dsk devfwqed
DESCRIPTION
dsfcsdfsdfTRANSCRIPT
-
Desktop Intelligence DeveloperGuide
BusinessObjects XI 3.1
-
2008 Business Objects, an SAP company. All rights reserved. Business Objectsowns the following U.S. patents, which may cover products that are offered and
Copyright
licensed by Business Objects: 5,295,243; 5,339,390; 5,555,403; 5,590,250;5,619,632; 5,632,009; 5,857,205; 5,880,742; 5,883,635; 6,085,202; 6,108,698;6,247,008; 6,289,352; 6,300,957; 6,377,259; 6,490,593; 6,578,027; 6,581,068;6,628,312; 6,654,761; 6,768,986; 6,772,409; 6,831,668; 6,882,998; 6,892,189;6,901,555; 7,089,238; 7,107,266; 7,139,766; 7,178,099; 7,181,435; 7,181,440;7,194,465; 7,222,130; 7,299,419; 7,320,122 and 7,356,779. Business Objects andits logos, BusinessObjects, Business Objects Crystal Vision, Business ProcessOn Demand, BusinessQuery, Cartesis, Crystal Analysis, Crystal Applications,Crystal Decisions, Crystal Enterprise, Crystal Insider, Crystal Reports, CrystalVision, Desktop Intelligence, Inxight and its logos , LinguistX, Star Tree, TableLens, ThingFinder, Timewall, Let There Be Light, Metify, NSite, Rapid Marts,RapidMarts, the Spectrum Design, Web Intelligence, Workmail and Xcelsius aretrademarks or registered trademarks in the United States and/or other countriesof Business Objects and/or affiliated companies. SAP is the trademark or registeredtrademark of SAP AG in Germany and in several other countries. All other namesmentioned herein may be trademarks of their respective owners.
Business Objects products in this release may contain redistributions of softwarelicensed from third-party contributors. Some of these individual components may
Third-partyContributors
also be available under alternative licenses. A partial listing of third-partycontributors that have requested or permitted acknowledgments, as well as requirednotices, can be found at: http://www.businessobjects.com/thirdparty
2008-09-11
-
ContentsIntroduction 7Chapter 1
About this guide...........................................................................................8
Who should use this guide ....................................................................8
Business Objects information resources................................................8
Getting started with VBA 9Chapter 2
Accessing the development environment..................................................10
Language summary...................................................................................10
Variables...............................................................................................11
Procedures...........................................................................................11
Event implementation...........................................................................11
Flow control .........................................................................................12
Arrays...................................................................................................13
With statement.....................................................................................14
Error handling.......................................................................................14
The VBA Object Browser.....................................................................15
Including external object libraries.........................................................15
Some useful VBA functions and subroutines............................................16
VBA macros: migration overview 19Chapter 3
Migration of VBA macros to XI...................................................................20
VBA macros.........................................................................................21
VBA add-ins.........................................................................................21
Updating platform-related calls.............................................................21
Using the Import Wizard tool................................................................22
Server-side execution...........................................................................22
Desktop Intelligence Developer Guide 3
-
API changes..............................................................................................23
Deprecated APIs and their replacements............................................23
New interoperability in XI......................................................................26
OLAP data access with universes........................................................26
Application-level variables....................................................................27
Use cases..................................................................................................28
Scheduling by using DocAgentOption class........................................28
BCA custom macro migration...............................................................29
Document events, properties, and methods..............................................30
Event-related restrictions .....................................................................32
Other limitations...................................................................................33
Programming with Desktop Intelligence 37Chapter 4
Macros and subroutines............................................................................38
Creating a macro..................................................................................38
The Visual Basic tool bar......................................................................40
Add-ins.......................................................................................................41
Creating an add-in................................................................................42
Installing an add-in by using the interface............................................43
Desktop Intelligence events.......................................................................44
Event triggers.......................................................................................45
Implementing an event.........................................................................45
Implementing application events...............................................................46
Customizing the user interface 49Chapter 5
User interface classes...............................................................................50
Command Bars....................................................................................51
Controls................................................................................................51
Adding a command bar..............................................................................53
Displaying pop-up menus.....................................................................54
4 Desktop Intelligence Developer Guide
Contents
-
Adding controls to a command bar............................................................54
Adding faces to buttons: the Clipboard object......................................55
Adding actions to buttons.....................................................................56
Creating your own forms............................................................................57
Data providers 59Chapter 6
Working with existing data providers.........................................................60
Data provider types .............................................................................62
Loading and unloading a data provider................................................64
Get More Help 67Appendix A
Index 71
Desktop Intelligence Developer Guide 5
Contents
-
6 Desktop Intelligence Developer Guide
Contents
-
Introduction
1
-
About this guide on page 8
About this guideThis guide describes how to develop applications by using the DesktopIntelligence Software Development Kit (SDK).
Who should use this guide
This guide is intended for developers who want to use the DesktopIntelligence SDK to develop applications.
Business Objects information resources
For more information and assistance, see Appendix A: Get More Help. Thisappendix describes the Business Objects documentation, customer support,training, and consulting services, with links to online resources.
8 Desktop Intelligence Developer Guide
Introduction1 About this guide
-
Getting started with VBA
2
-
You can use Microsoft Visual Basic for Applications (VBA) to create custommacros and add-ins in Desktop Intelligence.The VBA is used by MicrosoftOffice products and several other Windows software products. Using VBA,you can integrate and customize applications that are already available onthe system desktop. However, you may encounter some limitations whileusing VBA on the Desktop Intelligence server. For more information, seeVBA macros: migration overview on page 19.
Comprehensive on-line help about the VBA development environment andlanguage is available from the VBA Help menu. You can also press F1 inthe VBA development environment to access VBA Help menu.
This chapter describes how VBA enables you to extend the capabilities ofDesktop Intelligence. This chapter also describes how to develop macrosand add-ins by using VBA, to control the Desktop Intelligence and Designerenvironments, as well as perform queries and analysis on data in documentsthrough universes and data providers.
Accessing the development environmentDesktop Intelligence contains a Visual Basic editor, which you can use todevelop macros and add-ins. You can access the Visual Basic editor fromthe Visual Basic tool bar. If the editor is not displayed, right-click the tool baror menu bar, and select Visual Basic. You can also access the Visual Basiceditor from the Macros submenu in the Tools menu.
The Visual Basic editor is the standard Microsoft VBA editor, which is includedin the Microsoft Office 2000 suite. Hence, you can use tools such as ObjectBrowser and Project Explorer. Online help for VBA is also available from theVisual Basic editor.
Language summaryThis section provides an overview of the VBA language. It also discussessome of the key features of VBA language.
For information about Visual Basic and VBA, see the Microsoft documentation.
10 Desktop Intelligence Developer Guide
Getting started with VBA2 Accessing the development environment
-
Variables
The VBA supports the following data types: Boolean Byte Integer Long Single Double Currency Date Object String Variant user-defined
You can declare variables by using the Dim keyword, as follows:
Dim Name As String
Procedures
The VBA supports two different type of procedures: functions andsub-routines. Functions can return values, whereas subroutines do not returnvalues.
Event implementation
The VBA is event-driven, that is, the code is executed when certain eventstake place in the application. Examples of events include a user opening adocument and a user clicking a button. The execution of the code when anevent occurs is called event implementation.
The Universe Designer SDK does not have any events to implement. Thisimplies that you cannot write a code to respond to events in the Designer
Desktop Intelligence Developer Guide 11
2Getting started with VBALanguage summary
-
application. However, you can use the Designer object model whileimplementing events of other applications.
For more information on implementing events, see Desktop Intelligenceevents on page 44 and Creating your own forms on page 57.
Flow control
The following table discusses the most commonly used VBA flow controlstructures:
DescriptionControl
Tests a condition, and based on theresult of the test, alters the executionflow
If-Then-Else
Repeats an action the specifiednumber of times.For-Next
Repeats an action while a conditionis trueWhile-Wend
Repeats an action either when acondition is true, or until it becomestrue
Do-Loop
Branches to one of several possiblecode segments, based on the valueof a variable or the outcome of a test.
Select-Case
Repeats an action on each object ina collection or on each item in an ar-ray
For-Each-Next
12 Desktop Intelligence Developer Guide
Getting started with VBA2 Language summary
-
Arrays
An array is a variable that contains multiple values. Each value is indexedand all the elements in the array belong to the same data type.
The VBA supports multi-dimensional arrays.
Declaring an array
To declare an array in VBA, use the following syntax:
Dim ArrayName(n, m, ..., z) As DataType
where: n, m, , z are integers that represent the size of a dimension. InVBA, you can declare an array with up to 60 dimensions.
Example: Declaring a two dimensional array
The following VBA code fragment declares an array with two dimensions:
Note:The size of each dimension is determined by the constant MAX_CUSTOMERS.
Const MAX_CUSTOMERS As Integer = 500Dim customers(MAX_CUSTOMERS, MAX_CUSTOMERS) As String
Array indexes
By default, the first element of an array is element 0 and the last is n. Youcan change the array elements by using Option Base statement.
Option Base statement
The Option Base statement enables you to set the lower bound for all arraysto either 1 or 0.
For example:
Option Base 1Array(1) 'reference the first element
Desktop Intelligence Developer Guide 13
2Getting started with VBALanguage summary
-
is the same as:
Option Base 0Array(0) 'reference the first element
Array indexing that starts at a number other than 1 or 0
If you want the index of an array to start at a number other than 1 or 0, youmust specify the bounds in the array declaration. For example:
Dim RawData(10 To 20) As Variant
RawData has 11 elements. The first is element number 10 and the last iselement number 20.
With statement
The With statement tool enables you to abbreviate object references.
Example: Using a With statement in an object reference
The following code fragment sets the properties of an object by using theWith statement:
With Application.ActiveDocument.DataProviders.Item(1).Queries
.DuplicateRows = TRUE
.DeleteTrailingBlanks = TRUE
.ScopeOfAnalysis = boThreeLevelsDownEnd With
Error handling
You can use the On Error statement to handle errors generated during theexecution of a code.
If you don't use an On Error statement, any run-time error that occurs canprove to be critical. That is, an error message is displayed and the executionstops.
14 Desktop Intelligence Developer Guide
Getting started with VBA2 Language summary
-
Example: Handling errors with the On Error statementSub Convert(...)On Error Goto ErrorDisplay... 'if an error occurs here go to ErrorDisplayExit SubErrorDisplay: MsgBox Err.Number & "-" & Err.DescriptionSub End
You can ignore errors by using the following statement:
On Error Resume Next
Note:This statement can hinder debugging.
The VBA Object Browser
The VBA development environment includes a number of tools, to enableyou to run, debug, and move the code around. One of the most useful toolsis the Object Browser.
The Object Browser displays all the programmable objects that are installedand registered on the system along with their associated properties, methods,and events. You can also use the Object Browser to browse the proceduresand module-level variables in your own VBA projects.
To open the Object Browser, select Object Browser from the View menu.
Including external object libraries
To access the object models of other products, such as Designer or MicrosoftOutlook, from the VBA program, create a reference to the appropriate objectlibrary. After creating the reference, you can use the classes, methods, andproperties provided in the object model.
Referring to an external object library from VBA
To refer to an external object library from VBA, complete the following steps:
1. In the Tools menu, select References.
Desktop Intelligence Developer Guide 15
2Getting started with VBALanguage summary
-
If the reference is successful, the name of the object library you referencedappears in the Object Library drop-down list in the VBA Object Browser.
2. Select the object library from the list, and click OK.
Some useful VBA functions andsubroutines
The following table discusses some useful VBA functions and subroutines:
DescriptionName
Returns the absolute value of anumberAbs
Returns the current MS-DOS pathCurDir
Returns a character if its ASCII codeis givenChr
Returns the current system dateDate
Causes execution to break out of aDo loopExit Do
Causes execution to break out of aFor loopExit For
Causes execution to break out of afunctionExit Function
16 Desktop Intelligence Developer Guide
Getting started with VBA2 Some useful VBA functions and subroutines
-
DescriptionName
Causes execution to break out of asub-routineExit Sub
Returns the integer portion of anumber, after rounding down positivenumbers and negative numbers
Fix
Returns the integer portion of anumber, after rounding down positivenumbers and negative numbers
Int
Returns TRUE if an expression is anarrayIsArray
Returns TRUE if an expression is adateIsDate
Returns TRUE if no value is assignedto a variableIsEmpty
Returns TRUE if an expression is anerror valueIsError
Returns TRUE if an expression eval-uates to NULLIsNull
Returns TRUE if an expression eval-uates to a numberIsNumeric
Desktop Intelligence Developer Guide 17
2Getting started with VBASome useful VBA functions and subroutines
-
DescriptionName
Returns TRUE if an expression rep-resents an objectIsObject
Returns the lower bound of an arrayLBound
Returns the length of a string, or thenumber of bytes required to store avalue
Len
Returns the current date and timeNow
Runs an executable programShell
Returns the square root of a numberSqr
Performs a string comparisonStrComp
Returns the current system timeTime
Returns the data type of a variableTypeName
Returns the upper bound of an arrayUbound
18 Desktop Intelligence Developer Guide
Getting started with VBA2 Some useful VBA functions and subroutines
-
VBA macros: migrationoverview
3
-
BusinessObjects XI Release 2 (referred to as "XI R2") and BusinessObjectsXI 3.0 (referred to as "XI 3.0") are new versions of BusinessObjects XI. BothXI R2 and XI 3.0 enable majority of classic BusinessObjects customers tomove to the XI platform. The migration protects customers' investment in theBusinessObjects technology by delivering the following key features:
Note:Unless specifically mentioned, XI R2 and XI 3.x are collectively referred toas XI.
A direct migration path and a set of migration tools for customers whohave deployed BusinessObjects 5.1 (or Web Intelligence 2.7), 6.0, 6.1,or 6.5.
Desktop Intelligence: The BusinessObjects full client (which is renamedas Desktop Intelligence) is part of XI. It benefits from the enhancementsin the new platform, such as Unicode support, report instances, anddiscussions.
Web Intelligence: XI provides a much-enhanced version of WebIntelligence, which enables a large number of customers to move theirentire business intelligence (BI) solution to the web.
The XI provides a direct migration path from BusinessObjects 5.1/6.x. Thissection provides information about the migration of VBA macros to XI.
Migration of VBA macros to XIA number of BusinessObjects customers have developed VBA macros orVBA add-ins for the BusinessObjects Desktop Intelligence product.
The VBA macros or add-ins developed for 5.1/6.x work with DesktopIntelligence supported in XI. Most VBA macros developed for 5.1/6.x workin XI. However, some macros are not supported on the server side.
Support depends on the nature of the code and the location of the codeexecution. The following table discusses support for VBA macros in XI:
VBA add-insVBA macros
YesYesClient side
NoYes with restrictionsServer side
20 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Migration of VBA macros to XI
-
VBA macros
The VBA macros are embedded in .rep documents. You can migrate .repdocuments to XI in one of the following ways:
Corporate documents (that is, .rep documents located in the sourcerepository) can be migrated to the XI repository by using the Import Wizardtool.
Local documents (that is, .rep documents located on the desktop of thesystems) can be migrated to XI by opening and saving these documentswith Desktop Intelligence.
In both cases, after migration, VBA macros remain embedded in .repdocuments in XI.
VBA add-ins
Each VBA add-in is a separate file with a .rea (report add-in) extension. TheVBA add-ins do not run on the server side (that is, on the BusinessObjectsEnterprise server) in XI.
Updating platform-related calls
The macros that work at the document level (for example, macros thatexecute queries, filter a report, or re-format a report) continue to work in XI.
However, platform-related macros must be updated to reflect the newunderlying BusinessObjects Enterprise SDK. Following are the key changesin XI:
SDK name: In XI, the SDK is called the Desktop Intelligence SDK.However, for compatibility with previous versions, ProgIDs and othertechnical names used in the code remain unchanged.
Repository interaction: Login, document send/retrieve, and reference torepository universes require code update.
Send to Inbox or BCA is no longer available: To send to Inbox or BCA,you must now use the Enterprise SDK.
Desktop Intelligence Developer Guide 21
3VBA macros: migration overviewMigration of VBA macros to XI
-
Related Topics Scheduling by using DocAgentOption class on page 28
Using the Import Wizard tool
Import Wizard is a migration tool that enables you to move content from5.1/6.x to an XI repository. However, the Import Wizard does not check VBAcode contained in .rep documents and whether the VBA macros must beupdated or not. Hence, after migration, VBA macros must be checked andvalidated manually.
Some customers store VBA add-ins in the 5.1/6.x repository. Like agnosticdocuments, the VBA add-ins (.rea files) are migrated by using the ImportWizard. Hence, these add-ins are copied to the XI repository.
Server-side execution
The following is a brief description of the changes in the XI server-sideexecution:
Architecture - On the XI platform, the V5/V6 BOManager component isreplaced by the RAS21 component. While BOManager was amulti-document component, RAS21 is a mono-document component.This explains a number of restrictions on server side.
BCA custom macros - The BOE scheduler does not support custom VBAmacros. For more information, see BCA custom macro migration onpage 29.
VBA add-ins - The VBA add-ins cannot be executed on the server. Forexample, a document that includes a Web Connect data provider cannotbe refreshed (DPVBAInterface code must be in the document itself to beexecuted).
CreateObject ("BusinessObjects.Application") - CreateObject will fail usingDesktop Intelligence report engine as it is not a COM automation server.On the server, the Desktop Intelligence SDK runs only in VBA, not in VB.However, you can install the Desktop Intelligence client component onthe server and move the code to a VB program.
22 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Migration of VBA macros to XI
-
Replace ActiveDocument with ThisDocument - While ActiveDocumentand ActiveReport still work on the client side, they no longer work on theserver side. Hence, they must be replaced.
API changesSome APIs have been removed while others have been updated (with a newoperability defined in XI). This section discusses changes in the APIs.
Deprecated APIs and their replacements
The following tables discuss the APIs that are deprecated and the APIs thatare introduced as replacements:
Login
Replacement in XI6.x API- Removed
Function
Application. Logon (User As String,Password As String, CMS As String,Mode As String, ThreeTier AsBoolean, Offline As Boolean) AsBoolean
Function
Application.LogonWithToken (tokenAs String) As Boolean
Function
Application.LogonDialog ()AsBoolean
Function
Application.LoginAs ([User As String],[Pass As String], [Offline AsBoolean], [RepositoryName AsString]) As Boolean
CMS name supersedes repositoryname (.key file)
Desktop Intelligence Developer Guide 23
3VBA macros: migration overviewAPI changes
-
Document exchange
Replacement in XI6.x API- Removed
Sub Document.SaveToEnter-prise(Folder As string, CategoryListAs String, Overwrite As Boolean)
Sub Document.SaveToEnterpriseDi-alog()
Note:Send to inbox and scheduling are notavailable in Destkop Intelligence SDK.You must use the BOESDK destinationplug-in.
Sub Document.Send([User AsString], [StoreGeneratedHTML AsBoolean], [HtmlLayout As BoHTML-Layout], [CategoryList As String],[ExchangeMode As BoExchange-Mode], [ExchangeDomain As String])
HtmlLayout obsolete with dhtmlviewer
Application.BoExchangeMode
Function
Documents.OpenFromEnter-pris(Name As String, Folder, AsString) As Document
Function
Documents.OpenFromEnterpriseDia-log() As Document
Retrieve from inbox and from sc arenot available in Destkop IntelligenceSDK. You must use the BOESDKdestination plug-in.
Sub Documents.Receive([Name AsString], [DestDir As String])
Enum BODocumentLocation = boEnter-priseFolderApplication.BoExchangeMode
24 Desktop Intelligence Developer Guide
VBA macros: migration overview3 API changes
-
Replacement in XI6.x API- Removed
Function
Documents.OpenFromEnterpriseDia-log(DocumentOrigin As BODocumen-tOrigin) As Document
Sub Documents.Receive([Name AsString], [DestDir As String])
No replacement in XI
Application.BoExchangeModeDistinctmethod replace echange mode Appli-cation.ExchangeDomain Folders su-persede domains
Scheduling
Replacement in XI6.x API - Removed
You must use the BI PLATFORMSDK while migrating
Class DocAgentOption
Domains replaced by enterprise folders
Replacement in XI6.x API - Removed
Function AddQueryTechnique(Uni-verseName As String, EnterpriseFold-erName As String)
Function DataProviders.AddQueryTechnique(UniverseName As String,[UniverseDomainName]) As DataPro-vide
Desktop Intelligence Developer Guide 25
3VBA macros: migration overviewAPI changes
-
Replacement in XI6.x API - Removed
No replacement in XIProperty Universes.Item(Index AsVariant, [RepositoryName As String])As Universe )
No replacement in XIUniverse.DomainName
New interoperability in XI
The following objects are subject to new interoperability in XI: Universe.CUID (Read-only)
Document.CUID (Read-only)
Application.LogonWithToken()
OLAP data access with universes
In XI, you can build universes on top of MS Analysis Services, Essbase, andSAP BW cubes. Hence, the OLAP data provider is removed from DesktopIntelligence and the SecurityPrompts class is obsolete.
Note:Desktop Intelligence documents support only SAP BW universes.
New interoperability API in XI6.x API
No replacement in XIClass SecurtyPrompts
26 Desktop Intelligence Developer Guide
VBA macros: migration overview3 API changes
-
New interoperability API in XI6.x API
No replacement in XI
Sub Application.SetSecurityPrompt(sUserName As String,sUserPasswordVarName As String,sUserPassword As String, sDBNameAs String, sDBPasswordVarNameAs String, sDBPassword As String)
No replacement in XIFunction Document.GetSecurityPrompts() As Security Prompts
Application-level variables
The variables available through collection Application.Variables havechanged. The following table summarizes the changes:
Variable nameAvailability of variables
BOLANGUAGE
BOSECURITYDOMAIN
BOUSER
BUSER_UPPER
6.5 variables available in XI
Desktop Intelligence Developer Guide 27
3VBA macros: migration overviewAPI changes
-
Variable nameAvailability of variables
COMPUTERNAME
CommonProgramFiles
HOMEDRIVE
HOMEPATH
ProgramFiles
SystemDrive
SystemRoot
USERDNSDOMAIN
USERDOMAIN
USERNAME
USERPROFILE
6.5 variables not available in XI
DOCNAMENew variable in XI
Windows system variables such as TEMP andPROCESSOR_ARCHITECTURE are available in both XI and 6.5.
Use casesThis section briefly describes the use cases of Desktop Intelligence SDK.
Scheduling by using DocAgentOption class
The DocAgentOption calls must be replaced by Enterprise SDK schedulingAPI, because scheduling is no longer supported in Desktop Intelligence SDK.
28 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Use cases
-
In the following use case for Application.LogonWithToken andDocument.CUID, Desktop Intelligence SDK and Enterprise SDK interoperate.
Login BusinessObjects Full ClientApplication.LogonWithToken(EntSession.LogonTokenMgr.CreateLogonEx) Dim strCUID As String
Call to BusinessObjects FC SDK to get document's CUIDstrCUID = Application.Documents( " DocumentToScedule " ).CUID
Retrieve the InfoStore objectDim IStore As InfoStoreSet IStore = EntSession("IStore")
Retrieve the BI PLATFORM SDK InfoObject that corresponds to the documentto be scheduledSet Result=IStore.Query("SELECT SCHEDULEINFO FROM CI_INFOOBJECTS_ WHERE SI_CUID = ' "+strCUID + "'""")Dim FCDocumentObject As InfoObject
Retrieve the first documentSet FCDocumentObject =Result.Item(1)Dim FCScheduleInfo As SchedulingInfo
Use the scheduling object to set the scheduling optionsSet FCScheduleInfo = FCDocumentObject.SchedulingInfo
FCScheduleInfo.Type=4 (Schedule is monthly.)FCScheduleInfo.IntervalMonths = 2FCScheduleInfo.RightNow = 1
Schedule the documentIStore.Schedule Result
BCA custom macro migration
A use case for BCA Custom Macro is the Automatic distribution throughemail of BusinessObjects documents in PDF format.
How it was done in 6.5:
Desktop Intelligence Developer Guide 29
3VBA macros: migration overviewUse cases
-
A publisher.rep document contained the Sub ENotify() VBA macro to opendocuments, save them in PDFformat, and send notification emails.
The publisher.rep document was scheduled through BCA; action specifiedthe execution of VBA code embedded in the document.
How to migrate it to XI:
The following are the two options to migrate from 6.5 to XI: Option 1:
1. Move the code from VBA to a VB Program.2. Install Desktop Intelligence on the same machine as the
BusinessObjects XI Server.3. Use InfoView or BusinessObjects Enterprise SDK to schedule the VB
program object. For more information, see Scheduling by usingDocAgentOption class on page 28.
Option 2:1. Call VBA ENotify () in document event handler: Sub
Document_AfterRefresh()2. Use InfoView or BusinessObjects Enterprise SDK to schedule
publisher.rep refresh. For more information, see Scheduling by usingDocAgentOption class on page 28.
Document events, properties, andmethods
The following tables discuss the document events, properties, and methodsused in Desktop Intelligence client and their support on server side:
Desktop IntelligenceInfoViewDoc Event
OKOKOpen
OKOKBeforeRefresh
OKOKAfterRefresh
OKDoesn't workBeforeClose
30 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Document events, properties, and methods
-
Desktop IntelligenceInfoViewDoc Event
OKNot supported by procFCActivate
OKNot supported by procFCDeActivate
OKDoesn't work (Bug)Beforesave
Desktop IntelligenceInfoViewProperty
OKOKThisDocument
OKDoesn't work (normal be-cause there is no Activatein ProcFC)
ActiveDocument
OKDoesn't work (there is noActivate in procFC)ActiveReport
Desktop IntelligenceInfoViewMethod
OKDoesn't workThisDocument.Save
OKDoesn't workThisDocument.SaveAs
OKDoesn't workThisDocument.SaveToEnterprise
OKOKThisDocument.ExportAsPDF
OKOKThisDocument.ExportAsXML
Desktop Intelligence Developer Guide 31
3VBA macros: migration overviewDocument events, properties, and methods
-
Event-related restrictions
Desktop Intelligence generates the following events: OpenEvent BeforeRefresh AfterRefresh BeforeClose
However, these events are generated inconsistently.
The following table discusses the events generated by Desktop Intelligence:
DescriptionEvent
In Report Server, this event is gener-ated when the document is openedfor the first time (from the browser).Report Server spawns a new childprocess to handle the document.Based on user rights and other secu-rity information, this child process isshared among the different usersessions. Hence, next time the samedocument is opened by the sameuser or a different user with similarrights, this event is not generated.
Note:If the document goes to Cache, thisevent is not generated.
OpenEvent
These events are generated all thetime in Report Server and Job Serv-er. However, their functionality islimited.
BeforeRefresh AfterRefresh
32 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Document events, properties, and methods
-
DescriptionEvent
This event is generated inconsistentlyin the Report Server. The documentcloses when the child process ex-pires, because the child processesare shared. Hence, this event isgenerated when the document closes(in the child process and not in theviewer).
BeforeClose
Other limitations
The following are the limitations of Desktop Intelligence: When a Desktop Intelligence document is in Cache, the processing server
does not trigger any event. Hence, no event is generated while a documentis being opened or closed.
The AfterRefresh event has the following limitation: Changes made bythe user (on the document) may not work all the time, because of the RESDK protocols. For example, if you set a prompt in the background, itmay not be set to the value.
The Desktop Intelligence server plug-in is mono-document; that is, it isdesigned to handle a single document at a time. Hence, some of the APIsrelated to OpenDocument may not work on the server side.
Architectural limitations in RAS21: The documents are stateless. They forward the requests to the plug-in.
It is the responsibility of the plug-in to maintain the state (of thedocument it is handling).
The Desktop Intelligence Server is more suitable for a single documentrather than multiple documents.
Testing limitations
This section describes how to test the limitations of Desktop Intelligence.
Desktop Intelligence Developer Guide 33
3VBA macros: migration overviewDocument events, properties, and methods
-
State of the document
The following is the list of SDK APIs that change the state of the document.The Viewer/RAS 21 does not track these changes.
Open Document - Fails on both BeforeRefresh and AfterRefresh events.
Set Prompt - Fails on AfterRefresh event and partially passes onBeforeRefresh.
For example, pass the value through SDK on both BeforeRefresh andAfterRefresh events. Consider, Country = US.1. Click Refresh.2. Select a value from LOV when prompted.3. Set a different value (for example, Country = France) using SDK.4. Run the report.
The data relative to US is displayed even if you manually select France.
Workaround for setting prompts: Use Application.Variables() insteadof Document.Variable(). It is added to the list of Application variables.
Regression Risk: If another document with the same prompt name isrefreshed in the same process, it uses the previously set value andthe prompt does not appear.
Refresh Data Provider - Fails on both BeforeRefresh and AfterRefreshevents.
Change Universe of a Data Provider - Fails on both BeforeRefresh andAfterRefresh events.
Close Document - Fails on both BeforeRefresh and AfterRefresh events.
RE SDK protocol
When you perform any of the operations discussed in this section, the reportin the viewer and the actual report in the server do not match.
The following operations impact the RE SDK protocol:
Change the value of the prompt before/after refresh - Fails on AfterRefreshand partially passes on BeforeRefresh.
For example, pass the value through SDK on BeforeRefresh event forthe prompt. Consider, Country = US.
34 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Document events, properties, and methods
-
1. Click Refresh.2. Select a value from LOV when prompted.3. Set a different value (for example, Country = France) using SDK.4. Run the report.
The data relative to US is displayed even if you manually select France.
Any operation that changes the report map (use different prompt)
Operations on the viewer, such as trying to open a report map entry thatdoes not exist, give inconsistent results, or may fail.
Note:The following functions may not work on both BeforeRefresh and AfterRefreshevents: Opening a new document Performing operations such as refresh, edit, close, and so on, in a new
document Creating a new application from an existing application
The Desktop Intelligence server does not support opening multiple documentsin a process. Hence, these operations are not implemented.
Desktop Intelligence Developer Guide 35
3VBA macros: migration overviewDocument events, properties, and methods
-
36 Desktop Intelligence Developer Guide
VBA macros: migration overview3 Document events, properties, and methods
-
Programming with DesktopIntelligence
4
-
This chapter describes how to program with Desktop Intelligence.
This chapter discusses the following topics:
Macros and subroutines
Add-ins
Desktop Intelligence events
Implementing application events
Macros and subroutinesA macro is a series of commands and functions that automate tasks youneed to perform regularly. A macro is saved within a document and is enabledeach time you open the document. You can send a document containing amacro to other users, just as you can send a regular Desktop Intelligencedocument.
You can create macros in Desktop Intelligence by using the integrated VBAenvironment.
Creating a macro
To create a macro, complete the following steps:
1. From the Tools menu, select Macro.
2. On the submenu, select Macros.
The "Macros" dialog box appears, as shown in the following figure:
38 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence4 Macros and subroutines
-
In the "Macros" dialog box, the names of add-ins, the macros containedin the open document, or a combination of both is displayed.
3. Enter a name for the macro, and click Create. The VBA environment isopened, and a module containing a skeleton sub-routine for the macrois created, as shown in the following figure:
4. Begin writing the macro.
When you finish writing and compiling the macro successfully, select Closeand Return to Desktop Intelligence from the File menu. You can now run
Desktop Intelligence Developer Guide 39
4Programming with Desktop IntelligenceMacros and subroutines
-
the macro from the "Macros" dialog box. If you want, you can also associatethe macro with a button on the tool bar. For more information, seeCustomizing the user interface on page 49.
The Visual Basic tool bar
You can hide or show the Visual Basic tool bar in Desktop Intelligence byright-clicking another tool bar or the menu bar, and selecting Visual Basic.You can also select Toolbars from the View menu, as shown in the followingfigure:
The Visual Basic tool bar contains the following buttons:
Run Macro - Click Run Macro to browse and run a macro.
Visual Basic Editor - Click Visual Basic Editor to open the VBAenvironment for editing a procedure or a macro.
Run Associated Macro - Click Run Associated Macro to run a macroassociated with this button.
Adding macros to the Visual Basic tool bar
On the Visual Basic tool bar, you can associate up to five buttons with amacro.
To associate a macro with a button, complete the following steps:
1. In the Tools menu, click Options.
2. In the "Options" dialog box, click the Macros tab.
The Macros panel is displayed, as shown in the following figure:
40 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence4 Macros and subroutines
-
3. Click the check box besides the number of the button with which you wantto associate the macro.
4. Type the name of the macro in the text box to the right. Alternatively, youcan click Browse besides the text box to select a macro. When a macrois selected, the edit box displays AddIn.rea!module.macro orDocument.rep!module.macro.
5. Enter a tool tip for the macro (optional).
6. Click OK.
If a button has an associated macro, it no longer appears grayed on the toolbar. The macro details are now hidden. You can run the macro by clickingthe respective button on the Visual Basic tool bar.
Add-insAdd-ins are programs that provide optional commands and features toDesktop Intelligence. Each add-in is saved with a .rea extension.
Desktop Intelligence Developer Guide 41
4Programming with Desktop IntelligenceAdd-ins
-
Before you can use an add-in, you must load it on your computer and theninstall it in Desktop Intelligence. Once you install an add-in, it becomesavailable each time you launch Desktop Intelligence.
To conserve memory, uninstall add-ins you do not use often. Uninstalling anadd-in removes its features and commands from Desktop Intelligence.However, the add-in program remains on the computer so that you can easilyinstall it again.
Unlike macros, add-ins are not associated with a single documentonceinstalled, an add-in functions just like any other feature of the DesktopIntelligence application.
You can distribute add-ins you have created to other users, and retrieve anduse add-ins that others have created.
Note:Starting with XI, the add-ins are not supported when a Desktop Intelligencedocument is used on the server to perform any of the following tasks: refreshing scheduling publishing
Creating an add-in
You can create add-ins in Desktop Intelligence, and distribute them amongother users or save them to BusinessObjects Enterprise.
To create an add-in, complete the following steps:
1. Create a new document.
2. Open the VBA editor.
3. Write and compile the add-in.
4. In the File menu, select Close and Return to Desktop Intelligence.
5. In the File menu, select Save As....
6. In the Save as type list box, select Desktop Intelligence Addins (*.rea).
You can now distribute your add-in among other users.
42 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence4 Add-ins
-
When you save the document as an add-in, a copy of the document is saved.If you make further changes, you must use Save As rather than Save toupdate the saved add-in.
Tip:To optimize the performance of the system, use one large .rea file containingmany subroutines, rather than using multiple .rea files.
Installing an add-in by using the interface
To install an add-in, you must save it on the computer and then install it inDesktop Intelligence.
To install an add-in by using the interface, complete the following steps:
1. Save the add-in on the computer.
2. In the Tools menu, select Add-Ins.
The "Add-Ins" dialog box opens, as shown in the following figure:
3. Click the check box of the add-in you want to install. If it is not displayedin the "Add-Ins" dialog box, click Browse to search.
4. Click OK.
You can run an installed add-in from the Macros dialog box, or you canassociate it with a button on the Visual Basic tool bar. For more information,see Customizing the user interface on page 49.
Desktop Intelligence Developer Guide 43
4Programming with Desktop IntelligenceAdd-ins
-
Desktop Intelligence eventsAn event is a change in the state of Desktop Intelligence, for which you canprogram a response. For example, you can program Desktop Intelligenceto display a dialog box whenever a user opens a document. Programminga response to an event is called implementing the event.
In Desktop Intelligence, you can implement events concerning DesktopIntelligence documents (*.rep and *.rea). These events are made availablein general and specific senses. That is, you can implement an event for anydocument, or only when it happens to a particular document.
General document events, those that apply to any document, belong to theApplication class and are called application events.
Specific document events, those that apply to specific documents, belongto the Document class and are called document events.
The following table lists the application events and document events thatyou can implement in Desktop Intelligence:
Document eventsApplication events
ActivateDocumentActivate
AfterRefreshDocumentAfterRefresh
BeforeCloseDocumentBeforeClose
BeforeRefreshDocumentBeforeRefresh
BeforeSaveDocumentBeforeSave
DeactivateDocumentDeactivate
44 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence4 Desktop Intelligence events
-
Document eventsApplication events
OpenDocumentOpen
NewDocument
Event triggers
Events can be triggered by user actions or by use of methods in the DesktopIntelligence SDK. For example, a BeforeRefresh event (application anddocument) is triggered when the user clicks the Refresh button in the DesktopIntelligence user interface, or when the user calls the Document.Refreshmethod.
Triggering the events on the server side by using Desktop Intelligencedocument has certain limitations.
Notes on the order in which the events occur
Events in Desktop Intelligence occur in the following order:
Document events are triggered before Application events.
BeforeClose occurs before BeforeSave.
If the focus is moved from Doc1 to Doc2, the order of events isDoc1_Deactivate followed by Doc2_Activate.
When a document is opened, the Open event occurs followed by Activate.
Implementing an event
Each event that you can implement appears in the VBA procedure list for itscorresponding object.
Desktop Intelligence Developer Guide 45
4Programming with Desktop IntelligenceDesktop Intelligence events
-
To implement an event, insert the code that you want to execute in theprocedure corresponding to the event when the event occurs.
This process is identical to implementing form events in the user interface.For more information, see Creating your own forms on page 57.
Example: Implementation of the DocumentBeforeRefresh event
The following code may be useful for a document that takes a long time torefresh:
Private Sub Document_BeforeRefresh(Cancel As Boolean)'user's response to the messageDim Response As VariantResponse = MsgBox("Are you sure you want to refresh?", vbOKCancel)
If Response = vbCancel Then'user chose cancel, so cancel the refreshCancel = TrueElse'user didn't cancel, so continue with refreshCancel = FalseEnd IfEnd Sub
Implementing application eventsYou cannot implement application events directly. To access the events ofthe Application object, you need to create a reference to the object andimplement the events of the reference.
46 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence4 Implementing application events
-
To create a reference to the Application object, complete the following steps:
1. Create a class module in VBA.
2. In the definition of the class you created, include a property of type"Application". Declare the property as "Public" and "WithEvents".
The property (reference) you created appears in the object drop-downlist in the code window of the class.
3. In a module, create an object of the type you created in step 1.
4. In a subroutine, set the variable's Application property to the Applicationobject.
The subroutine must execute before the implementation of the applicationevents is triggered.
5. Implement the events of the reference to the Application object.
The events for the application reference property appear in the proceduredrop-down list in the code window of the class module you created instep 1.
The following diagramatic representation illustrates this sequence:
The events for the application reference property (boapp) appear in theprocedure list of the application reference class (AppRefClass).
Desktop Intelligence Developer Guide 47
4Programming with Desktop IntelligenceImplementing application events
-
Example: Accessing events of the Application object
The following code fragments show the VBA statements you need toestablish a reference to the Application object. Once you have establishedthis reference, you can implement application events.
In a VBA class module called AppRefClass, for example, declare anApplication property called, for example, boapp, as follows:
PublicWithEvents boapp As Application
The Public part of the declaration makes the property globally available.The WithEvents part of the declaration enables you to access the eventsdefined for the Application class. For more information on the Public andWithEvents keywords, see the Visual Basic documentation.
In another module, create an instance of AppRefClass called, for example,AppRef, as follows:
Dim AppRef AsNew AppRefClass
Then, in a sub-routine, set AppRef.boapp, as follows:
Sub Initialize()Set AppRef.boapp = Application...End
Sub
Now, the events of the Application object can be implemented by usingAppRef.boapp.
48 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence4 Implementing application events
-
Customizing the userinterface
5
-
This chapter describes how to customize the user interface by using theDesktop Intelligence SDK.
This chapter discusses the following topics:
User interface classes
Adding a command bar
Adding controls to a command bar
Creating forms
User interface classesSome programs require input from a user or require the user to initiate aprocess. With the Desktop Intelligence SDK, you can include a user-interaction element to add-ins and macros. Using the Desktop IntelligenceSDK, you can also access elements of the Desktop Intelligence user interfaceand extend the interface to accommodate the requirements of your program.
Each Desktop Intelligence Application object includes a collection calledCmdBars. The CmdBars collection is the access point for all menus, toolbars, and pop-ups in the Desktop Intelligence interface. Using this collection,you can integrate the user interface elements of your add-ins and macroswith the Desktop Intelligence interface, so that they appear as part of thenormal interface. Using this part of the object model you can:
access the properties of the existing Desktop Intelligence interface
specify the menus Desktop Intelligence must display
create user-initiated add-ins and macros
add buttons to existing tool bars
create your own tool bars and pop-up menus
50 Desktop Intelligence Developer Guide
Customizing the user interface5 User interface classes
-
Command Bars
A command bar can be a tool bar, a menu bar, or a pop-up menu. Forinformation about adding tool bars and pop-up menus to the DesktopIntelligence user interface, see Adding a command bar on page 53.
Command bars include controls that can be either a pop-up menus or buttons.
Controls
Following are the types of controls: pop-up menus and buttons. Pop-upmenus present the list of buttons that can be used to perform actions, asshown following figure:
Desktop Intelligence Developer Guide 51
5Customizing the user interfaceUser interface classes
-
The CmdBarControls collection
The CmdBarControls collection contains all the controls for a command bar.
CmdBarControl is a generic class that represents a control.
CmdBarButton and CmdBarPopup are special cases of CmdBarControl.Both support properties and methods of CmdBarControl.
The items in the CmdBarControls collection are of the type CmdBarControl.However, if you know what type of control you are accessing, you can usethe specialized properties and methods. Normally, you need to use thiscollection for nesting controls.
Nested controls
Pop-up controls can contain other controls, as shown in the following figure:
52 Desktop Intelligence Developer Guide
Customizing the user interface5 User interface classes
-
When pop-up controls contain other controls, they act as command bars.The pop-up controls have their own collection of controls that you can accessby using CmdBarPopup.Controls.
Adding a command barYou can add tool bars and pop-up menus to the Desktop Intelligence userinterface. For information on adding controls to the existing command bars,see Adding controls to a command bar on page 54.
Desktop Intelligence Developer Guide 53
5Customizing the user interfaceAdding a command bar
-
To add a command bar to the collection of command bars:
Call CmdBars.Add
To add a tool bar, set the type to a position, for example, boBarTop.
To add a pop-up menu, set the type to boBarPopup.
Example: Adding a tool barSub AddCommandBar()Dim toolbar As CmdBarSet toolbar = Application.CmdBars.Add'add command bar("Analysis Utilities", boBarFloating)
'make the tool bar visibletoolbar.Visible = True'turn it ontoolbar.Enabled = True...'delete it when finishedtoolbar.DeleteEnd Sub
After you have added a command bar, you must add controls that enableusers to access the functions you provide. For more information about addingcontrols, see Adding controls to a command bar on page 54.
Displaying pop-up menus
After you have defined the controls for a pop-up menu, useCmdBar.ShowPopup to display the pop-up menu, as follows:
popup.ShowPopup
Adding controls to a command barIn general, you can add any control to any of the command bars in theCmdBars collection. However, you cannot add pop-up controls to tool bars.
Use CmdBarControls.Add to add controls to a command bar. For informationabout command bars, see Command Bars on page 51.
54 Desktop Intelligence Developer Guide
Customizing the user interface5 Adding controls to a command bar
-
Example: Adding an extra item to the Desktop Intelligence Tools menuSub AddTool()Dim menuCmdPop As CmdBarControlDim toolCmdBut As CmdBarControlSet menuCmdPop = Application.CmdBars(2).Controls(6)Set toolCmdBut = menuCmdPop.Controls.Add(boControlButton)toolCmdBut.Caption = "New Tool"toolCmdBut.OnAction = "Extras.rea!ToolModule.NewToolRoutine"
toolCmdBut.DescriptionText = "Useful reporting tool"...toolCmdBut.DeleteEnd Sub
Adding faces to buttons: the Clipboard object
A face is the image that appears on the button. Faces are also called icons.Without a face, a button appears blank and is indistinguishable from thesurface of its command bar (and similarly, without any buttons, a commandbar appears as a thin line).
To add a face to a button, create the button and use the Clipboard object tohold the file containing the face. The Clipboard object enables you to accessthe system clipboard, which can contain one image and one block of text.Once the face is in the clipboard, you can add (paste) it to the button.
To add the face to the clipboard, use the standard VBA function LoadPicture(),which returns an object of the type StdPicture. For more information aboutadding faces to buttons, see the Visual Basic documentation.
Adding a face to a button
To add a face to a button, complete the following steps:
1. Clear the clipboard.
The clipboard is shared by other applications. Therefore, it is a goodprogramming practice to ensure that the clipboard is empty before andafter you use it.
2. Place the image on the clipboard.3. Paste the image on the face of the button.
Desktop Intelligence Developer Guide 55
5Customizing the user interfaceAdding controls to a command bar
-
4. Clear the clipboard.
The following code fragment illustrates this procedure:
Example: Adding a face to a buttonDim ToolBut As CmdBarControl 'the buttonDim Bitmap As New StdPicture 'the bitmap for thebutton
Bitmap = LoadPicture("c:\Temp\images\Tool.bmp", , , Default)
'put the bitmap in the clipboardApplication.Clipboard.Clear 'clean up the clipboardfirstApplication.Clipboard.SetData Bitmap, 2 '2means it's a bitmapToolBut.PasteFace 'paste the bitmap onto the buttonApplication.Clipboard.Clear 'clean up for otherapplications
Set Bitmap = Nothing 'free the space
Useful tips for adding buttons
Buttons attached to pop-up command bars do not need faces. DesktopIntelligence uses the caption instead. However, you can add faces tothese buttons that appear in the menus. For example, in the DesktopIntelligence Tools menu, the Visual Basic icon appears next to the VisualBasic Editor item in the Macros submenu.
For best results, ensure that the faces have the following specifications:16x16 pixels or 32x32 pixels.
Adding actions to buttons
Adding an action to a button means instructing Desktop Intelligence as towhat needs to be done when a user selects the button. You can add anaction only to the controls of type boControlButton. In programming terms,an action is a VBA subroutine.
To add a functionality to a button, use CmdBarControl.OnAction.
56 Desktop Intelligence Developer Guide
Customizing the user interface5 Adding controls to a command bar
-
Example: Adding functionality to a buttonDim MultiPasteBut As CommandBarControl...MultiPasteBut.OnAction = "MPaste.rea!MPasteModule.DisplayMPaste"...Sub DisplayMPaste()...End Sub
Creating your own formsA form is a base to which you attach user interface controls, for example,list boxes, labels, radio buttons, and command buttons.
You can use VBA to create your own forms. Visual Basic includes a rich setof programming tools for creating forms visually and defining the behaviorof the form and its controls by using eventsfor example, double-click,pressing a key, and moving the mouse.
Creating a form
To create a form, complete the following steps:
1. Create a form module in a Visual Basic project.2. Add controls to the form.3. Implement the event procedures for the control.
Desktop Intelligence Developer Guide 57
5Customizing the user interfaceCreating your own forms
-
Example: Implementing a form event
58 Desktop Intelligence Developer Guide
Customizing the user interface5 Creating your own forms
-
Data providers
6
-
This chapter discusses the concepts associated with creating data providersby using the Desktop Intelligence SDK. It discusses the different types ofdata providers and describes how to access these sources of data.
This chapter discusses the following topics:
Working with existing data providers
Creating a query technique data provider
Working with existing data providersIn Desktop Intelligence, the term "data provider" refers to the source of datathat end users make use of to create reports. You can access the dataproviders for a document by using the DataProviders collection.
Only data providers that are created from universes have a Queries object.For more information about the Queries class, see Query technique onpage 62.
Some of the properties of the DataProvider class relate directly to theinformation available from the Definitions tab of the "Data Manager" dialogbox. For example, by using the object model, you can read the state of theEditable and Refreshable check boxes.
60 Desktop Intelligence Developer Guide
Data providers6 Working with existing data providers
-
The columns in the Results tab of the "Data Manager" dialog box are thesame columns that you can access by using the Columns class.
Example: Accessing properties of a data provider
Sub Show_DP_Names()Dim I As
IntegerDim message AsStringFor I = 1 To Application.ActiveDocument.Dat
aProviders.Countmessage = message & Chr(10) &Application.ActiveDocument.DataProviders.Item(I).Name
NextMsgBox message 'display the names
End Sub
Desktop Intelligence Developer Guide 61
6Data providersWorking with existing data providers
-
Data provider types
Data providers are categorized into four main types:
query technique
freehand SQL
personal text file
stored procedure
You can access the data provider types by using DataProvider.GetType.
You can select and configure the data provider by using the New Data wizardor the New Report wizard. If editing is enabled for the data provider, you canedit the data provider by using the Desktop Intelligence interface.
For information on creating data providers with the Desktop Intelligence SDK,see Creating a query technique on page 65.
Query technique
A query technique is a data provider that queries a universe. You can usethe Desktop Intelligence Query Panel to create a query technique dataprovider.
The query technique data provider consists of the following:
universe
query
The universe part defines where the information comes from. For example,the eFashion universe is stored in the General repository. This correspondsto choosing the universe in the New Report wizard.
The query part defines which parts of the universe you are interested in. Forexample, the Year object of the Time period class, and the Sales revenueobject of the Measures class, where Year is equal to 2000.
62 Desktop Intelligence Developer Guide
Data providers6 Working with existing data providers
-
Freehand SQL
A freehand SQL data provider is one in which the data is retrieved by usingan SQL statement and the database connection is defined by the end user.
You can retrieve the SQL statement by using DataProvider.SQL.
A freehand SQL file data provider has no Queries object.
Personal text file
A personal text file data provider retrieves data from plain text, MicrosoftExcel, and dBASE files. You can use the personal text file option to configurethe information in the file, such as what is a value, what is a column nameand so on.
A personal text file data provider has no Queries object.
Stored procedure
A stored procedure data provider is an SQL script that is saved and executedin a database.
A stored procedure data provider has no Queries object.
Desktop Intelligence Developer Guide 63
6Data providersWorking with existing data providers
-
Loading and unloading a data provider
You can load and unload a DataProvider object to and from memory asfollows: To load a DataProvider object into memory, use DataProvider.Load
To unload a DataProvider object from memory, use DataProvider.Unload
These methods are used to optimize "product-level" programs. You neednot use them for macros and "one-off" add-ins.
Error handling
If you do not unload a data provider from memory after using it, it will slowdown the system and the program may terminate unexpectedly.
Business Objects recommends that you include a call to DataProvider whenyou load or unload a data provider. Unload a data provider in anerror-handling mechanism. If an error occurs while the data provider is loadedto memory, then system errors can occur.
Example: Unloading a data provider in an error handler
The following code fragments show how to ensure that a data provider isremoved from memory if an error occurs after it is loaded:
Sub Modify_DataProvider()Dim boDP As DataProviderOn
ErrorGoto DPError 'if there's an error handle itSet boDP = Application.ActiveDocument.Dat
aProviders.Item(1)boDP.Load 'load the data provider into memory... 'do some processing with the data providerboDP.Unload 'unload the data provider from memory...Exit
SubDPError:
boDP.Unload 'make sure that the data provider is notin memory
64 Desktop Intelligence Developer Guide
Data providers6 Working with existing data providers
-
MsgBox "An error occurred..." 'display anerror message
EndSub
Creating a query techniqueTo create a query technique, complete the following steps:
1. Call DataProviders.AddQueryTechnique.2. Build the query.
Ensure that the query you built is runnable, that is, that the query followsthe rules for a valid query. For more information on rules for a valid query,seeDesktop Intelligence User's Guide: Accessing Data and Data Analysis.
3. Run or refresh the query (execute the SQL) by usingDataProvider.Refresh.
Example: Creating a query technique data providerDim QT As DataProviderSet QT = Application.ActiveDocument.DataProviders.AddQueryTechnique("eFashion", "")QT.Queries.Item(1).Results.Add "Time period", "Year"QT.Refresh
Building the query
DataProviders.AddQueryTechnique returns a DataProvider object that hasan empty query object. This is the programmatic equivalent of the QueryPanel stage in creating or editing a report.
From this point, just as in the user interface, you can choose objects for theresults and conditions, apply sorts, and run the query. The object modelincludes a number of classes for this, all of which can be accessed throughthe Queries object.
Desktop Intelligence Developer Guide 65
6Data providersCreating a query technique
-
Running and refreshing the query (filling themicrocube)
To run and refresh the query, use DataProvider.Refresh. This methodexecutes the SQL instruction you built with the Query, Conditions, and Resultsobjects, and populates a microcube with the results of the SQL statement.Desktop Intelligence then builds a report based on the microcube and anysort orders that you have specified.
66 Desktop Intelligence Developer Guide
Data providers6 Creating a query technique
-
Get More Help
A
-
Online documentation library
Business Objects offers a full documentation set covering all products andtheir deployment. The online documentation library has the most up-to-dateversion of the Business Objects product documentation. You can browsethe library contents, do full-text searches, read guides on line, and downloadPDF versions. The library is updated regularly with new content as it becomesavailable.
To access the online documentation library, visit http://help.sap.com/ andclick Business Objects at the top of the page.
Additional developer resources
https://boc.sdn.sap.com/developer/library/
Online customer support
The Business Objects Customer Support web site contains information aboutCustomer Support programs and services. It also has links to a wide rangeof technical information including knowledgebase articles, downloads, andsupport forums.
http://www.businessobjects.com/support/
Looking for the best deployment solution for your company?
Business Objects consultants can accompany you from the initial analysisstage to the delivery of your deployment project. Expertise is available inrelational and multidimensional databases, in connectivities, database designtools, customized embedding technology, and more.
For more information, contact your local sales office, or contact us at:
http://www.businessobjects.com/services/consulting/
Looking for training options?
From traditional classroom learning to targeted e-learning seminars, we canoffer a training package to suit your learning needs and preferred learningstyle. Find more information on the Business Objects Education web site:
http://www.businessobjects.com/services/training
68 Desktop Intelligence Developer Guide
Get More HelpA
-
Send us your feedback
Do you have a suggestion on how we can improve our documentation? Isthere something you particularly like or have found useful? Drop us a line,and we will do our best to ensure that your suggestion is included in the nextrelease of our documentation:
mailto:[email protected]
Note:If your issue concerns a Business Objects product and not the documentation,please contact our Customer Support experts. For information aboutCustomer Support visit: http://www.businessobjects.com/support/.
Business Objects product information
For information about the full range of Business Objects products, visit:http://www.businessobjects.com.
Desktop Intelligence Developer Guide 69
AGet More Help
-
70 Desktop Intelligence Developer Guide
Get More HelpA
-
Index.rea 41
A
accessingapplication events 46Desktop Intelligence user interface 50
actionsadding to buttons 56
add-ins 10creating 41distributing 42
addingactions to buttons 56buttons 54command bars 53controls 54macros 40
application events 44implementing 46
Application object 46, 50arrays
indexes 13VBA 13
B
bitmapsadding to buttons 55
buildingquery technique data provider 65
buttonsadding 54adding actions 56adding faces 55
buttons (continued)definition 51
C
Chr function 16classes
command bars 52queries 62, 65user interface 50
Clipboard objectpasting faces 55
collectionscommand bars 52
command bar controlsactions 56adding 54collection 52definition 51nested 52
command barsadding 53adding controls 54collection 52definition 51
controlssee command bar controls 51
creatingadd-ins 41macros 38query technique data provider 65
customizingDesktop Intelligence interface 50
Desktop Intelligence Developer Guide 71
-
Ddata providers 60freehand SQL 63handling errors 64loading and unloading 64optimizing 64personal text file 63query technique 62stored procedure 63types 62
dBASEquerying 63
declaringarrays in VBA 13variables in VBA 11
Desktop Intelligencecustomizing the interface 50
development environmentVBA 10, 15
disablingmacros 38
displaying pop-up menus 54distributing
add-ins 42document events 44, 45
E
errorsdata providers 64handling 64handling in VBA 14
eventsapplication 44document 44, 45form 57implementing 11, 45order 45triggers 45
Excelquerying 63
executing macros 40external object libraries 15
F
facesadding 55recommended size 56
filling a microcube 66flow control
in VBA 12forms
creating 57freehand SQL data provider
definition 63functions 11, 16
H
handlingerrors in VBA 14
I
implementingform events 57
implementing events 11, 45including
external object libraries in VBA 15indexing
arrays in VBA 13
L
loadingdata providers 64
M
macros 10adding 40
72 Desktop Intelligence Developer Guide
Index
-
macros (continued)creating 38running 40tool tips 40
memory managementdata providers 64
menu bardefinition 51
menusnesting 52
microcubefilling 66
N
nesting controls 52
O
Object Browser 10opening 15
object modelsuser interface 50
objectsbrowsing in VBA 15external 15
On Error statement 14optimizing
data providers 64
P
personal text file data providerdefinition 63
pop-up menusadding 53definition 51displaying 54nesting 52
procedures 11browsing in VBA 15
Q
Queries object 65Query Panel 65query technique data provider
creating 62, 65definition 62running and refreshing 66
R
referencingexternal object libraries in VBA 15
refreshingquery technique data provider 66
reports 66repository 62running
macros 40query technique data provider 66
S
showing pop-up menus 54SQL 66
data provider 63stored procedure data provider
definition 63sub-routines 11, 38
T
tool barsadding 53definition 51
tool tipsmacros 40
Desktop Intelligence Developer Guide 73
Index
-
Uuniversesquerying 62, 65
unloadingdata providers 64
user input 50user interface
customizing 50
V
VBA 10arrays 13creating forms 57data types 11events 11flow control 12
VBA (continued)functions 16implementing an event 45language summary 10On Error statement 14variables 11With statement 14writing macros 38
VBA procedure data providercreating 62
Visual Basiceditor 10, 40tool bar 40
W
With statement 14
74 Desktop Intelligence Developer Guide
Index