CoFe Developer Guide

Cognos Finance Developer Guide 29-09-2006 Cognos Finance 7.
Type the text for the HTML TOC entry Cognos(R) Finance Developer Guide
DEVELOPER GUIDE
Cognos Finance
SOFTWARE DEVELOPMENT KIT DEVELOPER GUIDE
Product Information
This document applies to Cognos Finance Version 7.4 and may also apply to subsequent releases. To check for newer versions of this document, visit the Cognos Global Customer Services Web site (http://support.cognos.com).
Copyright
Copyright 2008 Cognos Incorporated. Portions of Cognos software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188 B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2; 6,995,768 B2; 7,062,479 B2; 7,072,822 B2; 7,111,007 B2; 7,130,822 B1; 7,155,398 B2; 7,171,425 B2; 7,185,016 B1; 7,213,199 B2; 7,243,106 B2; 7,257,612 B2; 7,275,211 B2; 7,281,047 B2; 7,293,008 B2. Cognos and the Cognos logo are trademarks of Cognos Incorporated in the United States and/or other countries. All other names are trademarks or registered trademarks of their respective companies. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to either the product or the document will be documented in subsequent editions. U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, or subparagraphs (C) (1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227-19, as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803. This software/documentation contains proprietary information of Cognos Incorporated. All rights are reserved. Reverse engineering of this software is prohibited. No part of this software/documentation may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos Incorporated.
Table of Contents
Introduction 7 Using This Document 7 Related Documentation 7 Chapter 1: Understanding and Using the Cognos Finance API 9 API Architecture in Cognos Finance 9 Using the Cognos Finance API 11 Using the Cognos Finance Add-in for Excel as an End-user 11 Using the Cognos Finance Add-in for Excel VBA Interface 12 Using the COM API as a Programmer Working External to Microsoft Excel 12 Chapter 2: Classes 13 Connect 13 CFAPI 13 CFAttribute 13 Name Property 14 Value Property 14 CFAttributes 15 Count Property 15 Item Function 15 CFConnection 15 Datadir Property 15 Discover Subroutine 16 InputDir Property 16 Mode Property 17 OutputDir Property 17 Port Property 17 Server Property 18 SysDesc Property 18 SysID Property 18 SysName Property 18 SysoutDir Property 19 SysRptsDir Property 19 UserRptsDir Property 19 CFConnections 20 Add Function 20 Count Property 20 Delete Subroutine 20 Item Function 21 CFData 21 Use the Batch Queue 21 BatchAddValue Subroutine 22 BatchGetValue Function 23 BatchPost Function 23 BatchTablesClear Subroutine 23 BatchUpdate Function 23 GetIceTargets Function 24 GetValue Function 24 GetValueEx Function 26 PostValue Function 27 Developer Guide 3
PostValueEx Function 28 GetErrorDescription Function 30 CFDimension 30 Count Property 30 DimId Property 30 DimName Property 30 DimType Property 30 DimTypeID Property 31 GetItemIDs Function 31 GetItemNames Function 31 Item Function 31 Picture Property 32 PasteFace Subroutine 32 CFDimensions 32 Count Property 32 GetDimIDs Function 32 GetDimNames Function 33 Item Function 33 NumCmps Property 33 NumTbls Property 33 CFErrItem 33 CellAddr Property 33 ErrCode Property 34 GetErrorDescription Function 34 Value Property 34 CFItem 34 Attributes Property 34 GetCalcString Function 34 GetChildren Property 35 GetLocked Property 35 GetParents Property 35 ItemID Property 36 ItemName Property 36 CFReport 36 Color Property 37 Columns Property 37 DependencySub Property 37 Dimensions Property 37 FileName Property 37 Filter Property 38 Pages Property 38 Rows Property 38 Scaling Property 38 Switchable Property 39 SysID Property 39 SysName Property 39 CFReports 39 Add Function 39 Clear Subroutine 40 Count Property 40 Item Function 40 Remove Subroutine 41 CFScreens 41 EditConnection Subroutine 41 Login Function 41 NewLocalConn Function 42 NewRemoteConn Function 42 4 Software Development Kit
SelectConnection Function 42 SelectDimension Function 43 SelectItems Function 43 CFSystem 43 ActiveConnection Property 44 Connections Property 44 Data Property 44 Dimensions Property 44 ErrLookup Function 44 Login Subroutine 44 Logout Subroutine 46 LogState Property 46 onLogin Event 46 onLogout Event 46 onPost Event 46 onUpdate Event 47 Reports Property 47 Screens Property 47 SysID Property 47 SysName Property 48 XLFormulas 48 XLInterface 48 CFMenuBarName Property 48 CFToolBarName Property 48 ConnectionDelete Subroutine 48 ConnectionEdit Subroutine 49 ConnectionNew Subroutine 49 DataPost Subroutine 49 DataUpdate Subroutine 49 GetCellsInError Function 50 Options Property 50 OptionsEdit Subroutine 50 PostCFI Subroutine 50 ShowErrorComment Subroutine 51 UpdateCFD Subroutine 51 UpdateCFI Subroutine 51 UpdateCFNAME Subroutine 52 XLMenuBarName (Hidden) Property 52 XLOptions 52 onChange Event 52 ReadNames Property 52 ReadOutput Property 53 SaveSettings Subroutine 53 UpdateInput Property 53 UpdateNames Property 53 Chapter 3: Enumerations 55 ErrCodes 55 errDimMismatch Constant 55 errDIIUnloaded Constant 55 errDupSystem Constant 55 errExcelAddin Constant 56 errExcelBusy Constant 56 errFailConnect Constant 56 errFailCreate Constant 56 errFailRegister Constant 57 errFailStart Constant 57
Developer Guide 5
errFailTransfer Constant 57 errInvalidAccArg Constant 57 errInvalidArrArg Constant 58 errInvalidCell Constant 58 errInvalidDirectory Constant 58 errInvalidLogin Constant 58 errInvalidNumArgs Constant 58 errInvalidObject Constant 59 errInvalidPerArg Constant 59 errInvalidReport Constant 59 errInvalidSub Constant 59 errInvalidSysId Constant 59 errInvalidSystem Constant 60 errInvalidTicket Constant 60 errInvalidValArg Constant 60 errInvalidXml Constant 60 errLoadDim Constant 60 errLoadingCache Constant 61 errLockedCell Constant 61 errMissingArg Constant 61 errNoConnections Constant 61 errNoDelimiter Constant 61 errNotLoggedIn Constant 62 errNTLogFail Constant 62 errTestFail Constant 62 errTieError Constant 62 errUnexpected Constant 63 TransferFilter 63 Appendix A: Sample VB Code 65 Make the Sample Code into an Executable Visual Basic Project 65 Sample File Login.frm 65 Sample File Main.frm 68 Index 83
Software Development Kit
Introduction
This document is intended for use with Cognos Finance. Cognos Finance provides a single financial view of enterprise information by consolidating multiple data sources, such as ledgers, spreadsheets, or manual input, into a dimensional chart-of-accounts structure. The consolidation process can calculate the effects of multiple reporting currencies, intercompany eliminations, and multitiered allocations, as well as calculate a wide range of financially intelligent metrics. In Cognos Finance, you can create and view reports, and distribute professional reports across the enterprise. You can also use Cognos Finance Web to distribute dynamic reports and collect data through a Web browser interface. Cognos Finance Add-In for Excel provides a simple toolbar and formula interface through Microsoft Excel, as well as a macro interface for customizing spreadsheet applications.
Using This Document

This guide describes how to use the Software Development Kit to access data from the Cognos Finance database. You can use the API contained in the Cognos Finance Software Development Kit to obtain values from the database and write values to the database.
Related Documentation
Our documentation includes user guides, getting started guides, new features guides, readmes, and other materials to meet the needs of our varied audience. The following documents contain related information and may be referred to in this document. Document Cognos Finance Add-In for Excel User Guide Description Connecting to the Cognos Finance database from Microsoft Excel and moving data between Excel workbooks and Cognos Finance databases
Integrating with Cognos Products

Cognos Finance is integrated with various Cognos products to provide a complete solution for analysis and reporting. For more information, please refer to the following integration material. Integration Cognos Finance and Cognos Planning Document Cognos Finance User Guide Cognos 8 Planning - Analyst User Guide Cognos Finance and Cognos PowerPlay Cognos Finance and Cognos Connection, Cognos Impromptu, Cognos Metrics Manager, or Cognos 8 Note: For integration with Cognos 8, you must install Cognos 8 Version 8.3 SP1 or later. Cognos Finance and Cognos Performance Applications Cognos Finance User Guide Cognos Finance User Guide Cognos Finance User Guide
Developer Guide 7
Introduction
Printing Copyright Materials

You can print selected pages, a section, or the whole book. Cognos grants you a non-exclusive, non-transferable license to use, copy, and reproduce the copyright materials, in printed or electronic format, solely for the purpose of operating, maintaining, and providing internal training on the Cognos software.
Chapter 1: Understanding and Using the Cognos Finance API

The Cognos Finance API resides in the cfxl.dll. It provides ways for accessing the Cognos Finance database, which includes financial, human resources, and statistical data and metadata. Specifically, the classes, methods, properties, events, subroutines, and constants in the Cognos Finance API provide ways to determine data structures, such as the number and type of data dimensions obtain metadata read data from the database post data to the database work with Microsoft Excel workbooks
API Architecture in Cognos Finance

The following diagram shows the overall API architecture. In this diagram, rectangular boxes indicate objects and classes. Ovals indicate properties, subroutines and events. The Connect object must be created by Microsoft Excel and provides access to the classes and methods in both the System class and the Interface class. CFAPI is a top-level object that is designed to be created by a programming language (Microsoft Excel does not exist in this environment).
Developer Guide 9
10
Using the Cognos Finance API

The Cognos Finance Application Programming Interface (API), which is found in the cfxl.dll file, has three main uses and types of users: the Cognos Finance Add-in for Excel, used by an end-user, not a programmer the Cognos Finance Add-in for Excel VBA interface COM API, used by a programmer working external to Microsoft Excel
Using the Cognos Finance Add-in for Excel as an End-user

In this environment, Microsoft Excel loads the cfxl.dll file as a COM add-in, which displays an interface in Microsoft Excel. The interface consists of a tool bar and menu with corresponding dialog boxes. The Excel end-user can now create reports and input forms that transfer data to and from the Cognos Finance database, using the Visual tools supplied through the add-in interface.
Example
Users familiar with the Cognos Finance Add-in for Excel know how to add dimensions to their worksheets, select items, add functions, such as CFD and CFI, and set references. The add-in can also be used to automate this process by refreshing and updating information. The excel_addin_dynamic report.xls sample that is provided with the GOS system shows how to automatically update data, which is shown based on a users security view, as the workbook is opened.
Developer Guide 11
Using the Cognos Finance Add-in for Excel VBA Interface

Used by a power-user who knows how to script in Microsoft Excel using VBA. Any action that can be taken by a user in Microsoft Excel with the Cognos Finance interface, can be invoked programmatically through the API interface. For example, a power user can write a script to log a user into a workbook and automatically post the contents of the workbook to the Cognos Finance database. Actions that the Excel user performs in the Microsoft Excel interface will raise events in the API, which the VBA programmer can trap and handle. This use of the API enables you to build very powerful financial applications inside Microsoft Excel.
Example
The excel_addin_GOS_Units Sold.xls sample that is provided with the GOS system shows how to set references and work with objects in the cfxl.dll. The sample sets local variables to object references in the cfxl.dll. This sample, also demonstrates how to check if a user is logged on and if not, prompts the user for a user name and password. It also demonstrates how to iterate through the Dimensions collection in the cfxl.dll.
Using the COM API as a Programmer Working External to Microsoft Excel

In this environment, Microsoft Excel is not involved at all and the functionality to work with Microsoft Excel does not exist. This approach requires more advanced programming. Rather than using the existing Cognos Finance COM object in Microsoft Excel, a programmer would create the Cognos Finance COM object in a programming language. Use this method to inspect the dimensional hierarchy of the Cognos Finance system retrieve data from or post data to the Cognos Finance database. integrate Cognos Finance with other applications In this scenario, if you have a proprietary system, the API could provide a way to programatically move data into and out of Cognos Finance database. If you are using .bat files or scripts to automate data import and export, the COM object can play a role in those scripts.
Example
Refer to "Sample VB Code" (p. 65) in the appendix for help with creating an executable example. The code in the appendix creates two forms that enable a user to log on to Cognos Finance and view individual data items from any Cognos Finance system. This sample program demonstrates how to use the API to perform the following functions: log on to a Cognos Finance system iterate through system connections obtain a list of the systems dimensions, as well as all the items in all the dimensions obtain the attributes of any item obtain children, parents, and calculation strings of any item load a report or input form into the API view the dimensional layout and selections of a report retrieve a value from and post a value to the database
12
Chapter 2: Classes
Classes are used to control connection, access attributes, and provide underlying support to the Cognos Finance application programming interface. By manipulating these classes, which include properties, subroutines, functions, and events, you can build customized applications that use the Cognos Finance database.
Connect
The Connect class is the top-level object of the cfxl.dll file designed to be loaded by Microsoft Excel. At this level, although there are no events, there are three objects: System When using the API, is always available. It provides access to the most common data values and system elements. Interface Controls the graphical user elements and is available only through Microsoft Excel. Microsoft Excel must make the COM object for Interface to be properly initialized. Formulas Provides access to account, component, and period formulas from the Cognos Finance database, and is available only through Microsoft Excel. Microsoft Excel must make the COM object for Formulas to be properly initialized. The Connect class uses references to the Microsoft Excel Object module, the Microsoft Excel type library, and the Microsoft Office type library. You must set references in those libraries. Because Connect uses Excel, you must import the libraries that Excel uses. Connect has extended functionality for VBA programmers working with Microsoft Excel. These include OnLogin onLogout onUpdate onPost
CFAPI
The CFAPI class is the top-level object of the cfxl.dll file designed to work outside Microsoft Excel. At this level, only the System object exists. When using the API, the System object is always available. It provides access to the most common data values and system elements. If you attempt to call the Interface or Formulas objects from the API and not through Microsoft Excel, an ErrExcelAddIn (p. 56) error occurs. The CFAPI object provides system access without the overhead of Microsoft Excel and Microsoft Office object libraries.
CFAttribute
The CFAttribute class contains the Name and Value properties, which return the names and values of item attributes in the Cognos Finance database. Developer Guide 13
Chapter 2: Classes
Name Property
Returns the name of an Item Attribute as a string data type. Read-only. The attributes collection is similar to the right pane in the Define Items main window. The item attributes in the collection are dependant on the type of dimension. For example, if the item comes from a Periods type dimension, it has an attribute named Pointer. However, if the item comes from an accounts type dimension and you tried to ask for the Pointer attribute a Subscript out of Range error occurs because Pointer is not a valid attribute of an account. Member of: CFXL.CFAttribute (p. 13) See also: CFDimension:DimTypeId (p. 31) to determine what type of attributes are available for this item.
Syntax
objConnect.System.Dimensions("DimensionName").Item("ItemName").Attributes(AttributeNa me).Name The following table lists types, IDs, and attributes for each dimension. Dimension type Submission Component Account Period Table
ID 1 2 3 4 5
Attributes Calc, Repair, Lock, JE, FY Start Date, Prior Year Sub, Budget Sub, Allow Scratch Pad, Allow Custom Pad Type, Class, [USER DEFINED ATTRIBUTES] DecPrec, Type, Round, Basis, Color, Pos Change, Class, Do ACT Calc, Do PER Calc, Pad Type Text, Calc, Pointer, Base Input, Prior [None]
Example
' For each attribute in the 2002 Actuals LC Item, print out the attributes name and value. Sub foo() Dim objAttr As CFAttribute Dim objItem As CFItem Set objItem = objConnect.System.Dimensions("Submissions").Item("2002_Act_LC") For Each objAttr In objItem.Attributes Debug.Print objAttr.Name & ": " & objAttr.Value Next objAttr End Sub
Value Property
Returns the value of an item attribute as a string data type. Read-only. The value of an attribute is always returned as a string. Some of these values may be converted to numeric or Boolean values, but the data type is string. Member of: CFXL.CFAttribute (p. 13)
Syntax
objConnect.System.Dimensions("Submissions").Item("2002_Act_LC").Attributes(1).Value
Example
' For each attribute in the 2002 Actuals LC Item, print out the attributes name and value.
14
Chapter 2: Classes
Sub foo() Dim objAttr As CFAttribute Dim objItem As CFItem Set objItem = objConnect.System.Dimensions("Submissions").Item("2002_Act_LC") For Each objAttr In objItem.Attributes Debug.Print objAttr.Name & ": " & objAttr.Value Next objAttr End Sub
CFAttributes
The CFAttributes class contains the Count and Item methods. The Count property is used to return the number of CFAttribute objects in a CFAttributes collection. The Item function returns CFAttribute objects and provides a way to examine item attributes from the Cognos Finance database.
Count Property
Returns the number of CFAttribute Objects in the CFAttributes collection as an integer data type. Read-only. Member of: CFXL.CFAttributes (p. 15)
Example
Dim objItem As CFItem Set objItem = objConnect.System.Dimensions("Submissions").Item("2002_Act_LC") For i = 0 to objCFItem.Attributes.Count objCFItem.Attributes.item(i) Next i
Item Function
Returns the specified CFAttribute object. Item can be indexed by position or by name. To determine at what point what names are valid, see CFAttribute:Name (p. 14). Because Item is the Default member of the CFAttributes class, objCFItem.Attributes.item(i) and objCFItem.Attributes(i) are synonymous. Member of: CFXL.CFAttributes (p. 15)
Syntax
item(index) As CFAttribute Argument index Description Either a number from 0 to CFAttributes:Count or a valid CFattribute:Name.
CFConnection
The CFConnection class, a member of the CFConnections collection, contains properties for determining and examining system connection information, such as system name, system ID, and the directories that are used to store system-specific data.
Datadir Property
Use the Datadir property to Get or Set the Cognos Finance data directory.
Developer Guide 15
Chapter 2: Classes Get returns the data directory for the current connection as a string data type. The data directory must already exist. The data directory is the data directory setting found in the lexw.ini file. Set must specify a valid directory or an errInvalidDirectory (p. 58) error occurs. Setting this property immediately writes the appropriate section to the lexw.ini file. If the data directory does not exist or cannot be accessed, an errInvalidDirectory (p. 58) error occurs. Member of: CFXL.CFConnection (p. 15)
Syntax
Datadir = path Argument path Description The path of the data directory
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.DataDir = "c:\wave\data"
Discover Subroutine
To identify the ID of the system to which remote connection points, the Discover subroutine pings the port of the server on which the target system is located. If the server is successfully pinged, it supplies the CFConnection object with the SYSID property and is recorded in the Lexw.ini file. If it does not successfully ping the server, errTestFail (p. 62) is raised. When creating a CFConnection object that points to a remote system, use this subroutine to test the connection and supply the value to the SYSID property. It uses the values of the Server (p. 18) and Port (p. 17) properties to attempt to connect to the system. The subroutine does not apply to a local connection. Member of: CFXL.CFConnection (p. 15)
Syntax
Discover ()
InputDir Property
Returns the input directory of the current connection as a string data type. The input directory must already exist. The input directory is determined by the input directory setting found in the lexw.ini file. If the input directory does not exist or cannot be accessed, an errInvalidDirectory (p. 58) error occurs. Setting this property immediately writes the appropriate section to the lexw.ini file. Member of: CFXL.CFConnection (p. 15)
Syntax
InputDir = path Argument path Description The path of the input directory
16
Chapter 2: Classes
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.InputDir = "c:\wave\input"
Mode Property
The Mode property switches between modes based on whether a system is local or remote. The data type set for this property is tmode enumeration, which passes the mLocal and mRemote values. Directory properties are used to connect to a local system, whereas the Server and Port properties are used to connect to the remote system. Member of: CFXL.CFConnection (p. 15)
Syntax
Mode () as tModes Argument tModes Description 0 = mLocal 1 = mRemote The connection defaults to 0, or local.
OutputDir Property
Returns the output directory of the current connection as a string data type. The output directory must already exist. The output directory is the output directory setting found in the lexw.ini file. If the output directory does not exist or cannot be accessed, an errInvalidDirectory (p. 58) error occurs. Setting this property immediately writes the appropriate section to the lexw.ini file. Member of: CFXL.CFConnection (p. 15)
Syntax
OutputDir = path Argument path Description The path of the output directory
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.OutputDir = "c:\wave\output"
Port Property
This property is the port on which the Cognos Finance system is listening on Cognos Finance Web Services. The server and port properties uniquely identify the computer and port on which the system is located. Each port on which Cognos Finance Web Services listens corresponds to a Cognos Finance system. Your application administrator configures Cognos Finance Web Services. Member of: CFXL.CFConnection (p. 15)
Developer Guide 17
Chapter 2: Classes
Syntax
Port As Long
Server Property
The Server property is the string name or IP address of the server where Cognos Finance Web Services is running. The server and port properties uniquely identify the computer and port on which the system is located. Each port on which Cognos Finance Web Services listens corresponds to a Cognos Finance system. Your application administrator configures Cognos Finance Web Services. Member of: CFXL.CFConnection (p. 15)
Syntax
Server As String
SysDesc Property
Returns the system description for the current connection as a string data type. The system description corresponds to the entry made in the Description box of the Define Cognos Finance Connection dialog box when the system was created. This information is also listed in the lexw.ini file. Member of: CFXL.CFConnection (p. 15)
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.SysDesc = "Wave System"
SysID Property
Returns the three-character system ID for this connection as a string data type. This property must be set using a three-character string that does not contain spaces, or an errInvalidSysID (p. 59) error occurs. The system ID corresponds to the entry made in the ID box of the Define Cognos Finance Connection dialog box when the system was created. This information is also listed in the [MENU] section of the lexw.ini file. If an invalid system ID is returned, an errInvalidSysID (p. 59) error occurs. Member of: CFXL.CFConnection (p. 15)
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("GOS") objConn.SysID = "GOS"
SysName Property
Returns the system name for this connection as a string data type. Read-only. SysName can be set only when adding a new connection. This property corresponds to the Section Name for this connection in the lexw.ini file. Use the SysName of a connection to index the CFConnections collection. Member of: CFXL.CFConnection (p. 15)
18
Chapter 2: Classes
SysoutDir Property
Returns the system output directory of the current connection as a string data type. The system output directory must already exist. The system output directory is the system output directory setting found in the lexw.ini file. If the system output directory does not exist or cannot be accessed, an errInvalidDirectory (p. 58) error occurs. Setting this property immediately writes the appropriate section to the lexw.ini file. Member of: CFXL.CFConnection (p. 15)
Syntax
SysoutDir = path Argument path Description The path of the system output directory
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.SysoutDir = "c:\wave\sysout"
SysRptsDir Property
Returns the system reports directory of the current connection as a string data type. The system reports directory must already exist. The system reports directory is the system reports directory setting found in the lexw.ini file. If the system reports directory does not exist or cannot be accessed, an errInvalidDirectory (p. 58) error occurs. Setting this property immediately writes the appropriate section to the lexw.ini file. Member of: CFXL.CFConnection (p. 15)
Syntax
SysRptsDir = path Argument path Description The path of the system reports directory
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.SysRptsDir = "c:\wave\sysrpts"
UserRptsDir Property
Returns the user reports directory of the current connection as a string data type. The user reports directory must already exist. The user reports directory is the user reports directory setting found in the lexw.ini file. If the user reports directory does not exist or cannot be accessed, an errInvalidDirectory (p. 58) error occurs. Setting this property immediately writes the appropriate section to the lexw.ini file. Member of: CFXL.CFConnection (p. 15)
Developer Guide 19
Chapter 2: Classes
Syntax
UserRptsDir = path Argument path Description The path of the user reports directory
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections("Wav") objConn.UserRptsDir = "c:\wave\userrpts"
CFConnections
The CFConnections Class is a collection of connection objects. Use the functions in this class to create, edit, or delete connections. Changes are written to the lexw.ini file, where they become part of a user profile.
Add Function
Creates and returns a new connection object. Connection information is written to the lexw.ini file. This function duplicates the function found in the Define Cognos Finance Connection dialog box. After providing a unique name, an entry in the lexw.ini file is added. The new connection object is returned, and you can use it to extract information for the creation of new directories. Setting these properties immediately creates a new section in the lexw.ini file. This function returns a reference to the newly created CFConnection object. Calling this function using a system name that already exists causes an errDupSystem (p. 55) error to occur. Member of: CFXL.CFConnections (p. 20)
Syntax
Add(SysName) Argument SysName Description The name of the system to be added. The name must be unique and must be a string data type. This name is used for the .ini section name for this system. This name is also used for indexing the CFConnections collection using the Item function.
Example
Dim objConn As CFConnection Set objConn = objConnect.System.Connections.Add("Wave")
Count Property
Returns the number of connection objects contained in a collection as an integer data type. Read-only. Member of: CFXL.CFConnections (p. 20)
Delete Subroutine
Deletes a specified connection object. The entry is removed from the lexw.ini file based on its unique name. This function also removes it from the menu and the Select Cognos Finance System dialog box.
20
Chapter 2: Classes Calling this function deletes the Connections section in the lexw.ini file. Member of: CFXL.CFConnections (p. 20)
Syntax
Delete(SysName) Argument SysName Description The name of the system to be deleted
Example
objConnect.System.Connections.Delete("Wave")
Item Function
Selects a specific connection object. This object is the default member for this class. Member of: CFXL.CFConnections (p. 20)
Syntax
item(index) As CFConnection Argument index Description The assigned number value of the connection object, which must be a number between 1 and count or a valid system name
Example
Set objConn = objConnect.System.Connections.item("Wave") ' Or Set objConn = objConnect.System.Connections("Wave")
CFData
The CFData class contains functions that control batch handling. These include BatchTablesClear, which clears the queue BatchAddValue, which adds a single data item to the queue BatchUpdate, which reads data out of the Cognos Finance database BatchPost, which inputs data into the Cognos Finance database BatchGetValue, which gets a value out of the queue
Use the Batch Queue

The batch queue takes individual unrelated data items and posts or updates them at the same time.
Steps
1. Call BatchTablesClear to clear out all the data items in the queue. 2. Call BatchAddValue repeatedly for each data item. If the intent is to post values, supply the Value argument to BatchAddValue. Each data item is added to the queue and assigned a unique ID that you supply. 3. Choose whether to update the queue with numbers from the database or numbers supplied by the Value argument. To update the queue with numbers stored in the database, call BatchUpdate. Developer Guide 21
Chapter 2: Classes To update the database with numbers you supplied for the Value argument, call BatchPost. If False is returned, errors were encountered. 4. Call BatchGetValue to retrieve the values or error messages associated with each data item.
BatchAddValue Subroutine
Adds a data item (tuple) to the Batch Queue through the use of IDs. By assigning your own unique ID as a string data type, you identify and can use the item in programming. If the number of dimensions that you supply does not match the number of dimensions in the system, an errDimMismatch (p. 55) error occurs. Member of: CFXL.CFData (p. 21)
Syntax
BatchAddValue(UniqueID, Dimensions(), [Value], [flags]) Argument UniqueID Description UniqueID As String. This unique string is used as an argument to BatchGetValue to retrieve the value of this data item after updating or posting the queue. Dimensions() As Variant. This argument is an array containing the same number of elements as there are dimensions in the system. This argument is required only if the intent is to post the queue. The flags argument is optional and controls three properties: color, YTD indicator, and scale. If omitted, the flags default to Array("S", "M", 0). Position is important. Attributes must be in the prescribed order, enclosed in double quotation marks and separated by a comma, such as "color","YTD indicator","scale". Any option can be blank, but it must be represented by a comma. The defaults are the same as those found in Microsoft Excel. Color, which can be either s for statement or a for account balance, defaults to s. The YTD indicator, which can be m for monthly or y for YTD, defaults to m. Scale, which can be 0 for whole currency, 1 for tens, 2 for hundreds, 3 for thousands, 6 for millions, or 9 for billions defaults to 0.
Dimensions() Value flags
Example
Dim objConnect As CFXL.Connect Set objConnect = Excel.Application.COMAddIns("CFXL.Connect").Object Dim dimArgs(0 To 6) As Variant dimArgs(0) = "2001_Act_LC" dimArgs(1) = "100" dimArgs(2) = "AMX" dimArgs(3) = "100100" dimArgs(4) = "TOT" dimArgs(5) = "TOT" dimArgs(6) = "Jan" objConnect.System.Data.BatchAddValue "tup1", dimArgs
22
Chapter 2: Classes
BatchGetValue Function
Returns the value of a data item from the batch queue based on its unique ID. If a data item was in error, this function returns the appropriate #CF* error code. A data item may be in error for many reasons. For example, if one of the selected dimension items was locked or did not exist, you would not be able to post that data item. Member of: CFXL.CFData (p. 21) See also: BatchAddValue (p. 22)
Syntax
BatchGetValue(UniqueID) Argument UniqueID Description A unique ID of the data type string. This argument is the same Unique ID that was supplied for the data item when calling BatchAddValue.
BatchPost Function
Posts the values from the Batch Queue to the Cognos Finance database. It returns, as a boolean data type, the success or failure of the post operation, as follows: If all values were posted successfully, True is returned. If the operation failed, False is returned. You must call BatchGetValue for each data item to identify if it yielded an error. Member of: CFXL.CFData (p. 21) See also: BatchGetValue (p. 23)
Syntax
BatchPost() As Boolean
BatchTablesClear Subroutine
Resets the batch queue for a new transfer by clearing the internal collection used to store the data item for a transfer. Before using the queue call this function to ensure that the transfer buffer is clear and that erroneous data is not being posted to the database. Member of: CFXL.CFData (p. 21)
Syntax
BatchTablesClear()
BatchUpdate Function
Updates the values in the Batch Queue from the Cognos Finance database. It returns, as a boolean data type, the success or failure of the update operation. If True is returned, the operation was successful; if False, the operation failed. If the update operation fails, use BatchGetValue to retrieve the error code, which is returned in place of the value. Member of: CFXL.CFData (p. 21) See also: BatchGetValue (p. 23)
Syntax
BatchUpdate() As Boolean
Developer Guide 23
Chapter 2: Classes
GetIceTargets Function
Retrieves the intercompany targets for a data item. This function is used to determine the valid intercompany targets for a data item. The arguments must be passed through a parameter array (PA), which consists of the submission, component, account and period dimensions. Because ICE targets do not use table dimensions, these are excluded from the array. Both accounts and periods can be arrays and are referenced in the parameter array. If the correct number of arguments, equal to the total number of submission, account, period, and component dimensions, is not supplied in the arguments, an errInvalidNumArgs (p. 58) error occurs. The result of this function is a collection of CFDimensions Objects, each of which represents a valid Intercompany target. Each CFDimensions object contains a number of CFDimension objects that equals the number of component dimensions in the system. Each CFDimension object contains one CFItem object. The CFItem object is the valid target for that dimension. Member of: CFXL.CFData (p. 21)
Syntax
GetIceTargets(ParamArray pa() As Variant) As Collection Argument ParamArray() Description Dimensions: array(Submission, Account, Components, Period) The number of dimensions to be supplied is the number of component dimensions in the system plus one submission, one account and one period. This is the number of dimensions minus tables. If an incorrect number of dimensions is supplied, an errInvalidNumArgs error occurs. If there was an error loading the intercompany elimination information (usually because one or more of the dimensions arguments is invalid), an errLoadDim error occurs.
Example
Dim objConnect As CFXL.Connect Set objConnect = Excel.Application.COMAddIns("CFXL.Connect").Object Dim dimArgs(0 To 4) As Variant dimArgs(0) = "2001_Act_LC" dimArgs(1) = "101-60" dimArgs(2) = "BUS" dimArgs(3) = "EL_405510" dimArgs(4) = "Jan" Dim colTargets As Collection Set colTargets = objConnect.System.Data.GetIceTargets(dimArgs) Dim objCFDims As CFDimensions Dim objCFDim As CFDimension For Each objCFDims In colTargets Debug.Print "Intercomany Target" For Each objCFDim In objCFDims Debug.Print "Dimension: " & objCFDim.DimName Debug.Print "Item: " & objCFDim(1).ItemName Next objCFDim Next objCFDims
GetValue Function
There is an extended version of the GetValue function, GetValueEx. Use the GetValueEx (p. 26) function for any new development. The GetValue function has been retained for purposes of backward compatibility.
24
Chapter 2: Classes GetValue retrieves a single value, array, or matrix of data from the Cognos Finance database. The Dimensions argument needs to match the order in the system, which is found in the Define Items module. Depending on the argument, a scalar, vector, or two-dimensional matrix of data can be retrieved. If a single item is selected for the accounts and periods dimensions, the result is a single value. If an array is supplied for the accounts or periods elements, the result is an array of values the same length as the array created for the accounts or periods element. If an array is supplied for both accounts and periods, a two-dimensional matrix returns n number of accounts high by m number of periods wide. The values themselves are either valid values in the database or #CF* error codes. If an error code is encountered, the GetErrorDescription function decodes the error into a helpful string. If the number of dimensions supplied is not the same as in the system, an errDimMismatch (p. 55) error occurs. If the order of dimensions is not the same as in the system, for example in the Define Items module listing, #CF errors are generated and returned as part of the result. If any argument, other than accounts or periods, is an array, an errInvalidArrArg (p. 58) error occurs. Only periods and accounts can be arrays. Member of: CFXL.CFData (p. 21) See also: GetValueEx (p. 26)
Syntax
GetValue(Dimensions, [flags]) Argument Dimensions Description The Dimensions argument takes as parameters all the dimensions in a Cognos Finance system. They must appear in the same order as they appear in the Define Items module. An array containing the same number of elements as there are dimensions in the system. If any other number of elements is supplied, an errDimMismatch (p. 55) error occurs. The Accounts or Periods elements of this array can also be arrays. If an array is supplied for an element that is not an Account or Period type dimension, an errInvalidArrArg (p. 58) error occurs. If your system contains one component dimension and two table dimensions, the dimensions argument is: Array(Sub, Cmp1, Acc, Tbl1, Tbl2, Per) The Acc and Per elements can be arrays as well. flags The flags argument is optional and controls three properties: color, YTD indicator, and scale. If omitted, the flags default to Array("S", "M", 0). Position is important. Attributes are the elements in the array. Each value of the element is represented as a text string and separated by a comma, such as color, YTD indicator, scale. Any option can be blank, but it must be represented by a comma. The defaults are the same as those found in Microsoft Excel. Color, which can be either s for statement or a for account balance, defaults to s. The YTD indicator, which can be m for monthly or y for YTD, defaults to m. Scale, which can be 0 for whole currency, 1 for tens, 2 for hundreds, 3 for thousands, 6 for millions, or 9 for billions, defaults to 0.
Developer Guide 25
Chapter 2: Classes
GetValueEx Function
Retrieves a single value, array, or n-dimensional matrix of data from the Cognos Finance database. The Dimensions argument needs to match the order in the system, which is found in the Define Items module. Depending on the argument, a scalar, vector, or n-dimensional matrix of data can be retrieved. The GetValueEx function provides flexibility that GetValue does not. GetValueEx extends capabilities by enabling you to work with multi-dimensional data. This flexibility can, however, make the arguments and result of the function more complex. The Dimensions argument is an array of items for each dimension in the system. The shape and rank of the elements of this array define the result. For example, if a single item is selected for each dimension, then the result is a scalar value. If an array is supplied for one dimension, then the result is an array of values the same length. If an array was supplied for two elements of the dimensions argument, the result is a two-dimensional matrix, where the first dimensions element that is an array is placed on the rows of the matrix and the second is placed on the columns. Using GetValueEx any element of the dimensions argument can be passed as an array, with the exception of the submissions element. If the number of dimensions supplied is not the same as in the system, an errDimMismatch (p. 55) error occurs. If the order of dimensions is not the same as in the system, for example in the Define Items module listing, #CF errors are generated and returned as part of the result. Use the GetErrorDescription function (p. 34) to decode the error into a helpful string. If the submission argument is an array, an errInvalidArrArg (p. 58) error occurs. The submission dimension is the only dimension that cannot be an array; it must be a single value. Member of: CFXL.CFData (p. 21)
Syntax
GetValueEx(Dimensions, [flags]) Argument Dimensions Description The Dimensions argument takes as parameters all the dimensions in a Cognos Finance system. They must appear in the same order as they appear in the Define Items module. An array containing the same number of elements as there are dimensions in the system. If any other number of elements is supplied, an errDimMismatch (p. 55) error occurs. All but the submission element can be arrays. If an array is supplied for the submission dimension, an errInvalidArrArg (p. 58) error occurs. If your system contains one component dimension and two table dimensions, the dimensions argument is: Array(Sub, Cmp1, Acc, Tbl1, Tbl2, Per) The Cmp1, Acc, Tbl1, Tbl2, and Per elements can be arrays as well. flags The flags argument is optional and controls item properties: color, YTD indicator, and scale. Position is important. Attributes must be in the prescribed order, enclosed in double quotation marks and separated by a comma, such as "color","YTD indicator","scale". Any option can be blank, but it must be represented by a comma. The defaults are the same as those found in Microsoft Excel. Color, which can be either s for statement or a for account balance, defaults to s. The YTD indicator, which can be m for monthly or y for YTD, defaults to m. Scale, which can be 0 for whole currency, 1 for tens, 2 for hundreds, 3 for thousands, 6 for millions, or 9 for billions defaults to 0.
26
Chapter 2: Classes
Results
The result from GetValueEx is always a three-element array. The first element is a scalar flag that specifies if an error occurred. If the flag is 0 (zero) then no errors were encountered. If the flag is 1 (one) then errors exist. Check the third element for the errors. The second element is a variant structure containing the values of the data items you were attempting to get from the database. The shape and rank of this element is defined by the Dimensions argument. The third element of the result array is an array of errors. The number of elements in this array are the number of errors that were encountered. Each error in the array is also an array. The first element of the error array returns the error code, such as #CFIN3. The second through n (1 + number of dimensions) elements are the IDs for the data items in error. The last element is 0 (zero).
------------------------------------------------------------| #CFIN3 | AC94 | NJ | Modems | Sales | Jan | 0 | -------------------------------------------------------------
PostValue Function
There is an extended version of the PostValue function, PostValueEx. Use the PostValueEx (p. 28) function for any new development. The PostValue function has been retained for purposes of backward compatibility. PostValue posts a single value, array, or matrix of data to the Cognos Finance database. Depending on the argument, a scalar, vector, or two-dimensional matrix of data can be posted. The result of this function is an array of errors. If the array has 0 elements, no errors were encountered. If errors are encountered, each element of the result array is a three-element array consisting of account, period, and the error code. The following table shows that three errors were encountered. For each of the errors, you can rebuild the data item (tuple) using the original dimensions argument you supplied and the specific account and period specified in the error. 100100 | Jan | #CFIN7 100100 | Feb | #CFIN4 100100 | Jan | #CFIN7
If the number of dimensions supplied is not the same as in the system, an errDimMismatch (p. 55) error occurs. If the order of dimensions is not the same as in the system, for example in the Define Items module listing, #CF errors are generated and returned as part of the result. If the submission argument is an array, an errInvalidArrArg (p. 58) error occurs. Only periods and accounts can be arrays. Member of: CFXL.CFData (p. 21) See also: PostValueEx (p. 28)
Developer Guide 27
Chapter 2: Classes
Syntax
PostValue(Dimensions, Value, [flags]) Argument Dimensions Description The Dimensions argument takes as parameters all the dimensions in a Cognos Finance system. They must appear in the same order as they appear in the Define Items module. An array containing the same number of elements as there are dimensions in the system. If any other number of elements is supplied, an errDimMismatch (p. 55) error occurs. The Accounts or Periods elements of this array can also be arrays. If an array is supplied for an element that is not an Account or Period type dimension, an errInvalidArrArg (p. 58) error occurs. If your system contains one component dimension and two table dimensions, the dimensions argument is: Array(Sub, Cmp1, Acc, Tbl1, Tbl2, Per) The Acc and Per elements can be arrays as well. Value The Value argument directly relates to what type of information is sent for the Dimensions argument. It can be the value of a single data item (tuple) or an array or matrix of values. The shape and rank of this argument is based on the Dimensions argument. If a single item is selected for the accounts and periods dimensions, the value should be a scalar. If an array is supplied for the accounts or periods elements, the value should be an array of values the same length as the array created for the accounts or periods element. If an array is supplied for both accounts and periods, the value should be a two-dimensional matrix n number of accounts high by m number of periods wide. flags The flags argument is optional and controls item properties: color, YTD indicator, and scale. Position is important. Attributes must be in the prescribed order, enclosed in double quotation marks and separated by a comma, such as "color","YTD indicator","scale". Any option can be blank, but it must be represented by a comma. The defaults are the same as those found in Microsoft Excel. Color, which can be either s for statement or a for account balance, defaults to s. The YTD indicator, which can be m for monthly or y for YTD, defaults to m. Scale, which can be 0 for whole currency, 1 for tens, 2 for hundreds, 3 for thousands, 6 for millions, or 9 for billions defaults to 0.
PostValueEx Function
Posts a single value, array, or matrix of data to the Cognos Finance database. Depending on the argument, a scalar, vector, or n-dimensional matrix of data can be posted. If the number of dimensions supplied is not the same as in the system, an errDimMismatch (p. 55) error occurs. If the order of dimensions is not the same as in the system, for example in the Define Items module listing, #CF errors are generated and returned as part of the result. Use the GetErrorDescription function (p. 34) to decode the error into a helpful string. If the submission argument is an array, an errInvalidArrArg (p. 58) error occurs. The submission dimension is the only dimension that cannot be an array; it must be a single value. Member of: CFXL.CFData (p. 21)
28
Chapter 2: Classes
Syntax
PostValueEx(Dimensions, Value, [flags]) Argument Dimensions Description The Dimensions argument takes as parameters all the dimensions in a Cognos Finance system. They must appear in the same order as they appear in the Define Items module. An array containing the same number of elements as there are dimensions in the system. If any other number of elements is supplied, an errDimMismatch (p. 55) error occurs. All but the submission element can be arrays. If an array is supplied for the submission dimension, an errInvalidArrArg (p. 58) error occurs. If your system contains one component dimension and two table dimensions, the dimensions argument is: Array(Sub, Cmp1, Acc, Tbl1, Tbl2, Per) The Cmp1, Acc, Tbl1, Tbl2, and Per elements can be arrays as well. Value The Value argument directly relates to what type of information is sent for the Dimensions argument. It can be the value of a single data item (tuple) or an array or matrix of values. The shape and rank of this argument is based on the Dimensions argument. If a single item is selected for all dimensions, the resulting value is a scalar. If an array is supplied for one element, the resulting value is an array of values the same length as the array created for that element. If an array is supplied for two elements, the resulting value is a two-dimensional matrix, m number of rows high by n number of columns wide. If an array is supplied for three elements, the resulting value is a three-dimensional matrix m number of pages deep, by n number of rows high, by o number of columns wide. If an array is supplied for n elements, the resulting value is an n-dimensional matrix. flags The flags argument is optional and controls item properties: color, YTD indicator, and scale. Position is important. Attributes must be in the prescribed order, enclosed in double quotation marks and separated by a comma, such as "color","YTD indicator","scale". Any option can be blank, but it must be represented by a comma. The defaults are the same as those found in Microsoft Excel. Color, which can be either s for statement or a for account balance, defaults to s. The YTD indicator, which can be m for monthly or y for YTD, defaults to m. Scale, which can be 0 for whole currency, 1 for tens, 2 for hundreds, 3 for thousands, 6 for millions, or 9 for billions defaults to 0.
Results
The result from PostValueEx is always a three-element array. The first element is a scalar flag that specifies if an error occurred. If the flag is 0 (zero) then no errors were encountered. If the flag is 1 (one) then errors exist. Check the third element for the errors. The second element is a variant structure containing the values of the data items you were attempting to post to the database. The shape and rank of this element is defined by the Dimensions argument.
Developer Guide 29
Chapter 2: Classes The third element of the result array is an array of errors. The number of elements in this array are the number of errors that were encountered. Each error in the array is also an array. The first element of the error array returns the error code, such as #CFIN3. The second through n (1 + number of dimensions) elements are the IDs of the items for the data item in error. The last element is the value you attempted to post. For a system that has five dimensions, if you were trying to post the value 22 to the data item AC94 NJ Modems Sales Jan and an error occurred because Modems was locked, the error array would look like this:
------------------------------------------------------------| #CFIN3 | AC94 | NJ | Modems | Sales | Jan | 22 | -------------------------------------------------------------
GetErrorDescription Function
Translates error codes from the PostValue or GetValue function, such as #CFIN6, into descriptive text that explains the error. Use this text to show to a user or write to an error log file. Member of: CFXL.CFData (p. 21) See also: CFErrItems (p. 33), GetErrorDescription (p. 34)
CFDimension
The CFDimension class, a member of the CFDimensions collection, contains methods for examining dimensions, such as submissions, accounts, components, or periods in the Cognos Finance database.
Count Property
Returns the number of CFDimension objects in the CFDimensions class as an integer data type. Read-only. Member of: CFXL.CFDimension (p. 30)
DimId Property
Returns the ID of the dimension as a string data type, such as Subs. Read-only. Member of: CFXL.CFDimension (p. 30)
DimName Property
Returns the dimension name of a dimension as a string data type, such as Submissions. Read-only. Member of: CFXL.CFDimension (p. 30)
DimType Property
Returns the type name of the dimension as a string data type. Read-only. Possible values are Submissions Components Accounts Periods Tables Member of: CFXL.CFDimension (p. 30)
30
Chapter 2: Classes
DimTypeID Property
Returns the numeric type ID of a dimension as an integer data type. Use this property when checking for a specific type of dimension. Possible values are 1 through 5. Read-only. Member of: CFXL.CFDimension (p. 30) This table summarizes the dimension type IDs. Dimension Submissions Components Accounts Periods Tables Type ID 1 2 3 4 5
Example
Dim objCFDim As CFDimension For Each objCFDim In objConnect.System.Dimensions If 2 = objCFDim.DimTypeID Then Debug.Print objCFDim.DimName & " is a component type dimension." End If Next objCFDim
GetItemIDs Function
Returns an array of the ItemID property (p. 36) for each of the CFItem objects (p. 34) in the CFDimension object. Use this function as an alternative to iterating through the CFItem objects to build a list of the item IDs. Member of: CFXL.CFDimension (p. 30)
Syntax
GetItemIDs()
GetItemNames Function
Returns an array of the ItemName property (p. 36) for each of the CFItem objects in this CFDimension object. Use this function as an alternative to iterating through the CFItem objects to build a list of the item names. Member of: CFXL.CFDimension (p. 30)
Syntax
GetItemNames()
Item Function
Selects a specific item in a dimension. This is the default member for this class. Member of: CFXL.CFDimension (p. 30)
Developer Guide 31
Chapter 2: Classes
Syntax
item(index) As CFItem Argument index Description A number between 1 and count or a valid item name
Picture Property
Exposes the StdPicture bitmap. The bitmap is a graphical representation of any of the several data dimensions that make up the selected Cognos Finance system. The bitmaps or icons are originally assigned by the application administrator. Read-only. The bitmaps are read from the resource file, Lexw.dll. Member of: CFXL.CFDimension (p. 30)
Syntax
Picture As StdPicture
PasteFace Subroutine
To customize Office.CommandBarButton Objects, you must call this subroutine on the appropriate CFDimension object by using the built-in dimension icons, which are shown on the Cognos Finance dimension buttons. You can then pass a reference to the button object you want. The selected icon is automatically placed on your button object. Member of: CFXL.CFDimension (p. 30)
Syntax
PasteFace (objButton As Object)
CFDimensions
The CFDimensions class contains the Count and Item methods. The Count property returns the number of dimensions in a system. The Item Function enables you to select a specific dimension in the current system.
Count Property
Returns the number of dimensions in a system as an integer data type. Read-only. You must be logged on to the system to return the number of dimensions. If you are not logged on to a system, an errNotLoggedIn (p. 62) error occurs. Member of: CFXL.CFDimensions (p. 32)
GetDimIDs Function
Returns an array of the DimID property (p. 30) for each of the CFDimension objects in the CFDimensions collection. Use this function as an alternative to iterating through the CFDimension objects to build a list of the dimension IDs. Member of: CFXL.CFDimensions (p. 32)
Syntax
GetDimIDs()
32
Chapter 2: Classes
GetDimNames Function
Returns an array of the DimName property (p. 30) for each of the CFDimension objects in the CFDimensions collection. Use this function as an alternative to iterating through the CFDimension objects to build a list of the dimension names. Member of: CFXL.CFDimensions (p. 32)
Syntax
GetDimNames()
Item Function
Selects a specific dimension in the current system. Member of: Default member of CFXL.CFDimensions (p. 32)
Syntax
item(index) As CFDimension Argument index Description The assigned number value of the dimension
NumCmps Property
Returns the number of component dimensions in the current system. Use this property as an alternative to iterating through the CFDimension object and evaluating the DimTypeID property (p. 31). Read only. Member of: CFXL.CFDimensions (p. 32)
Syntax
NumCmps As Long
NumTbls Property
Returns the number of table dimensions in the current system. Use this property as an alternative to iterating through the CFDimension object and evaluating the DimTypeID property (p. 31). Member of: CFXL.CFDimensions (p. 32)
Syntax
NumTbls As Long
CFErrItem
The CFErrItem class contains methods for examining errors that occur in Microsoft Excel workbooks and the API.
CellAddr Property
Returns the location of the cell in error. Read-only. Gives the worksheet, column, and row of the active workbook. Member of: CFXL.CFErrItem (p. 33)
Developer Guide 33
Chapter 2: Classes
Syntax
CellAddr
ErrCode Property
Returns the Cognos Finance error code for an error item. Read-only. Member of: CFXL.CFErrItem (p. 33)
GetErrorDescription Function
Returns the error diagnostic message associated with an error as a string data type. Read-only. Member of: CFXL.CFErrItem (p. 33)
Syntax
GetErrorDescription()
Value Property
Returns the #CF error code that appears in a cell as a variant data type. Read-only. Member of: CFXL.CFErrItem (p. 33)
CFItem
The CFItem class contains functions and properties that provide item attributes, such as lock status, calculations, children, and parents.
Attributes Property
Returns a collection of item attributes as a CFAttributes data type, which is a type of collection. Read-only. Names of attributes are keys. Member of: CFXL.CFItem (p. 34)
GetCalcString Function
Returns the calculation of an item from a specific submission as a string data type, such as @SUM( "700700" "700800" "700900" ). You can retrieve a calculation string even for items not in your view. Member of: CFXL.CFItem (p. 34)
Syntax
GetCalcString([subID]) Argument subID Description The submission ID, as a string data type, from which to retrieve the calculation of an item. The submission ID should not be supplied if called from a dimension type 1 (Submission). Otherwise, submission ID is required. If not supplied, an errLoadingCache (p. 61) error occurs. The submission ID specifies which submission hierarchy to use for the data request. It is the equivalent of selecting the submission when opening a dimension in the Define Items module.
34
Chapter 2: Classes
GetChildren Property
Returns the children of an item as a CFDimension data type, which is a collection of items. The returned CFDimension collection does not have a valid DimName, DimID, DimType, or DimTypeID. It is a simple collection. Member of: CFXL.CFItem (p. 34)
Syntax
GetChildren([subID]) As CFDimension Argument subID Description The Submission ID as a string data type. The submission ID should not be supplied if called from a dimension type 1 (Submission). Otherwise, submission ID is required. If not supplied, an errLoadingCache (p. 61) error occurs. The submission ID specifies which submission hierarchy to use for the data request. It is the equivalent of selecting the submission when opening a dimension in the Define Items module.
Example
For Each objCFItem In objSystem.Dimensions("Accounts").Item("100000").GetChildren("2001_Act_LC") Debug.Print objCFItem.ItemName Next objCFItem
GetLocked Property
Indicates whether an item in a specific submission is locked by returning a result of y or n. The subID argument is required for items other than submissions. Member of: CFXL.CFItem (p. 34)
Syntax
GetLocked([subID]) As Boolean Argument subID Description The Submission ID as a string data type. Although not required for submissions, it is required for all other dimensions. The submission ID should not be supplied if called from a dimension type 1 (Submission). Otherwise, submission ID is required. If not supplied, an errLoadingCache (p. 61) error occurs. The submission ID specifies which submission hierarchy to use for the data request. It is the equivalent of selecting the submission when opening a dimension in the Define Items module.
GetParents Property
Returns the parents of an item in a specified submission as a CFDimension data type. The CFDimension data type is a collection and can, in this case, include multiple parents. The returned CFDimension collection does not have a valid DimName, DimID, DimType, or DimTypeID. It is a simple collection. Member of: CFXL.CFItem (p. 34)
Developer Guide 35
Chapter 2: Classes
Syntax
GetParents([subid]) As CFDimension Argument subid Description The Submission ID as a string data type. The submission ID should not be supplied if called from a dimension type 1 (Submission). Otherwise, submission ID is required. If not supplied, an errLoadingCache (p. 61) error occurs. The submission ID specifies which submission hierarchy to use for the data request. It is the equivalent of selecting the submission when opening a dimension in the Define Items module.
Example
For Each objCFItem In objSystem.Dimensions("Accounts").Item("100000").GetParents("2001_Act_LC") Debug.Print objCFItem.ItemName Next objCFItem
ItemID Property
Returns the ID for an item as a string data type, such as EL_405510. Read-only. Member of: CFXL.CFItem (p. 34)
ItemName Property
Returns the name of an item as a string data type, such as Services: Consulting - Intercompany. Read-only. Member of: CFXL.CFItem (p. 34)
CFReport
Loads reports without logging on to the Cognos Finance system. This can be used to acquire the system ID, system name, and file name associated with a report. When a report is added to the collection, only the Sysid, SysName, and Filename are readily available. You do not need to be logged on to the system to which this report belongs to access these three properties. Use the acquired information to choose and log onto a specific Cognos Finance system. Calling properties other than SysId, SysName and FileName causes a report to attempt to load it's data using the system that you are currently logged on to: The properties in this class can all cause the following errors: If you are not logged on to a system or the report cannot load its data, an errNotLoggedIn (p. 62) error occurs. If the report is unable to load because its path and file name are no longer valid or the report is currently exclusively used by some other process, an errTieError (p. 62) error occurs. If the report is not a valid Cognos Finance report or input form, an errInvalidReport (p. 59) error occurs. If the number of dimensions in the report and the number of dimensions in the system do not match, an errDimMismatch (p. 55) error occurs. If an error is encountered loading the data for this report, an errLoadDim (p. 60) error occurs. Member of: CFReports (p. 39)
36
Chapter 2: Classes
Color Property
Returns the color attribute of a report, either account or statement, as a string data type. Values can be Account or Statement where a=Account and s=Statement. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Columns Property
Returns a CFDimensions object, which is a collection of the dimensions that are located on columns for the loaded report. Use this property to determine which dimensions are on columns and to use the items in those dimensions. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Example
Dim objRpt As CFReport, objDim As CFDimension For Each objDim In objRpt.Columns Print objDim.DimName Next objDim
DependencySub Property
Returns the ID of the submission, as a string data type, used for the Dependency Hierarchy. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Dimensions Property
Returns a CFDimensions object, which is a collection of the dimensions that are located on pages, rows, columns, and the dimension bar, also known as the filter bar, for the loaded report. Use this property to access the items selected on this report for each dimension in this system. The order of the dimensions in this collection may not match the order in the System.Dimensions object. You must index by name if you are looking for a specific dimension. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve a collection of the dimensions on pages, rows, columns and the dimension bar from the first report in the Reports collection.
objDimDimensions = objConnect.System.Reports(1).Dimensions
FileName Property
Returns the file name of the loaded report as a string data type. This is the fully qualified path and file name used for adding the report to the collection. Read-only. This property is always available and does not prompt the report to load its data. Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve the path and file name of the first report in the Reports collection.
strFileName = objConnect.System.Reports(1).FileName
Developer Guide 37
Chapter 2: Classes
Filter Property
Returns a CFDimensions object, which is a collection of the dimensions that are located on the dimension bar, also known as the filter bar, for the loaded report. Use this property to determine which dimensions are on the filter bar and to access the items in those dimensions. Dimensions that are on the filter bar should only have one item selected for each dimension. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve a collection of the dimensions on the dimension bar from the first report in the Reports collection.
objDimensionsOnFilter = objConnect.System.Reports(1).Filter
Pages Property
Returns a CFDimensions object, which is a collection of the dimensions that are located on pages for the loaded report. Use this property to determine which dimensions are on pages and to access the items in those dimensions. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve a collection of the dimensions on pages from the first report in the Reports collection.
objDimensionsOnPages = objConnect.System.Reports(1).Pages
Rows Property
Returns a CFDimensions object, which is a collection of the dimensions that are located on rows for the loaded report. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Use this property to determine which dimensions are on rows and to access the items in those dimensions. Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve a collection of the dimensions on rows from the first report in the Reports collection.
objDimensionsOnRows = objConnect.System.Reports(1).Rows
Scaling Property
Returns the scaling attribute for the loaded report as a string data type. A number between 0 and 9. Read-only. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve the scaling property from the first report in the Reports collection.
strScaling = objConnect.System.Reports(1).Scaling
38
Chapter 2: Classes
Switchable Property
Returns the switchable attribute for the loaded report as a string data type. Values can be YTD, Switchable, or Monthly where Y=YTD, S=Switchable, and M=Monthly. Read-only. Use this property to retrieve the Switchable Accounts option used for the report. Calling this property causes the report to load its data. For more information, see "CFReport" (p. 36). Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve the switchable attribute from the first report in the Reports collection.
strSwitchable = objConnect.System.Reports(1).Switchable
SysID Property
Returns the system ID associated with the loaded report as a string data type. Read-only. This property is always available and does not prompt the report to load its data. Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve the system ID from the first report in the Reports collection.
strSysID = objConnect.System.Reports(1).SysID
SysName Property
Where a connection exists, returns the name of a system associated with a system ID as a string data type. This property is always available and does not prompt the report to load its data. This is the name of the system connection defined in the connections class that would load this system ID. The result of this property can be used as a parameter to the System.Login subroutine (p. 44). If you don't have a connection set up for this system ID, an errInvalidSystem (p. 60) error occurs. Member of: CFXL.CFReport (p. 36)
Example
The following example shows you how to retrieve the system name from the first report in the Reports collection.
strSysName = objConnect.System.Reports(1).SysName
CFReports
The CFReports class is a collection of reports (.lrf) and input forms (.lif). Use the functions and properties in this class to retrieve settings and lists of items in reports and forms. The functions and properties in this class do not load or generate reports or input forms. They can only be used to obtain information about the structure of reports or input forms. These functions and properties limit the viewable items to those in a users security view.
Add Function
Adds an existing report or input form into a collection, which is a CFReports data type. If no errors are encountered, the report is added to the collection. The report is returned by this function so that it can be used immediately. If an error is encountered loading the file, either because the report does not exist or it does not appear to be the correct type of file, an errTieError (p. 62) error occurs. Developer Guide 39
Chapter 2: Classes To remove a single report or input form from the collection, use Remove. To remove all files from a collection, use Clear. Member of: CFXL.CFReports (p. 39) See also: Remove (p. 41), Clear (p. 40)
Syntax
Add(filename) Argument filename Description A fully qualified path and file name, as a string data type, to a valid Cognos Finance report or input form to be added to the collection
Example
Dim objRpt As CFReport set objRpt = objConnect.System.Reports.Add("C:\Income Statement.lrf")
Clear Subroutine
Removes all files from a collection. The count should be 0 (zero) after calling this function. To remove a single report or input form from the collection, use Remove. To add a report, use Add. Member of: CFXL.CFReports (p. 39) See also: to remove a single report, see Remove (p. 41); to add a report, see Add (p. 20)
Syntax
Clear()
Example
objConnect.System.Reports.Clear
Count Property
Returns the number of CFReport objects, such as loaded reports or input forms, in the CFReports class as an integer data type. Read-only. Member of: CFXL.CFReports (p. 39)
Syntax
Count = integer
Item Function
Retrieves a loaded report. This is the default member for this class. Each report or form is indexed by number or path and file name, and can only be in the collection once. Member of: CFXL.CFReports (p. 39)
Syntax
item(index) As CFReport Argument index Description The assigned number value, between 1 and count, of the loaded report or the file name used to add the report to the collection
Example
Set objRpt = objConnect.System.Reports("C:\Income Statement.lrf")
40
Chapter 2: Classes
' or Set objRpt = objConnect.System.Reports.item("C:\Income Statement.lrf")
Remove Subroutine
Removes the specified file, such as a report, from a collection. To remove all files from a collection, use Clear. To add a report, use Add. Member of: CFXL.CFReports (p. 39) See also: Add (p. 20), Clear (p. 40)
Syntax
Remove(filename) Argument filename Description The path and file name, as a string data type, to be removed from the collection
Example
objConnect.System.Reports.Remove "C:\Income Statement.lrf"
CFScreens
The CFScreens class exposes the API internal interfaces used in the Excel Add-in. These screens can be used for creating, modifying, and deleting connections, logging onto systems, and selecting items and dimensions.
EditConnection Subroutine
The subroutine displays the Edit Connection dialog box. It takes the CFConnection object as an argument by reference. If the CFConnection object is a local connection, the Edit Local Connection dialog box is shown. If the CFConnection is a remote connection, the Edit Remote Connection dialog box is shown. Users can use the appropriate dialog box to enter the information necessary to modify the connection object. Because the CFConnection object is passed by reference, the changes are reflected in the object in which they are passed. If the user cancels, the object is not altered. Changes to the connection information are written to the Lexw.ini file. Member of: CFScreens (p. 41)
Syntax
EditConnection(objConn As CFConnection)
Login Function
Logs the user onto the system to which the CFConnection object argument belongs. For systems implementing native security, a Logon dialog box is shown. For systems implementing Access Manager, the Common Logon dialog box is shown unless Access Manager is not installed on the same physical computer. If Access Manager is not installed on the computer, a Logon dialog box is shown and user credentials, such as user ID and password, are authenticated against the Access Manager Ticket server. If the user logs on successfully, the function returns true. If the user is unable to log on, the function returns false. Member of: CFScreens (p. 41)
Developer Guide 41
Chapter 2: Classes
Syntax
Login(objConn) As Boolean
NewLocalConn Function
Calls the New Local Connection dialog box and returns the newly created CFConnection object. The New Local Connection dialog box allows users to enter the information necessary to create a CFConnection object for a local Cognos Finance system. If the user cancels from the dialog box, a NULL object is returned. The new connection is made readily accessible through the CFConnections collection. Information about the local connection is written to the Lexw.ini file. Member of: CFScreens (p. 41)
Syntax
NewLocalConn() As CFConnection
NewRemoteConn Function
Calls the New Remote Connection dialog box and returns the newly created CFConnection object. The New Remote Connection dialog box allows users to enter the information necessary to create a CFConnection object for a remote Cognos Finance system. The new connection is available in the CFConnections collection and returned for immediate use. If the user cancels from the dialog box, a NULL object is returned. Information about the remote connection is written to the Lexw.ini file. Member of: CFScreens (p. 41)
Syntax
NewRemoteConn() As CFConnection
SelectConnection Function
Shows the Select Systems dialog box used to select a system connection. This function returns the selected connection as a CFConnection object. If the user cancels, a NULL object is returned. If no system connections exist, errNoConnections (p. 61) is raised. The CFConnect object returned can be used as arguments to the EditConnection (p. 41) and Login (p. 41) functions. The mode argument controls which systems are shown in the Select Systems dialog box. These connections are based on entries contained in the Lexw.ini file. Member of: CFScreens (p. 41)
Syntax
SelectConnection([mode As Long]) As CFConnection) Argument Long Description 0 shows all systems (default) 1 shows local systems 2 shows remote systems
42
Chapter 2: Classes
SelectDimension Function
You must be logged onto a Cognos Finance system to call this function, otherwise an errNotLoggedIn (p. 62) occurs. The function shows a dialog box that lists the dimensions available in the selected system. A user is allowed to select a single dimension, which is returned from the function in the form of a CFDimension object. If the user cancels, a NULL object is returned. To show a default dimension as a pre-selected item in the list, you must supply the DimID (p. 30) for the DefautItem argument when calling this function. Member of: CFScreens (p. 41)
Syntax
SelectDimension([DefaultItem As String]) Argument DefaultItem Description The identifier for the dimension to be selected by default. This argument is optional.
SelectItems Function
Users must be logged onto a Cognos Finance system to call this function. If the user is not logged on, an errNotLoggedIn (p. 62) occurs. The function shows a dialog box that contains a list of items in the dimension specified by the Dimension argument. The Dimension argument is either the DimName or the integer index for the dimension in the CFDimensions collection. An array of IDs for the selected items is returned. If the user cancels from the dialog box, a non-array integer (0) is returned. The dialog box supports commands such as, Selection Criteria and Find, which are available from a shortcut menu. Optionally, you can supply a default list that contains preselected items in the Select Items dialog box. The DefaultList argument is an array of IDs for items available for selection, which can also be the same array that is returned for the SelectItems function. Member of: CFScreens (p. 41).
Syntax
SelectItems(Dimension, [DefaultList]) Argument Dimension [DefaultList] Description The identifier for the selected dimension item. An array of IDs for preselecting items in the list.
CFSystem
The CFSystem class exposes the API functionality of Cognos Finance. This includes working with system connections moving data into and out of the database traversing the dimensional hierarchy logging on to and out of a system
Developer Guide 43
Chapter 2: Classes
ActiveConnection Property
Makes the reference to the connection on which the user is logged available as a CFConnection object in the active Connection property. If the user is not logged on, the property returns NULL. Member of: CFXL.CFSystem (p. 43)
Connections Property
The Connections property is a CFConnections object. It provides access to creating, editing, and deleting connections to Cognos Finance systems. Changes in this object are reflected in the users lexw.ini file. Read-only. Member of: CFXL.CFSystem (p. 43)
Data Property
The Data property is a CFData object. It provides access to functions and subroutines that transfer data, including intercompany targets, in batch queues or in real time into and out of the Cognos Finance database. Read-only. Member of: CFXL.CFSystem (p. 43) See also: CFData (p. 21)
Dimensions Property
The Dimensions property is a CFDimensions object. It provides access to dimensions and items in the active Cognos Finance system. Read-only. Member of: CFXL.CFSystem (p. 43) See also: CFDimensions (p. 32)
ErrLookup Function
Returns the description or help as a string data type for a supplied error code. This function is useful for non-VBA programming where an error number is returned and you must show the error description to end users. Member of: CFXL.CFSystem (p. 43)
Syntax
ErrLookup(ecode As ErrCodes) Argument ecode Description The error code that appears in the cfxl.dll file, whose message you want to look up
Login Subroutine
Logs a user on to a Cognos Finance system. If a user successfully logs on, the onLogIn (p. 46) event occurs. The Login subroutine uses three arguments, System, User, and Password. Depending on the circumstances, these arguments may be optional or required. If the cfxl.dll file is loaded as a Microsoft Excel COM add-in, the following behaviors are exhibited. The three arguments to this function are optional. If none of the arguments are supplied, the select system and login interface are displayed in both native and Access Manager security.
44
Chapter 2: Classes If the System argument is supplied and both the User and Password arguments are "" (blank) and the security type is set to Access Manager, the user is logged on using the Access Manager Common Logon Server. We recommend this usage when creating scripts for different users to run. The cfxl.dll file attempts to log on a user if the security type is set to native and both the User and Password arguments are "" (blank) if the User and Password arguments were set to non-blank for either security type No interface is displayed. If the User and Password arguments are omitted, Access Manager prompts the user for the user name and password. Access Manager logs the user on through the Password Logon screen rather than the Common Logon Server. If native security is used, the native security logon screen prompts for the user name and password and logs the user on. If you supply the System argument, it is highlighted (supplied) when the logon screen is displayed.
If the cfxl.dll file is not loaded through Microsoft Excel, the following behaviors are exhibited. All arguments are required. If any of the arguments are not supplied, an errMissingArg (p. 61) error occurs. If the System argument is supplied and both the User and Password arguments are "" (blank) and the security type is set to Access Manager, the user is logged on using the Access Manager Common Logon Server. We recommend this usage when creating scripts for different users to run. The cfxl.dll file attempts to log on a user if the security type is set to native and both the User and Password arguments are "" (blank) if the User and Password arguments were set to non-blank for either security type No interface is displayed. The Login subroutine can cause several errors. If any of these errors is encountered, the user is logged out. The errFailRegister (p. 57) error occurs when the Cognos Finance COM object is not registered correctly in the Windows Registry or Windows.ini file. The errFailCreate (p. 56) error occurs if the application fails to create the Cognos Finance COM object. The errMissingArg (p. 61) error occurs if the required System, User, or Password arguments are missing. The errFailConnect (p. 56) error occurs if there is an initialization failure, an invalid system connection, or if the application cannot access the database directory. This error can also occur if the user clicks Cancel on the Access Manager logon screen or has invalid credentials. If the errFailConnect occurred because of an invalid system connection, programming should trap this connection and offer the ability to select another connection. The errFailStart (p. 57) error occurs if the XLInterface object fails to start up in Microsoft Excel. Member of: CFXL.CFSystem (p. 43)
Syntax
Sub Login([System], [User], [Password]) Argument System User Password Description The name of the system connection The user ID The password
Developer Guide 45
Chapter 2: Classes
Logout Subroutine
Logs a user out of the current system. Once the user is logged out, the onLogout (p. 46) event occurs. Member of: CFXL.CFSystem (p. 43)
LogState Property
Returns True if a user is logged on to a Cognos Finance system. Returns False if a user is not logged on to a Cognos Finance system. Read-only. Member of: CFXL.CFSystem (p. 43)
Example
Dim objConnect As Connect Sub foo() If Not objConnect.System.LogState Then objConnect.System.Login "WAVE" End If If Not objConnect.System.LogState Then MsgBox "Login Failed." Exit Sub End If End Sub
onLogin Event
Occurs if the Login function is successful. When the API is loaded as a Microsoft Excel COM add-in, this event occurs if the Excel user logs on to a Cognos Finance System by using the Toolbar interface. Member of: CFXL.CFSystem (p. 43)
Syntax
Event onLogin(Status As Boolean)
onLogout Event
Occurs if the Logout function is called. If the API is loaded as a Microsoft Excel COM Add-in, this event occurs when the Excel user logs out of a Cognos Finance system using the Toolbar interface. Member of: CFXL.CFSystem (p. 43)
Syntax
Event onLogout(Status As Boolean)
onPost Event
Occurs when a post operation is performed using the Microsoft Excel COM Add-in. If the API is loaded as a Microsoft Excel COM Add-in, this event occurs when the Excel user uses the interface to post data or calls the DataPost function in the XLInterface class. The onPost event occurs if the transfer of data is complete; it does not occur if the PostCFI macro is used. Member of: CFXL.CFSystem (p. 43)
Syntax
Event onPost(Status As Boolean)
46
Chapter 2: Classes
onUpdate Event
Occurs when an update operation is performed using the Microsoft Excel COM Add-in. If the API is loaded as a Microsoft Excel COM Add-in, this event is raised when the Excel user uses the interface to update data or calls the DataUpdate function in the XLInterface class. The onUpdate event occurs when the transfer of data is complete; it does not occur if the UpdateCFI or UpdateCFD functions are used. Member of: CFXL.CFSystem (p. 43)
Syntax
Event onUpdate(Status As Boolean)
Reports Property
The Reports property is a CFReports object. It provides the ability to use loaded reports as selections when exposing dimensions and item. Before logging on to a system, you can obtain the following information file name (p. 37) system name, which can be used to log in (p. 18) system ID (p. 39) When you log on, the first parameter is System Name. It takes the System ID and matches the System Name to existing connections. An errInvalidSystem (p. 60) error occurs if no connection exists. After logging on to a system, you can obtain attribute and dimensional information by using the properties in the CFReport class. This includes the following report color, either account balance or statement (p. 37) scaling (p. 38) YTD setting, either YTD or monthly (p. 39) dependency submission IDs (p. 37) a list of dimensions on pages (p. 38), columns (p. 37), rows (p. 38), or filters (p. 38) Note: If a report from a different system has the same dimensions as a system to which you are logged on, the API assumes they are the same. If you attempt to load a report and the number of dimensions does not match the current system, an errDimMismatch (p. 55) error occurs. If an unknown error is generated by the cfxl.dll file, an errLoadDim (p. 60) error occurs. If an error is encountered loading a file, either because it does not exist or it does not appear to be the correct type of file, an errTieError (p. 62) error occurs. If the report or input form is not in a valid Cognos Finance format, an errInvalidReport (p. 59) error occurs. Member of: CFXL.CFSystem (p. 43)
Screens Property
Returns a reference to the CFScreens object, which can be used to show various dialog boxes to the user. Read only. Member of: CFXL.CFSystem (p. 43)
SysID Property
Returns the three-character system ID of the current system. If the user is not logged on, an errNotLoggedIn (p. 62) error occurs. Member of: CFXL.CFSystem (p. 43)
Developer Guide 47
Chapter 2: Classes
SysName Property
Returns the name of the current system. If the user is not logged on, an errNotLoggedIn (p. 62) error occurs. Read-only. Member of: CFXL.CFSystem (p. 43)
Syntax
SysName =
XLFormulas
Microsoft Excel calls this hidden class to run Cognos Finance cell macros, such as CFD, CFI, and CFName. Users are not meant to access this class.
XLInterface
The XLInterface object presents user interface elements from Cognos Finance in the Microsoft Excel environment. It is called by VBA and makes extensive use of Microsoft Excel library objects. The properties and subroutines associated with the XLInterface object enable you to manipulate user interface elements, such as dialog boxes, menu bars, and tool bars. With this functionality, you can customize user environments. If you attempt to call the Interface or Formulas objects from the API rather than Microsoft Excel, and the cfxl.dll file has not been loaded as a Microsoft Excel add-in, an ErrExcelAddIn (p. 56) error occurs.
CFMenuBarName Property
Enables you to find the menu bar name so you can script with it or hide it. Read-only. Member of: CFXL.XLInterface (p. 48)
Syntax
CFMenuBarName As String
CFToolBarName Property
Enables you to find the tool bar name so you can script with it or hide it. Read-only. Member of: CFXL.XLInterface (p. 48)
Syntax
CFToolBarName As String
ConnectionDelete Subroutine
Displays the Delete Connection dialog box. Used to remove a database link if you no longer want to make a database system available. Member of: CFXL.XLInterface (p. 48)
Syntax
Sub ConnectionDelete()
48
Chapter 2: Classes
ConnectionEdit Subroutine
Shows the Edit Connection dialog box, used to change the paths to show the new file locations when you have moved your Cognos Finance database files, reports, or data to another folder, drive, or computer. Member of: CFXL.XLInterface (p. 48)
Syntax
Sub ConnectionEdit()
ConnectionNew Subroutine
Displays the New Connection dialog box. Used to create a new connection to a Cognos Finance system. Member of: CFXL.XLInterface (p. 48)
Syntax
Sub ConnectionNew()
DataPost Subroutine
Posts workbook data to the Cognos Finance database. Use transfer filters to set what should be posted (p. 63). The DataPost subroutine works with user options settings like other post and update features in the interface, such as UpdateCFI and UpdateCFName. If no optional arguments are used, DataPost yields the same result as clicking Post Current Workbook on the Command Bar in the interface. If the user is not logged on, an errNotLoggedIn (p. 62) error occurs. Member of: CFXL.XLInterface (p. 48)
Syntax
Function DataPost([tTran As TransferFilter = 4], [Range As Range], [Quiet As Boolean = True]) As Boolean Argument tTran Description The number of the transfer filter option (p. 63) as a TransferFilter data type. The default is tWorkBook, which updates all cells on all sheets in the active Microsoft Excel workbook. The range of cells in the Microsoft Excel workbook If set to True, the Update/Post Complete or Update/Post Failed message box does not display.
Range Quiet
DataUpdate Subroutine
Updates workbook data from the Cognos Finance database. Use transfer filters to set what should be updated (p. 63). The DataUpdate subroutine works with user options settings like other post and update features in the interface, such as UpdateCFI and UpdateCFName. If no optional arguments are used, DataUpdate yields the same result as clicking Update Current Workbook on the Command Bar in the interface. If the user is not logged on, an errNotLoggedIn (p. 62) error occurs.
Developer Guide 49
Chapter 2: Classes Member of: CFXL.XLInterface (p. 48)
Syntax
Function DataUpdate([tTran As TransferFilter = 4], [Range As Range], [Quiet As Boolean = True]) As Boolean Argument tTran Description The number of the transfer filter option (p. 63) as a TransferFilter data type. The default is tWorkBook, which updates all cells on all sheets in the active Microsoft Excel workbook. The range of cells in the Microsoft Excel workbook. If set to True, the Update/Post Complete or Update/Post Failed message box does not display.
Range Quiet
Member of: CFXL.XLInterface (p. 48)
GetCellsInError Function
Returns a collection of CFErrItems. Used to get a group of errors for trapping and debugging events. Using CFErrItems, you can examine the collection, get a count if there are errors and then get a cell address (using CellAddr). ErrCode is the number associated with the error. The Value is displayed in the cell itself. Typically in Microsoft Excel, this is prefixed by #err. You can also use GetErrorDescription to return balloon tip help with the errors returned by CFErrItems. Member of: CFXL.XLInterface (p. 48)
Syntax
GetCellsInError() As Collection
Options Property
Returns the XLOptions object, which contains properties for posting and refreshing data. Read-only. Member of: CFXL.XLInterface (p. 48)
Syntax
Property Options As XLOptions
OptionsEdit Subroutine
Displays the Options dialog box. Used to set the extent of post and update commands. Member of: CFXL.XLInterface (p. 48)
Syntax
Sub OptionsEdit()
PostCFI Subroutine
Posts only CFI formulas to Cognos Finance Database. CFI is a function used to update the Cognos Finance database with input items from the workbook and/or to write input data from the database to the workbook. For more information about the CFI function, see the Cognos Finance Add-In for Excel User Guide. Member of: CFXL.XLInterface (p. 48) 50 Software Development Kit
Chapter 2: Classes
Syntax
Sub PostCFI([tTran As TransferFilter = tWorkBook]) Argument tTran Description The number of the transfer filter option (p. 63) as a TransferFilter data type. The default is tWorkBook, which updates all cells on all sheets in the active Microsoft Excel workbook.
ShowErrorComment Subroutine
Shows balloon tips in the active or specified cell, where errors are returned after processing. Used with a single cell, this subroutine takes the cell address as an optional argument. The default is the active cell. If an invalid cell range is supplied, an errInvalidCell (p. 58) error occurs. The ShowErrorComment subroutine is the equivalent of right-clicking a cell and then clicking Help on this Error. Member of: CFXL.XLInterface (p. 48)
Syntax
ShowErrorComment([Cell Address]) Argument Cell Address Description The cell address as a string data type
UpdateCFD Subroutine
Updates only CFD formulas from the Cognos Finance Database. CFD is a function used to write non-input data to the workbook. CFD is used only to retrieve and show items from the database. The CFD function links display-only cells that are refreshed from the database. For more information about the CFD function, see the Cognos Finance Add-In for Excel User Guide. Member of: CFXL.XLInterface (p. 48)
Syntax
Sub UpdateCFD([tTran As TransferFilter = tWorkBook]) Argument tTran Description The number of the transfer filter option (p. 63) as a TransferFilter data type. The default is tWorkBook, which updates all cells on all sheets in the active Microsoft Excel workbook.
UpdateCFI Subroutine
Updates only CFI formulas from Cognos Finance Database. CFI is a function used to update the Cognos Finance database with input items from the workbook and/or to write input data from the database to the workbook. For more information about the CFI function, see the Cognos Finance Add-In for Excel User Guide. Member of: CFXL.XLInterface (p. 48)
Developer Guide 51
Chapter 2: Classes
Syntax
Sub UpdateCFI([tTran As TransferFilter = tWorkBook]) Argument tTran Description The number of the transfer filter option (p. 63) as a TransferFilter data type. The default is tWorkBook, which updates all cells on all sheets in the active Microsoft Excel workbook.
UpdateCFNAME Subroutine
Updates only CFName formulas from Cognos Finance Database. CFNAME is similar to the CFD function in that it refreshes the target cell from the Cognos Finance database. This function is used to retrieve the full name of a dimension item from the Cognos Finance database and show it in the workbook instead of showing only the ID of an item. For more information about the CFName function, see the Cognos Finance Add-In for Excel User Guide. Member of: CFXL.XLInterface (p. 48)
Syntax
Sub UpdateCFNAME([tTran As TransferFilter = tWorkBook]) Argument tTran Description The number of the transfer filter option (p. 63) as a TransferFilter data type. The default is tWorkBook, which updates all cells on all sheets in the active Microsoft Excel workbook.
XLMenuBarName (Hidden) Property

The XLMenuBarName property is hidden, but can be displayed through Microsoft Excel.
XLOptions
The XLOptions class contains items that correspond to the items in the Excel Interface, Cognos Finance Options screen. Properties in this category include UpdateInput UpdateNames ReadNames ReadOutput To write these updates to the users lewx.ini file, call the SaveSettings subroutine. The onChange event is used to confirm that a property has been changed successfully.
onChange Event
Notifies that a property has been changed. Member of: CFXL.XLOptions (p. 52)
Syntax
Event onChange()
ReadNames Property
Flags items that use CFName functions for update after a post operation has been issued. Member of: CFXL.XLOptions (p. 52) 52 Software Development Kit
Chapter 2: Classes
Syntax
Property ReadNames As Boolean
ReadOutput Property
Flags items that use CFD macros for update after a post operation has been issued. Member of: CFXL.XLOptions (p. 52)
Syntax
ReadOutput As Boolean
SaveSettings Subroutine
Saves settings to the users lexw.ini file. Member of: CFXL.XLOptions (p. 52)
Syntax
SaveSettings()
UpdateInput Property
Flags items containing CFI functions for update during the next update operation. Member of: CFXL.XLOptions (p. 52)
Syntax
UpdateInput As Boolean
UpdateNames Property
Sets a flag to update item names during an update operation. Specifically, this flag turns on all CFName functions. CFNAME is similar to the CFD function in that it refreshes the target cell from the Cognos Finance database. This function is used to retrieve the full name of a dimension item from the Cognos Finance database and show it in the workbook instead of showing only the ID of an item. Member of: CFXL.XLOptions (p. 52)
Syntax
UpdateNames As Boolean
Developer Guide 53
Chapter 2: Classes
54
Chapter 3: Enumerations
Enumerations are used for error codes and transfer filters. This chapter describes each of these different type of enumerations and provides extensive cross-references to the other topics in this guide.
ErrCodes
The ErrCodes object contains error code constants. These constants apply when user errors or unexpected events prevent the application from functioning or from completing a process. Trap these errors to provide feedback to users or to correct your programming.
errDimMismatch Constant
Constant errDimMismatch = -2147220971 (&H80040215) Applies when the number of dimensions that you supply does not match the number of dimensions in the system. This constant also applies when the order of the dimensions does not match the listing found in the Define Items module. Functions and subroutines that use this constant include BatchAddValue, GetValue, PostValue, Reports, and all the properties and functions found in the CFReport class. Member of: CFXL.ErrCodes (p. 55)
Solution
Obtain proper dimension names and their order by examining the CFDimension class.
errDIIUnloaded Constant
Constant errDllUnloaded = -2147220970 (&H80040216) Applies when trying to access an object that was referenced in the cfxl.dll file after setting the cfxl.dll file instance to nothing. Member of: CFXL.ErrCodes (p. 55)
Example
For example, the following procedure causes this error: 1. Create objAPI, which is an instance of the cfxl.dll file. 2. Create objReport, which is a reference to a CFReport object that you loaded into the Reports collection. 3. Set objAPI to nothing. 4. Access any of the functionality in the objReport object.
Solution
When setting the API instance to nothing, all other references to the cfxl.dll file should also be set to nothing.
errDupSystem Constant
Constant errDupSystem = -2147220982 (&H8004020A)
Developer Guide 55
Chapter 3: Enumerations Applies when an attempt is made, using the CFConnections.Add function (p. 20), to add a Cognos Finance connection that has a name that already exists. Cognos Finance connections, which are written to the lexw.ini file, must be unique. Member of: CFXL.ErrCodes (p. 55)
Solution
Add a connection that has a unique name, or prompt users to use a different name to add their connections.
errExcelAddin Constant
Constant errExcelAddin = -2147220974 (&H80040212) Applies when you attempt to call the Interface or Formulas objects from the API and not through Microsoft Excel. The Interface and Formulas objects can be used only to work with Microsoft Excel. This constant is used throughout the Connect and XLInterface classes. Member of: CFXL.ErrCodes (p. 55)
Solution
To use the Interface or Formulas objects, start Microsoft Excel. If not working in Microsoft Excel, do not use any of the functions, subroutines, or properties from the Interface or Formulas objects.
errExcelBusy Constant
Constant errExcelBusy = -2147220976 (&H80040210) Applies when performing a transfer using the XLInterface class, such as UpdateCFI() and PostCFI() if the active cell in Excel is in Edit Mode. Member of: CFXL.ErrCodes (p. 55)
Solution
End Edit mode on the active cell by pressing Enter or clicking a different cell.
errFailConnect Constant
Constant errFailConnect = -2147220979 (&H8004020D) Applies when a problem is raised by the Cognos Finance COM object or some other component of the underlying software, such as an initialization failure the application cannot directly access the database directory an invalid system connection exists the user clicks Cancel in the Access Manager logon screen the user has invalid credentials This constant is used in the Login subroutine. Member of: CFXL.ErrCodes (p. 55)
Solution
Use err.Description to log or present the error message to the user.
errFailCreate Constant
Constant errFailCreate = -2147220980 (&H8004020C) Applies when the cfxl.dll file is unable to create the object APLW.WSEngine. The cfxl.dll file should ensure that this class is properly registered and set up. 56 Software Development Kit
Chapter 3: Enumerations Member of: CFXL.ErrCodes (p. 55)
Solution
Contact Cognos support.
errFailRegister Constant
Constant errFailRegister = -2147220967 (&H80040219) Applies when the Cognos Finance COM object was not registered correctly in the Windows Registry. Member of: CFXL.ErrCodes (p. 55)
Solution
Attempt to manually register the Cognos Finance COM object. You must contact Cognos support for help with this issue. 1. From the Start menu, click Run and type the following command: regsrvr32 [path_to_the_/bin_directory]/aplwco.dll 2. From the Start menu, click Run and type the following command: [path_to_the_/bin_directory]/lexw.exe/RegServer
errFailStart Constant
Constant errFailStart = -2147220981 (&H8004020B) Applies when the application encounters errors while trying to create the Cognos Finance menu and command bar. Member of: CFXL.ErrCodes (p. 55)
Solution
errFailTransfer Constant
Constant errFailTransfer = -2147220977 (&H8004020F) Applies if corrupt data is encountered when calling any transfer operation using XLInterface or CFData. Member of: CFXL.ErrCodes (p. 55)
Solution
errInvalidAccArg Constant
Constant errInvalidAccArg = -2147220963 (&H8004021D) Applies if the number of rows in the matrix does not match the number of accounts in the array. When supplying an array for only the Accounts argument the Value argument needs to be an array of the same number of elements. When you supply an array for both the Accounts argument and the Periods argument the Value argument needs to be a matrix n number of accounts wide. Member of: CFXL.ErrCodes (p. 55)
Solution
Determine why the number of accounts in the Accounts argument does not match the number of accounts in the Value argument. Developer Guide 57
errInvalidArrArg Constant
Constant errInvalidArrArg = -2147220965 (&H8004021B) Applies when any argument other than accounts or periods is an array. Functions that use this constant include GetValue and PostValue. Member of: CFXL.ErrCodes (p. 55)
Solution
Change the arguments so that only accounts and periods are in arrays.
errInvalidCell Constant
Constant errInvalidCell = -2147220984 (&H80040208) Applies when the supplied cell range is invalid or does not exist in Microsoft Excel. The ShowErrorComment subroutine (p. 51) uses this constant. Member of: CFXL.ErrCodes (p. 55)
Solution
Change the argument so that the supplied cell range is valid.
errInvalidDirectory Constant
Constant errInvalidDirectory = -2147220991 (&H80040201) Applies when the specified directory does not exist or cannot be accessed. Properties that use this constant include Datadir (p. 15), InputDir (p. 16), OutputDir (p. 17), SysoutDir (p. 19), SysRptsDir (p. 19), and UserRptsDir (p. 19). Member of: CFXL.ErrCodes (p. 55)
Solution
Ensure that the directory exists.
errInvalidLogin Constant
Constant errInvalidLogin = -2147220890 (&H80040266) Applies when user has invalid user credentials. Member of: CFXL.ErrCodes (p. 55)
Solution
Confirm the user credentials or contact your application administrator for the correct user ID and password.
errInvalidNumArgs Constant
Constant errInvalidNumArgs = -2147220966 (&H8004021A) Applies when the correct number of arguments, equal to the total number of submission, account, period and component dimensions, is not supplied. Functions that use this constant include GetIceTargets, which requires a tuple consisting of all the submission, component, account, and period dimensions to retrieve intercompany target data. Member of: CFXL.ErrCodes (p. 55)
Solution
Use the Count function to count the number of arguments. 58 Software Development Kit
errInvalidObject Constant
Constant errInvalidObject = -2147220986 (&H80040206) Applies if errors are encountered while the cfxl.dll file is loading. This happens if some of the classes are not valid or if you try to use an object that does not exist. Member of: CFXL.ErrCodes (p. 55)
Solution
errInvalidPerArg Constant
Constant errInvalidPerArg = -2147220962 (&H8004021E) Applies if the number of columns in the matrix does not match the number of periods in the array. When supplying an array for only the periods argument the Value argument needs to be an array of the same number of elements. When you supply an array for both the Accounts argument and the Periods argument the Value argument needs to be a matrix m number of periods wide. Member of: CFXL.ErrCodes (p. 55)
Solution
Determine why the number of periods in the Periods argument does not match the number of periods in the Value argument.
errInvalidReport Constant
Constant errInvalidReport = -2147220972 (&H80040214) Applies when the CFReports Add function (p. 20) encounters a problem with the report or input form. Member of: CFXL.ErrCodes (p. 55)
Solution
Ensure that the report is a valid Cognos Finance report or input form. Try to load the report or input form in the Reporting or Input module.
errInvalidSub Constant
Constant errInvalidSub = -2147220968 (&H80040218) Applies if you supply a SubID argument that does not exist in the database when calling any of the following functions on a CFItem: GetLocked, GetCalcString, GetChildren, or GetParents. Member of: CFXL.ErrCodes (p. 55)
Solution
Correct the SubID argument and call the function again. You can compare the SubID with the item IDs for each item in the submissions dimension.
errInvalidSysId Constant
Constant errInvalidSysId = -2147220989 (&H80040203) Applies when you attempt to set the SysID property (p. 18) using an invalid format. Member of: CFXL.ErrCodes (p. 55)
Developer Guide 59
Solution
Ensure that the argument does not contain spaces and is three characters in length.
errInvalidSystem Constant
Constant errInvalidSystem = -2147220990 (&H80040202) Applies if you do not have a connection set up for a supplied system name. Member of: CFXL.ErrCodes (p. 55)
Solution
Add the connection.
errInvalidTicket Constant
Constant errInvalidTicket = -2147220891 (&H80040265) Applies when attempting to communicate with the server and the Access Manager ticket is invalid. Member of: CFXL.ErrCodes (p. 55)
Solution
The Access Manager ticket expired or the Access Manager settings may have changed during your session. Log off and then log back on.
errInvalidValArg Constant
Constant errInvalidValArg = -2147220964 (&H8004021C) Applies when using the PostValue function if you supply the following an array for accounts and an array for periods and do not supply a two-dimensional matrix for Value an array for accounts and a scalar for periods or a scalar for accounts and an array for periods and do not supply a one-dimensional array for Value Member of: CFXL.ErrCodes (p. 55)
Solution
Supply the appropriate Value argument. If using an array for both accounts and periods, you must supply a matrix for the Value argument that is n number of accounts high by m number of periods wide. If you are using an array only for accounts or only for periods, you must supply an array of the same shape.
errInvalidXml Constant
Constant errInvalidXml = -2147220792 (&H800402C8) Applies if the information sent to and received from the server is corrupt. Member of: CFXL.ErrCodes (p. 55)
Solution
errLoadDim Constant
Constant errLoadDim = -2147220975 (&H80040211) Applies when an error is encountered while loading the data for this report. Member of: CFXL.ErrCodes (p. 55) 60 Software Development Kit
Solution
errLoadingCache Constant
Constant errLoadingCache = -2147220969 (&H80040217) Applies if an error is encountered while loading the cache when calling any of the following functions on a CFItem: GetLocked, GetCalcString, GetChildren, or GetParents. The cache is used to enhance performance by loading submission information for items the first time they are read from the Cognos Finance database. Member of: CFXL.ErrCodes (p. 55)
Solution
errLockedCell Constant
Constant errLockedCell = -2147220983 (&H80040209) Applies if the cfxl.dll file is unable to update the Value argument in a CFD, CFI, or CFName macro while performing a transfer using the XLInterface class. Member of: CFXL.ErrCodes (p. 55)
Solution
Unlock the cell by either unchecking Format/Cells/Protection/Locked or programatically by running something similar to the following:
Range(strRange).Locked = false
errMissingArg Constant
Constant errMissingArg = -2147220978 (&H8004020E) Applies when the system name, user, or password argument is missing. Member of: CFXL.ErrCodes (p. 55)
Solution
Supply the missing arguments. For information, see the System.Login subroutine (p. 44).
errNoConnections Constant
Const errNoConnections = -2147220956 (&H80040224) Applies when calling the prompt for SelectConnection function from the CFScreens class and no connections exist. Member of: CFXL.ErrCodes (p. 55)
Solution
Add a connection.
errNoDelimiter Constant
Constant errNoDelimiter = -2147220960 (&H80040220) Applies if errors are encountered while loading the cfxl.dll file. Member of: CFXL.ErrCodes (p. 55)
Developer Guide 61
Solution
errNotLoggedIn Constant
Constant errNotLoggedIn = -2147220987 (&H80040205) Applies when you are not logged on to a system. Some operations require you to be logged on to a system before obtaining information or posting data. Properties that use this constant include Count, Reports, SysID, SysName, DataPost, DataUpdate, and all properties and functions in the CFReport class. Member of: CFXL.ErrCodes (p. 55)
Solution
Log on to the system and retry the operation.
errNTLogFail Constant
Constant errNTLogFail = -2147220957 (&H80040223) Applies when a problem is encountered while attempting to enter new events to the Windows Application Event Log. Member of: CFXL.ErrCodes (p. 55)
Solution
The Application Event log may be full. Open Windows Event Viewer and inspect the log. 1. From the Windows Start menu, click Control Panel, Administrative Tools, and then double-click Event Viewer. 2. If necessary, change the size of the event log.
errTestFail Constant
Constant errTestFail = -2147220958 (&H80040222) Applies when the server and port do not reply after calling the Discover subroutine from a CFConnection object. Member of: CFXL.ErrCodes (p. 55)
Solution
Confirm that the server and port information is correct and ensure that the server is running.
errTieError Constant
Constant errTieError = -2147220973 (&H80040213) Applies when an error is encountered loading a file, either because the file does not exist or does not appear to be the correct type of file. The errTieError constant may also indicate that the file is currently being exclusively used by some other process. Properties that use this constant include Add, Reports, and all properties and functions in the CFReport class. Member of: CFXL.ErrCodes (p. 55)
Solution
Another application may have a lock on the file. Wait for the process to release the file. If that does not work, ensure that the path and file name are correct.
62
errUnexpected Constant
Constant errUnexpected = -2147220959 (&H80040221) Applies when attempting to communicate with the remote computer. Before this error is returned, related errors are logged in the Windows Event Viewer. Member of: CFXL.ErrCodes (p. 55)
Solution
Check for server connectivity and contact Cognos support.
TransferFilter
Use transfer filters to specify the scope of posting and update functions. Use a filter by passing its ID (constant) as an argument in a DataPost (p. 49) or DataUpdate (p. 49) subroutine. The following table describes the filters and their constants: Filter tExcel tSelection tSheet Constant 8 1 2 Description Posts and updates all cells in all sheets in all open workbooks Posts and updates selected cells Posts and updates all cells in the selected sheets Posts and updates all cells in all sheets in the current workbook, which is the default
tWorkBook 4
Developer Guide 63
64
Appendix A: Sample VB Code

The samples in this section exhibit some of the techniques used when the API is used outside of Microsoft Excel.
Make the Sample Code into an Executable Visual Basic Project

Using the text contained in this appendix you can create a visual basic project that demonstrates many of the methods that are available using the System class.
Steps
1. Copy the text labeled Sample File Login.frm and paste it into a text editor, such as Windows NotePad. 2. Save the file as Login.frm. 3. Copy the text labeled Sample File Main.frm and paste it into a text editor, such as Windows NotePad. 4. Save the file as Main.frm. 5. Create a Visual Basic standard executable project. 6. Add the two forms you created to the project. 7. Set the startup object to the Main.frm. 8. In the Project References dialog box, set a reference to the Cognos Finance Add-In for Excel (cfxl.dll). 9. Run the project.
Sample File Login.frm

Use the text in this section to create the login form.
VERSION 5.00 Begin VB.Form fmLogin BorderStyle = Caption = ClientHeight = ClientLeft = ClientTop = ClientWidth = LinkTopic = MaxButton = MinButton = ScaleHeight = ScaleWidth =
3 'Fixed Dialog "Login" 2190 45 435 4185 "Form2" 0 'False 0 'False 2190 4185
Developer Guide 65

ShowInTaskbar = 0 'False StartUpPosition = 1 'CenterOwner Begin VB.ComboBox cmbSystems Height = 315 Left = 1050 Style = 2 'Dropdown List TabIndex = 0 Top = 720 Width = 1710 End Begin VB.TextBox Text1 Height = 315 IMEMode = 3 'DISABLE Index = 1 Left = 1050 PasswordChar = "*" TabIndex = 2 Top = 1680 Width = 1695 End Begin VB.CommandButton bnCancel Cancel = -1 'True Caption = "Cancel" Height = 375 Left = 3135 TabIndex = 4 Top = 1185 Width = 975 End Begin VB.CommandButton bnOK Caption = "OK" Default = -1 'True Height = 375 Left = 3135 TabIndex = 3 Top = 705 Width = 975 End Begin VB.TextBox Text1 Height = 315 Index = 0 Left = 1050 TabIndex = 1 Top = 1200 Width = 1695 End Begin VB.PictureBox Picture1 Appearance = 0 'Flat BackColor = &H80000018& ForeColor = &H80000008& Height = 495 Left = 75 ScaleHeight = 465 ScaleWidth = 3975 TabIndex = 8 Top = 75 Width = 4005 Begin VB.Label Label2 Appearance = 0 'Flat BackColor = &H80000004& BackStyle = 0 'Transparent Caption = "Leave username and password blank to use Access Manager Common Logon Server." ForeColor = &H80000008& Height = 420 Left = 75 TabIndex = 9 Top = 15
66

Width = 3825 WordWrap = -1 'True End End Begin VB.Label Label1 AutoSize = -1 'True Caption = "System:" Height = 195 Index = 2 Left = 90 TabIndex = 7 Top = 720 Width = 555 End Begin VB.Label Label1 AutoSize = -1 'True Caption = "Password:" Height = 195 Index = 1 Left = 90 TabIndex = 6 Top = 1680 Width = 735 End Begin VB.Label Label1 AutoSize = -1 'True Caption = "Username:" Height = 195 Index = 0 Left = 90 TabIndex = 5 Top = 1200 Width = 765 End End Attribute VB_Name = "fmLogin" Attribute VB_GlobalNameSpace = False Attribute VB_Creatable = False Attribute VB_PredeclaredId = True Attribute VB_Exposed = False ' CFXL Client Demo - Login Form ' This form uses fmMain's Public CF object Private Sub Form_Load() Dim objConn As CFConnection For Each objConn In fmMain.CF.System.Connections ' Loop through system connections cmbSystems.AddItem objConn.SysName ' Add this connection to the combo list Next objConn cmbSystems.ListIndex = 0 ' Set default selection End Sub Private Sub bnOK_Click() ' A successful login will fire the onLogin Event in the Main Form On Error Resume Next ' Try to login with args: System, Username, Password fmMain.CF.System.Login cmbSystems.Text, Text1(0).Text, Text1(1).Text If err <> 0 Then MsgBox err.Description, , "Error Logging on" Else Unload Me End If End Sub Private Sub bnCancel_Click()
Developer Guide 67

Unload Me End Sub
Sample File Main.frm

Use the text in this section to create the Main CFXL Client Demo form.
VERSION 5.00 Object = "{F9043C88-F6F2-101A-A3C9-08002B2F49FB}#1.2#0"; "COMDLG32.OCX" Begin VB.Form fmMain BorderStyle = 1 'Fixed Single Caption = "CFXL Client Demo" ClientHeight = 6315 ClientLeft = 45 ClientTop = 435 ClientWidth = 12120 LinkTopic = "Form1" MaxButton = 0 'False MinButton = 0 'False ScaleHeight = 6315 ScaleWidth = 12120 StartUpPosition = 2 'CenterScreen Begin VB.TextBox txtNewValue Alignment = 1 'Right Justify Appearance = 0 'Flat Height = 285 Left = 10080 TabIndex = 47 Top = 2130 Width = 1935 End Begin VB.CommandButton bnPost Caption = "Post Value" Height = 495 Left = 10080 TabIndex = 46 Top = 1530 Width = 1935 End Begin VB.CommandButton bnFilter Caption = "Load Report" Height = 495 Left = 10080 TabIndex = 45
68

Top = 930 Width = 1935 End Begin VB.TextBox txtAttributes BackColor = &H8000000F& BorderStyle = 0 'None Height = 3135 Left = 10080 Locked = -1 'True MultiLine = -1 'True TabIndex = 31 Top = 2970 Width = 2055 End Begin VB.Frame frmItem Caption = "Item Information" BeginProperty Font Name = "MS Sans Serif" Size = 8.25 Charset = 0 Weight = 700 Underline = 0 'False Italic = 0 'False Strikethrough = 0 'False EndProperty Height = 3495 Left = 4920 TabIndex = 21 Top = 90 Visible = 0 'False Width = 4935 Begin VB.Label lblCalc Height = 255 Left = 1080 TabIndex = 44 Top = 2280 Width = 3735 End Begin VB.Label lblChildren Height = 255 Left = 1080 TabIndex = 43 Top = 2520 Width = 3735 End Begin VB.Label lblParents Height = 255 Left = 1080 TabIndex = 42 Top = 2760 Width = 3735 End Begin VB.Label lblLocked Height = 255 Left = 1080 TabIndex = 41 Top = 2040 Width = 3735 End Begin VB.Label lblItemName Height = 255 Left = 1080 TabIndex = 40 Top = 1560 Width = 3735 End Begin VB.Label lblItemID Height = 255
Developer Guide 69

Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index = = = = 1080 39 1320 3735
lblDimType = 255 = 1440 = 38 = 840 = 3375 lblDimID = 255 = 1440 = 37 = 600 = 3375 lblDimNm = 255 = 1440 = 36 = 360 = 3375 lblTargets = 375 = 1080 = 35 = 3000 = 3735 Label3 = = = = = = = = Label3 = = = = = = = = Label3 = = = = = = = = Label3 = = = = -1 'True "ICE Targets:" 195 9 120 32 3000 885 -1 'True "Dimension Name:" 195 0 120 30 360 1245 -1 'True "Dimension ID:" 195 1 120 29 600 990 -1 'True "Dimension Type:" 195 2
70

Left = TabIndex = Top = Width = End Begin VB.Line Line3 BorderColor = Index = X1 = X2 = Y1 = Y2 = End Begin VB.Label Label3 AutoSize = Caption = Height = Index = Left = TabIndex = Top = Width = End Begin VB.Label Label3 AutoSize = Caption = Height = Index = Left = TabIndex = Top = Width = End Begin VB.Label Label3 AutoSize = Caption = Height = Index = Left = TabIndex = Top = Width = End Begin VB.Line Line3 BorderColor = Index = X1 = X2 = Y1 = Y2 = End Begin VB.Label Label3 AutoSize = Caption = Height = Index = Left = TabIndex = Top = Width = End Begin VB.Label Label3 AutoSize = Caption = Height = Index = Left = TabIndex = 120 28 840 1185 &H80000000& 0 120 4800 1200 1200 -1 'True "Item ID:" 195 3 120 27 1320 555 -1 'True "Item Name:" 195 4 120 26 1560 810 -1 'True "Locked:" 195 5 120 25 2040 585 &H80000000& 1 120 4800 1920 1920 -1 'True "Calc String:" 195 6 120 24 2280 810 -1 'True "Children:" 195 7 120 23
Developer Guide 71

Top = 2520 Width = 615 End Begin VB.Label Label3 AutoSize = -1 'True Caption = "Parents:" Height = 195 Index = 8 Left = 120 TabIndex = 22 Top = 2760 Width = 585 End End Begin VB.Frame frmFilter Caption = "Report Properties:" BeginProperty Font Name = "MS Sans Serif" Size = 8.25 Charset = 0 Weight = 700 Underline = 0 'False Italic = 0 'False Strikethrough = 0 'False EndProperty Height = 2535 Left = 4920 TabIndex = 4 Top = 3720 Visible = 0 'False Width = 4935 Begin VB.Line Line3 BorderColor = &H80000000& Index = 3 X1 = 120 X2 = 4680 Y1 = 1320 Y2 = 1320 End Begin VB.Label lblColumns Height = 255 Left = 960 TabIndex = 20 Top = 2160 Width = 3855 End Begin VB.Label lblRows Height = 255 Left = 960 TabIndex = 19 Top = 1920 Width = 3855 End Begin VB.Label lblPages Height = 255 Left = 960 TabIndex = 18 Top = 1680 Width = 3855 End Begin VB.Label lblFilter Height = 255 Left = 960 TabIndex = 17 Top = 1440 Width = 3855 End Begin VB.Label lblDep
72

Height Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label Height Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label AutoSize Caption Height Index Left TabIndex Top Width End Begin VB.Label = = = = = 255 1200 16 960 3615
lblSwitch = 255 = 1200 = 15 = 720 = 3615 lblScale = 255 = 1200 = 14 = 480 = 3615 lblColor = 255 = 1200 = 13 = 240 = 3615 Label4 = = = = = = = = Label4 = = = = = = = = Label4 = = = = = = = = Label4 = = = = = = = = Label4 -1 'True "Columns:" 195 8 120 12 2160 645 -1 'True "Rows:" 195 7 120 11 1920 450 -1 'True "Pages:" 195 6 120 10 1680 495 -1 'True "Filter:" 195 5 120 9 1440 375
Developer Guide 73

AutoSize = -1 'True Caption = "Dependency:" Height = 195 Index = 4 Left = 120 TabIndex = 8 Top = 960 Width = 960 WordWrap = -1 'True End Begin VB.Label Label4 AutoSize = -1 'True Caption = "Switchable:" Height = 195 Index = 3 Left = 120 TabIndex = 7 Top = 720 Width = 825 End Begin VB.Label Label4 AutoSize = -1 'True Caption = "Scaling:" Height = 195 Index = 2 Left = 120 TabIndex = 6 Top = 480 Width = 570 End Begin VB.Label Label4 AutoSize = -1 'True Caption = "Color:" Height = 195 Index = 1 Left = 120 TabIndex = 5 Top = 240 Width = 405 End End Begin MSComDlg.CommonDialog cmm Left = 240 Top = 5730 _ExtentX = 847 _ExtentY = 847 _Version = 393216 End Begin VB.Frame frmDims Caption = "Dimensions" BeginProperty Font Name = "MS Sans Serif" Size = 8.25 Charset = 0 Weight = 700 Underline = 0 'False Italic = 0 'False Strikethrough = 0 'False EndProperty Height = 6165 Left = 120 TabIndex = 1 Top = 90 Visible = 0 'False Width = 4695 Begin VB.ComboBox cmbDimItemIDs Height = 315 Index = 0
74

Left = 4560 Style = 2 'Dropdown List TabIndex = 34 Top = -120 Visible = 0 'False Width = 390 End Begin VB.ComboBox cmbDimItems Height = 315 Index = 0 Left = 1320 Style = 2 'Dropdown List TabIndex = 3 Top = -100 Visible = 0 'False Width = 3225 End Begin VB.Label lblDimName AutoSize = -1 'True Caption = "Dummy Dimension" BeginProperty Font Name = "MS Sans Serif" Size = 8.25 Charset = 0 Weight = 700 Underline = 0 'False Italic = 0 'False Strikethrough = 0 'False EndProperty ForeColor = &H00C00000& Height = 195 Index = 0 Left = 120 TabIndex = 2 Top = -105 Visible = 0 'False Width = 1545 End End Begin VB.CommandButton bnLogin Caption = "Login" Height = 495 Left = 10080 TabIndex = 0 Top = 330 Width = 1935 End Begin VB.Line Line1 BorderColor = &H80000000& Index = 1 X1 = 9960 X2 = 12120 Y1 = 210 Y2 = 210 End Begin VB.Line Line1 BorderColor = &H80000000& Index = 0 X1 = 9960 X2 = 12120 Y1 = 6210 Y2 = 6210 End Begin VB.Label Label5 Caption = "Attributes:" Height = 255 Left = 10080 TabIndex = 33
Developer Guide 75

Top = 2610 Width = 1935 End Begin VB.Line Line1 BorderColor = &H80000000& Index = 3 X1 = 9960 X2 = 12120 Y1 = 2490 Y2 = 2490 End Begin VB.Line Line2 BorderColor = &H80000000& X1 = 9960 X2 = 9960 Y1 = 6210 Y2 = 210 End End Attribute VB_Name = "fmMain" Attribute VB_GlobalNameSpace = False Attribute VB_Creatable = False Attribute VB_PredeclaredId = True Attribute VB_Exposed = False ' CFXL Client Demo - Main Form ' This demo provides examples of the various properties and methods in the API ' Note: You may need to reset the reference to the CFXL.dll Public CF As CFXL.CFAPI ' CF API com object Private WithEvents CFSystem As CFSystem ' Used for getting login & logout events Attribute CFSystem.VB_VarHelpID = -1 Private bFilter As Boolean ' Is a report filter loaded? Private bLoaded As Boolean ' Is the interface loaded yet? Supress events ' #### FORM EVENTS #### Private Sub Form_Load() Set CF = CreateObject("CFXL.CFAPI") Set CFSystem = CF.System bFilter = False bLoaded = False End Sub ' #### BUTTON EVENTS #### Private Sub bnLogin_Click() If CF.System.LogState Then CF.System.Logout Else fmLogin.Show vbModal End If End Sub
' ' ' '
Create CF Com Object Set local reference to trap events default: no filter loaded The interface is not loaded
' ' ' '
User is Logged in Log them out User is Not logged in Attempt to Log them in
Private Sub bnPost_Click() Dim i As Integer, value As Variant, arrTupple As Variant ' Check the the interface has completed loading If Not bLoaded Then Exit Sub ' Fill Array with selection for PostValue ReDim arrTupple(0 To CF.System.Dimensions.Count - 1) As Variant For i = 1 To CF.System.Dimensions.Count ' Iterate through each dimension in this system arrTupple(i - 1) = GetItem(i).itemID ' Find the ID of the selected item for this dimension Next i ' Update gui with new value
76

value = txtNewValue.Text ' Get the Value
to Post
value = CF.System.Data.PostValue(arrTupple, value) ' Post the value to Finance If UBound(value) >= 0 Then txtNewValue.Text = value(0)(2) ' First Error, Error Description Exit Sub End Sub Private Sub bnFilter_Click() Dim objDim As CFDimension, objItem As CFItem, CFRpt As CFReport Dim filename As String, n As Integer ' Check the the interface has completed loading If Not bLoaded Then Exit Sub If bFilter Then ' Reload all items for all dimensions For Each objDim In CF.System.Dimensions ' Iterate through each dimension n = n + 1 ' Increment each dimension cmbDimItems(n).Clear ' Clear this dimension's Names combo list cmbDimItemIDs(n).Clear ' Clear this dimension's IDs combo list For Each objItem In objDim ' Iterate through each item in this dimension cmbDimItems(n).AddItem objItem.ItemName ' Add the Name to the list cmbDimItemIDs(n).AddItem objItem.itemID ' Add the ID to the list Next objItem cmbDimItems(n).ListIndex = 0 ' Set default selection Next objDim Else ' Load a report and use it's dimensions for the selection criteria. cmm.Filter = "Cognos Finance Forms (*.lrf, *.lif)|*.LRF;*.LIF" ' Get file name cmm.ShowOpen ' Display the dialog If cmm.filename = "" Then Exit Sub ' Check for cancel filename = cmm.filename ' Save file name ' Try to add this file, raises errors if it's already there On Error Resume Next CF.System.Reports.Add filename On Error GoTo err ' Get the report from the DLL Set CFRpt = CF.System.Reports(filename) ' For each dimension in the system, find that dimension in the report For i = 1 To CF.System.Dimensions.Count ' Order of dimensions in report does not match order in system ' so we must index by this i dimension in the system to get the ' then index that name into the report to get it's object out Set objDim = CFRpt.Dimensions(CF.System.Dimensions(i).DimName) cmbDimItems(i).Clear dimension's Names combo list cmbDimItemIDs(i).Clear dimension's IDs combo list For Each objItem In objDim each item in this dimension cmbDimItems(i).AddItem objItem.ItemName the list ' Clear this ' Clear this ' Iterate through ' Add the Name to
name
of the report
Developer Guide 77

cmbDimItemIDs(i).AddItem objItem.itemID ' Add the ID to the Next objItem cmbDimItems(i).ListIndex = 0 Next i ' Set default
list selection
' Update the interface frmFilter.Caption = Mid(CFRpt.filename, 1 + InStrRev(CFRpt.filename, "\")) lblColor = CFRpt.Color lblScale = CFRpt.Scaling lblSwitch = CFRpt.Switchable lblDep = CFRpt.DependencySub ' Update the interface lblFilter = BuildDimString(CFRpt.Filter) lblPages = BuildDimString(CFRpt.Pages) lblRows = BuildDimString(CFRpt.Rows) lblColumns = BuildDimString(CFRpt.Columns) ' Remove the report from the Dll's collection. CF.System.Reports.Clear End If ' Update interface bFilter = Not bFilter frmFilter.Visible = bFilter bnFilter.Caption = IIf(bFilter, "Unload Report", "Load Report") cmbDimItems_Click 1 ' fire an onclick to update the interface. Exit Sub err: If err.Number = ErrCodes.errDimMismatch Then MsgBox "This report is not compatible with the loaded system", vbCritical, "Error Loading Report" Else MsgBox err.Description, vbCritical, "Error Loading Report" End If End Sub ' #### CFSYSTEM EVENTS #### Private Sub CFSystem_onLogin() ' System has been logged into, set up cf interface bnLogin.Caption = "Logout" frmDims.Caption = "System: " & CF.System.SysID LoadInterface End Sub Private Sub CFSystem_onLogout() ' System has been logged out of, hide cf interface ' Reset Captions bFilter = False bnFilter.Caption = IIf(bFilter, "Unload Report", "Load Report") bnLogin.Caption = "Login" frmDims.Caption = "" txtNewValue = "" txtAttributes.Text = "" ' Delete dynamic controls Do While lblDimName.Count > 1 Unload lblDimName(lblDimName.Count - 1) Unload cmbDimItems(cmbDimItems.Count - 1) Unload cmbDimItemIDs(cmbDimItemIDs.Count - 1) Loop ' Hide frames frmItem.Visible = False frmDims.Visible = False
78

frmFilter.Visible = False ' Update interface flag bLoaded = False End Sub ' #### COMBO BOX EVENTS #### Private Sub cmbDimItems_GotFocus(index As Integer) ' Check the the interface has completed loading If Not bLoaded Then Exit Sub End Sub Private Dim Dim Dim LoadInfo index ' Update Info for this item Sub cmbDimItems_Click(index As Integer) objDims As CFDimensions, objDim As CFDimension arrTupple() As Variant ' array to send tupple in i As Integer, str As String
' Check the the interface has completed loading If Not bLoaded Then Exit Sub ' Create the post array the same size of the dimensions ReDim arrTupple(0 To CF.System.Dimensions.Count - 1) As Variant ' Update Info for this item LoadInfo index ' Fill Array with selection For i = 1 To CF.System.Dimensions.Count arrTupple(i - 1) = GetItem(i).itemID Next i ' Update gui with new value txtNewValue.Text = CF.System.Data.GetValue(arrTupple) ' Fill Array with selection for GetIceTargets ReDim arrTupple(0) As Variant ' Start out with an empty array For i = 1 To CF.System.Dimensions.Count ' Iterate through the dimensions If 5 <> CF.System.Dimensions(i).DimTypeID Then ' If this item is not a table dimension ReDim Preserve arrTupple(1 + UBound(arrTupple)) As Variant ' Add an element to the array arrTupple(UBound(arrTupple) - 1) = GetItem(i).itemID ' Fill the new element with the selection End If Next i ' Remove the last unused element ReDim Preserve arrTupple(UBound(arrTupple) - 1) As Variant On Error GoTo Skip ' Iterate through each target, adding that target's components For Each objDims In CF.System.Data.GetIceTargets(arrTupple) str = str & "(" ' New target For Each objDim In objDims ' Iterate through it's target components str = str & objDim(1).itemID & ", " ' Only one item in each component Next objDim str = Left(str, Len(str) - 2) & ") " ' End this target Next objDims lblTargets.Caption = str ' Update the interface Exit Sub Skip: End Sub
Developer Guide 79
' #### HELPER FUNCTIONS #### Private Sub LoadInterface() Dim n As Integer, objDim As CFDimension, objItem As CFItem For Each objDim In CF.System.Dimensions ' control index item, for creating new combo box n = lblDimName().Count ' Create a dimension label Load lblDimName(n) ' Create new label Set lblDimName(n).Container = frmDims ' Set label's parent lblDimName(n).Visible = True ' Show the label lblDimName(n).Top = 400 + lblDimName(n - 1).Top ' Move it to the correct position lblDimName(n).Caption = objDim.DimName ' Set it's caption to the Dimension name ' Create a combo for the items Names in this dimension Load cmbDimItems(n) ' Create a new combo Set cmbDimItems(n).Container = frmDims ' Set the combo's
box parent
cmbDimItems(n).Visible = True ' Show the combo box cmbDimItems(n).Top = 400 + lblDimName(n - 1).Top 'Move it to the correct position ' Create a combo for the items IDs in this dimension Load cmbDimItemIDs(n) ' Create a new combo box Set cmbDimItemIDs(n).Container = frmDims ' Set the combo's parent cmbDimItemIDs(n).Visible = False ' Hide the combo box cmbDimItemIDs(n).Top = 400 + lblDimName(n - 1).Top 'Move it to the correct position ' Add this dimensions items to the combo For Each objItem In objDim Items in this dimension cmbDimItems(n).AddItem objItem.ItemName the combo box cmbDimItemIDs(n).AddItem objItem.itemID ID to the mapping combo box Next objItem cmbDimItems(n).ListIndex = 0 selection Next objDim ' Update Interface frmDims.Visible = True frmItem.Visible = True frmFilter.Visible = False bLoaded = True End Sub Private Sub LoadInfo(index As Integer) Dim objDim As CFDimension, objItem As CFItem, oItem As CFItem, objAttr As CFAttribute Dim strSub As String, str As String ' Check the the interface has completed loading If Not bLoaded Then Exit Sub ' Get the item selected for submissions Set objItem = GetItem(1) strSub = objItem.itemID ' Iterate through ' Add the item to ' Add this item's ' Set the default
80

' Get the dimension for the combo box with the focus Set objDim = CF.System.Dimensions(index) lblDimID.Caption = objDim.DimId lblDimNm.Caption = objDim.DimName lblDimType.Caption = objDim.DimTypeID & ": " & objDim.DimType ' Get the item for the combo box with the focus Set objItem = GetItem(index) lblItemID.Caption = objItem.itemID lblItemName.Caption = objItem.ItemName lblLocked.Caption = objItem.GetLocked(strSub) lblCalc.Caption = objItem.GetCalcString(strSub) ' Iterate through the children for this item str = "" For Each oItem In objItem.GetChildren(strSub) str = str & oItem.itemID & ", " Next oItem If str <> "" Then str = Left(str, Len(str) - 2) lblChildren.Caption = str ' Iterate through the parents for this item str = "" For Each oItem In objItem.GetParents(strSub) str = str & oItem.itemID & ", " Next oItem If str <> "" Then str = Left(str, Len(str) - 2) lblParents.Caption = str ' Iterate through the Attributes for this item str = "" For Each objAttr In objItem.Attributes str = str & objAttr.Name & ": " & objAttr.value & vbNewLine Next objAttr txtAttributes.Text = str End Sub Private Function GetItem(index As Integer) As CFItem Dim idx As Integer, itemID As String idx = cmbDimItems(index).ListIndex ' Which item is selected in this combo? itemID = cmbDimItemIDs(index).List(idx) ' What is this Item's ID? Set GetItem = CF.System.Dimensions(index).Item(itemID) ' Get the CFItem object for this selection End Function Private Function BuildDimString(objDims As CFDimensions) As String Dim str As String, objDim As CFDimension For Each objDim In objDims str = str & objDim.DimId & "(" & objDim.Count & "), " Next objDim BuildDimString = Left(str, Len(str) - 2) End Function Private Sub txtNewValue_GotFocus() txtNewValue.SelStart = 0 txtNewValue.SelLength = Len(txtNewValue.Text) End Sub
Developer Guide 81
82
Index
Symbols
.dll, 32 .ini, 41, 42 classes (cont'd) CFSystem, 43 Connect, 13 XLFormulas, 48 XLInterface, 48 XLOptions, 52 Clear (subroutine), 40 Cognos Finance Web Services, 18 Cognos Web Services, 17 Color (property), 37 Columns (property), 37 Common Logon Server, 41 Connect (class), 13 ConnectionDelete (subroutine), 48 ConnectionEdit (subroutine), 49 ConnectionNew (subroutine), 49 connections exposing interface, 41 local, 42 modifying, 41 remote, 42 testing, 16 to local or remote systems, 17 Connections (property), 44 copyright, 2 Count (property), 15, 20, 30, 32, 40 counters component dimensions, 33 items in a dimension, 31
A
Access Manager, 41 Add (function), 20, 39 arrays, 32 Attributes (property), 34
B
batch queue using, 21 BatchAddValue (subroutine), 22 BatchGetValue (function), 23 BatchPost (function), 23 BatchTablesClear (function), 23 BatchUpdate (function), 23
C
calculated items, 34 CellAddr (property), 33 CFAPI (class), 13 CFAttribute (class), 13 CFAttributes (class), 15 CFConnection (class), 15 CFConnections (class), 20 CFData (class), 21 CFDimension (class), 30 CFDimensions (class), 32 CFErrItem (class), 33 CFItem (class), 34 CFMenuBarName (property), 48 CFReport (class), 36 CFReports (class), 39 CFScreens (class), 41 CFSystem (class), 43 CFToolBarName (property), 48 classes CFAPI, 13 CFAttribute, 13, 15 CFConnection, 15 CFConnections, 20 CFData, 21 CFDimension, 30 CFDimensions, 32 CFErrItem, 33 CFItem, 34 CFReport, 36 CFReports, 39 CFScreens, 41
D
Data (property), 44 Datadir (property), 15 DataPost (subroutine), 49 DataUpdate (subroutine), 49 Delete (subroutine), 20 DependencySub (property), 37 dialog boxes, 41 dimension buttons, 32 dimension IDs, 32 dimension items, 43 dimension names, 33 dimensions, 43 Dimensions (property), 37, 44 DimId (property), 30 DimName (property), 30 DimType (property), 30 DimTypeID (property), 31 Discover (subroutine), 16
E
EditConnection (subroutine), 41
Developer Guide 83
Index
enumerations error codes, 55 transfer filters, 63 ErrCode (property), 34 errDIIUnloaded (error code), 55 errDimMismatch (error code), 55 errDupSystem (error code), 55 errExcelAddin (error code), 56 errExcelBusy (error code), 56 errFailConnect (error code), 56 errFailCreate (error code), 56 errFailRegister (error code), 57 errFailStart (error code), 57 errFailTransfer (error code), 57 errInvalidArrArg (error code), 58 errInvalidCell (error code), 58 errInvalidDirectory (error code), 58 errInvalidItem (error code), 58 errInvalidLevel (error code), 58 errInvalidLogin (error code), 58 errInvalidNumArgs (error code), 58 errInvalidObject (error code), 59 errInvalidPerArg Constant (error code), 59 errInvalidReport (error code), 59 errInvalidSub (error code), 59 errInvalidSysId (error code), 59 errInvalidSystem (error code), 60 errInvalidTicket (error code), 60 errLoadDim (error code), 60 errLoadingCache (error code), 61 errLockedCell (error code), 61 ErrLookup (property), 44 errMissingArg (error code), 61 errNoConnections (error code), 61 errNoDelimiter (error code), 61 errNotLoggedIn (error code), 62 errNTLogFail (error code), 62 error codes errDimMismatch, 55 errDllUnloaded, 55 errDupSystem, 55 errExcelAddin, 56 errExcelBusy, 56 errFailConnect, 56 errFailCreate, 56 errFailRegister, 57 errFailStart, 57 errFailTransfer, 57 errInvalidArrArg, 58 errInvalidCell, 58 errInvalidDirectory, 58 errInvalidItem, 58 errInvalidlevel, 58 errInvalidLogin, 58 errInvalidNumArgs, 58 errInvalidObject, 59 errInvalidPerArg, 59 errInvalidReport, 59 errInvalidSub, 59 errInvalidSysId, 59 errInvalidSystem, 60 errInvalidTicket, 60 error codes (cont'd) errLoadDim, 60 errLoadingCache, 61 errLockedCell, 61 errMissingArg, 61 errNoConnections, 61 errNoDelimiter, 61 errNotLoggedIn, 62 errNTLogFail, 62 errTestFail, 62 errTieError, 62 errUnexpected, 63 overview, 55 errTestFail (error code), 62 errTieError (error code), 62 errUnexpected (error code), 63 events onChange, 52 onLogin, 46 onLogout, 46 onPost, 46 onUpdate, 47 exposing interface, 41 exposing StdPicture, 32
F
FileName (property), 37 Filter (property), 38 functions BatchGetValue, 23 BatchPost, 23 BatchTablesClear, 23 BatchUpdate, 23 CFAttributes.Item, 15 CFConnections.Add, 20 CFConnections.Item, 21 CFDimension.Item, 31 CFDimensions.Item, 33 CFReports.Add, 39 CFReports.Item, 40 GetCalcString, 34 GetCellsInError, 50 GetDimIds, 32 GetDimNames, 33 GetIceTargets, 24 GetItemIDs, 31 GetNames, 31 GetValue, 24, 26 Login, 41 NewLocalConn, 42 NewRemoteConn, 42 PostValue, 27, 28 SelectConnection, 42 SelectDimensions, 43 SelectItems, 43
G
GetCalcString (function), 34 GetCellsInError (function), 50 GetChildren (property), 35 GetDimIds (function), 32
84
Index
GetDimNames (function), 33 GetErrorDescription, 30 GetIceTargets (function), 24 GetItemIDs (function), 31 See also ItemID (property) GetLocked (property), 35 GetNames (function), 31 See also ItemName (property) GetParents (property), 35 GetValue (function), 24, 26 OutputDir (property), 17
P
Pages (property), 38 PasteFace (subroutine), 32 Picture (property), 32 pinging servers and ports, 16 Port (property), 17 ports, 18 pinging, 16 used to identify computers, 17 PostCFI (subroutine), 50 PostValue (function), 27, 28 properties Attributes, 34 CellAddr, 33 CFMenuBarName, 48 CFToolBarName, 48 Color, 37 Columns, 37 Connections, 44 Count, 15, 20, 30, 32, 40 Data, 44 Datadir, 15 DependencySub, 37 Dimensions, 37, 44 DimId, 30 DimName, 30 DimType, 30 DimTypeID, 31 ErrCode, 34 ErrLookup, 44 FileName, 37 Filter, 38 GetChildren, 35 GetLocked, 35 GetParents, 35 InputDir, 16 ItemID, 36 ItemName, 36 LogState, 46 Mode, 17 Name, 14 NumCmps, 33 NumTbls, 33 Options, 50 OutputDir, 17 Pages, 38 Picture, 32 Port, 17 ReadNames, 52 ReadOutput, 53 Reports, 47 Rows, 38 Scaling, 38 Server, 18 Switchable, 39 SysDesc, 18 SysID, 18, 39, 47 SysName, 18, 39, 48 SysoutDir, 19
I
identifiers (IDs), 31 IDs (identifiers), 31 InputDir (property), 16 interfaces exposing dialog boxes, 41 IP addresses, 18 Item (function), 15, 21, 31, 33, 40 item IDs, 31 ItemID (property), 36 ItemName (property), 36
L
Lexw.dll, 32 Lexw.ini, 41, 42 local systems toggling between remote, 17 logging on, 41 Login (function), 41 Login (subroutine), 44 Logout (subroutine), 46 LogState (property), 46
M
mLocal (value), 17 Mode (property), 17 mRemote (value), 17
N
Name (property), 14 names dimensions, 33 native security, 41 NewLocalConn (function), 42 NewRemoteConn (function), 42 NumCmps (property), 33 NumTbls (property), 33
O
Office.CommandBarButton customizing, 32 onChange (event), 52 onLogin (event), 46 onLogout (event), 46 onPost (event), 46 onUpdate (event), 47 Options (property), 50 OptionsEdit (subroutine), 50
Developer Guide 85
Index
properties (cont'd) SysRptsDir, 19 UpdateInput, 53 UpdateNames, 53 UserRptsDir, 19 Value, 14, 34 XLMenuBarName, 52
T
table dimensions, 33 tExcel (transfer filter), 63 ticket servers, 41 tMode (enumeration), 17 transfer filters overview, 63 tExcel, 63 tSelection, 63 tSheet, 63 tWorkBook, 63 tSelection (transfer filter), 63 tSheet (transfer filter), 63 tWorkBook (transfer filter), 63
R
ReadNames (property), 52 ReadOutput (property), 53 remote systems testing the connection to, 16 toggling between local, 17 Remove (subroutine), 41 Reports (property), 47 Rows (property), 38
U
UpdateCFD (subroutine), 51 UpdateCFI (subroutine), 51 UpdateCFNAME (subroutine), 52 UpdateInput (property), 53 UpdateNames (property), 53 UserRptsDir (property), 19
S
SaveSettings (subroutine), 53 Scaling (property), 38 SelectConnection (function), 42 SelectDimension (function), 43 SelectItems (function), 43 Server (property), 18 servers pinging, 16 ShowErrorComment (subroutine), 51 StdPicture, 32 submissions calculated items, 34 subroutines BatchAddValue, 22 CFConnections.Delete, 20 CFReports.Clear, 40 CFReports.Remove, 41 ConnectionDelete, 48 ConnectionEdit, 49 ConnectionNew, 49 DataPost, 49 Discover, 16 EditConnection, 41 Login, 44 Logout, 46 OptionsEdit, 50 PasteFace, 32 PostCFI, 50 SaveSettings, 53 ShowErrorComment, 51 UpdateCFD, 51 UpdateCFI, 51 UpdateCFNAME, 52 Switchable (property), 39 SysDesc (property), 18 SysID (property), 18, 39, 47 SysName (property), 18, 39, 48 SysoutDir (property), 19 SysRptsDir (property), 19
V
Value (property), 14, 34 version of document, 2
X
XLFormulas (class), 48 XLInterface (class), 48 XLMenuBarName (property), 52 XLOptions (class), 52
86

CoFe Developer Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CoFe Developer Guide

Uploaded by

Copyright:

Available Formats

Cognos Finance Developer Guide 29-09-2006 Cognos Finance 7.

SOFTWARE DEVELOPMENT KIT DEVELOPER GUIDE

Software Development Kit

Using This Document

Integrating with Cognos Products

Printing Copyright Materials

Software Development Kit

Chapter 1: Understanding and Using the Cognos Finance API

API Architecture in Cognos Finance

Chapter 1: Understanding and Using the Cognos Finance API

Software Development Kit

Chapter 1: Understanding and Using the Cognos Finance API

Using the Cognos Finance API

Using the Cognos Finance Add-in for Excel as an End-user

Chapter 1: Understanding and Using the Cognos Finance API

Using the Cognos Finance Add-in for Excel VBA Interface

Using the COM API as a Programmer Working External to Microsoft Excel

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Use the Batch Queue

Dimensions() Value flags

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Software Development Kit

Chapter 2: Classes Member of: CFXL.XLInterface (p. 48)

Member of: CFXL.XLInterface (p. 48)

XLMenuBarName (Hidden) Property

Software Development Kit

Chapter 3: Enumerations Member of: CFXL.ErrCodes (p. 55)

Software Development Kit

Software Development Kit

Appendix A: Sample VB Code

Make the Sample Code into an Executable Visual Basic Project

Sample File Login.frm

Appendix A: Sample VB Code

Software Development Kit

Appendix A: Sample VB Code

Appendix A: Sample VB Code

Sample File Main.frm

Software Development Kit

Appendix A: Sample VB Code

Appendix A: Sample VB Code

Software Development Kit

Appendix A: Sample VB Code

Appendix A: Sample VB Code

Software Development Kit

Appendix A: Sample VB Code

Appendix A: Sample VB Code

Software Development Kit