Desktop Intelligence Developer

Guide
BusinessObjects XI 3.1
2008 Business Objects, an SAP company. All rights reserved. Business Objects
owns 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 and
its logos, BusinessObjects, Business Objects Crystal Vision, Business Process
On Demand, BusinessQuery, Cartesis, Crystal Analysis, Crystal Applications,
Crystal Decisions, Crystal Enterprise, Crystal Insider, Crystal Reports, Crystal
Vision, Desktop Intelligence, Inxight and its logos , LinguistX, Star Tree, Table
Lens, ThingFinder, Timewall, Let There Be Light, Metify, NSite, Rapid Marts,
RapidMarts, the Spectrum Design, Web Intelligence, Workmail and Xcelsius are
trademarks or registered trademarks in the United States and/or other countries
of Business Objects and/or affiliated companies. SAP is the trademark or registered
trademark of SAP AG in Germany and in several other countries. All other names
mentioned herein may be trademarks of their respective owners.
Business Objects products in this release may contain redistributions of software
licensed from third-party contributors. Some of these individual components may
Third-party
Contributors
also be available under alternative licenses. A partial listing of third-party
contributors that have requested or permitted acknowledgments, as well as required
notices, can be found at: http://www.businessobjects.com/thirdparty
2008-09-11
Contents
Introduction 7 Chapter 1
About this guide...........................................................................................8
Who should use this guide ....................................................................8
Business Objects information resources................................................8
Getting started with VBA 9 Chapter 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 19 Chapter 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 37 Chapter 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 49 Chapter 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 59 Chapter 6
Working with existing data providers.........................................................60
Data provider types .............................................................................62
Loading and unloading a data provider................................................64
Get More Help 67 Appendix 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 guide
This guide describes how to develop applications by using the Desktop
Intelligence Software Development Kit (SDK).
Who should use this guide
This guide is intended for developers who want to use the Desktop
Intelligence SDK to develop applications.
Business Objects information resources
For more information and assistance, see Appendix A: Get More Help. This
appendix describes the Business Objects documentation, customer support,
training, and consulting services, with links to online resources.
8 Desktop Intelligence Developer Guide
Introduction
1
About this guide
Getting started with VBA
2
You can use Microsoft Visual Basic for Applications (VBA) to create custom
macros and add-ins in Desktop Intelligence.The VBA is used by Microsoft
Office products and several other Windows software products. Using VBA,
you can integrate and customize applications that are already available on
the system desktop. However, you may encounter some limitations while
using VBA on the Desktop Intelligence server. For more information, see
VBA macros: migration overview on page 19.
Comprehensive on-line help about the VBA development environment and
language is available from the VBA Help menu. You can also press F1 in
the VBA development environment to access VBA Help menu.
This chapter describes how VBA enables you to extend the capabilities of
Desktop Intelligence. This chapter also describes how to develop macros
and add-ins by using VBA, to control the Desktop Intelligence and Designer
environments, as well as performqueries and analysis on data in documents
through universes and data providers.
Accessing the development environment
Desktop Intelligence contains a Visual Basic editor, which you can use to
develop macros and add-ins. You can access the Visual Basic editor from
the Visual Basic tool bar. If the editor is not displayed, right-click the tool bar
or menu bar, and select Visual Basic. You can also access the Visual Basic
editor from the Macros submenu in the Tools menu.
The Visual Basic editor is the standard Microsoft VBA editor, which is included
in the Microsoft Office 2000 suite. Hence, you can use tools such as Object
Browser and Project Explorer. Online help for VBA is also available from the
Visual Basic editor.
Language summary
This section provides an overview of the VBA language. It also discusses
some 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 VBA
2
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 and
sub-routines. Functions can return values, whereas subroutines do not return
values.
Event implementation
The VBA is event-driven, that is, the code is executed when certain events
take place in the application. Examples of events include a user opening a
document and a user clicking a button. The execution of the code when an
event occurs is called event implementation.
The Universe Designer SDK does not have any events to implement. This
implies that you cannot write a code to respond to events in the Designer
Desktop Intelligence Developer Guide 11
2
Getting started with VBA
Language summary
application. However, you can use the Designer object model while
implementing events of other applications.
For more information on implementing events, see Desktop Intelligence
events on page 44 and Creating your own forms on page 57.
Flow control
The following table discusses the most commonly used VBA flow control
structures:
Description Control
Tests a condition, and based on the
result of the test, alters the execution
flow
If-Then-Else
Repeats an action the specified
number of times.
For-Next
Repeats an action while a condition
is true
While-Wend
Repeats an action either when a
condition is true, or until it becomes
true
Do-Loop
Branches to one of several possible
code segments, based on the value
of a variable or the outcome of a test.
Select-Case
Repeats an action on each object in
a collection or on each item in an ar-
ray
For-Each-Next
12 Desktop Intelligence Developer Guide
Getting started with VBA
2
Language summary
Arrays
An array is a variable that contains multiple values. Each value is indexed
and 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. In
VBA, 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 = 500
Dim 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. You
can 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 arrays
to either 1 or 0.
For example:
Option Base 1
Array(1) 'reference the first element
Desktop Intelligence Developer Guide 13
2
Getting started with VBA
Language summary
is the same as:
Option Base 0
Array(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, you
must 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 is
element 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 the
With statement:
With Application.ActiveDocument.DataProviders.Item(1).Queries
.DuplicateRows = TRUE
.DeleteTrailingBlanks = TRUE
.ScopeOfAnalysis = boThreeLevelsDown
End With
Error handling
You can use the On Error statement to handle errors generated during the
execution of a code.
If you don't use an On Error statement, any run-time error that occurs can
prove to be critical. That is, an error message is displayed and the execution
stops.
14 Desktop Intelligence Developer Guide
Getting started with VBA
2
Language summary
Example: Handling errors with the On Error statement
Sub Convert(...)
On Error Goto ErrorDisplay
... 'if an error occurs here go to ErrorDisplay
Exit Sub
ErrorDisplay: MsgBox Err.Number & "-" & Err.Description
Sub 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 enable
you to run, debug, and move the code around. One of the most useful tools
is the Object Browser.
The Object Browser displays all the programmable objects that are installed
and registered on the systemalong with their associated properties, methods,
and events. You can also use the Object Browser to browse the procedures
and 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 Microsoft
Outlook, fromthe VBA program, create a reference to the appropriate object
library. After creating the reference, you can use the classes, methods, and
properties 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
2
Getting started with VBA
Language summary
If the reference is successful, the name of the object library you referenced
appears 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 and
subroutines
The following table discusses some useful VBA functions and subroutines:
Description Name
Returns the absolute value of a
number
Abs
Returns the current MS-DOS path CurDir
Returns a character if its ASCII code
is given
Chr
Returns the current system date Date
Causes execution to break out of a
Do loop
Exit Do
Causes execution to break out of a
For loop
Exit For
Causes execution to break out of a
function
Exit Function
16 Desktop Intelligence Developer Guide
Getting started with VBA
2
Some useful VBA functions and subroutines
Description Name
Causes execution to break out of a
sub-routine
Exit Sub
Returns the integer portion of a
number, after rounding down positive
numbers and negative numbers
Fix
Returns the integer portion of a
number, after rounding down positive
numbers and negative numbers
Int
Returns TRUE if an expression is an
array
IsArray
Returns TRUE if an expression is a
date
IsDate
Returns TRUEif no value is assigned
to a variable
IsEmpty
Returns TRUE if an expression is an
error value
IsError
Returns TRUE if an expression eval-
uates to NULL
IsNull
Returns TRUE if an expression eval-
uates to a number
IsNumeric
Desktop Intelligence Developer Guide 17
2
Getting started with VBA
Some useful VBA functions and subroutines
Description Name
Returns TRUE if an expression rep-
resents an object
IsObject
Returns the lower bound of an array LBound
Returns the length of a string, or the
number of bytes required to store a
value
Len
Returns the current date and time Now
Runs an executable program Shell
Returns the square root of a number Sqr
Performs a string comparison StrComp
Returns the current system time Time
Returns the data type of a variable TypeName
Returns the upper bound of an array Ubound
18 Desktop Intelligence Developer Guide
Getting started with VBA
2
Some useful VBA functions and subroutines
VBA macros: migration
overview
3
BusinessObjects XI Release 2 (referred to as "XI R2") and BusinessObjects
XI 3.0 (referred to as "XI 3.0") are new versions of BusinessObjects XI. Both
XI R2 and XI 3.0 enable majority of classic BusinessObjects customers to
move to the XI platform. The migration protects customers' investment in the
BusinessObjects technology by delivering the following key features:
Note:
Unless specifically mentioned, XI R2 and XI 3.x are collectively referred to
as XI.
A direct migration path and a set of migration tools for customers who
have deployed BusinessObjects 5.1 (or Web Intelligence 2.7), 6.0, 6.1,
or 6.5.
Desktop Intelligence: The BusinessObjects full client (which is renamed
as Desktop Intelligence) is part of XI. It benefits from the enhancements
in the new platform, such as Unicode support, report instances, and
discussions.
Web Intelligence: XI provides a much-enhanced version of Web
Intelligence, which enables a large number of customers to move their
entire business intelligence (BI) solution to the web.
The XI provides a direct migration path from BusinessObjects 5.1/6.x. This
section provides information about the migration of VBA macros to XI.
Migration of VBA macros to XI
A number of BusinessObjects customers have developed VBA macros or
VBA add-ins for the BusinessObjects Desktop Intelligence product.
The VBA macros or add-ins developed for 5.1/6.x work with Desktop
Intelligence supported in XI. Most VBA macros developed for 5.1/6.x work
in XI. However, some macros are not supported on the server side.
Support depends on the nature of the code and the location of the code
execution. The following table discusses support for VBA macros in XI:
VBA add-ins VBA macros
Yes Yes Client side
No Yes with restrictions Server side
20 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
Migration of VBA macros to XI
VBA macros
The VBA macros are embedded in .rep documents. You can migrate .rep
documents to XI in one of the following ways:
Corporate documents (that is, .rep documents located in the source
repository) can be migrated to the XI repository by using the Import Wizard
tool.
Local documents (that is, .rep documents located on the desktop of the
systems) can be migrated to XI by opening and saving these documents
with Desktop Intelligence.
In both cases, after migration, VBA macros remain embedded in .rep
documents in XI.
VBA add-ins
Each VBA add-in is a separate file with a .rea (report add-in) extension. The
VBA add-ins do not run on the server side (that is, on the BusinessObjects
Enterprise server) in XI.
Updating platform-related calls
The macros that work at the document level (for example, macros that
execute queries, filter a report, or re-format a report) continue to work in XI.
However, platform-related macros must be updated to reflect the new
underlying BusinessObjects Enterprise SDK. Following are the key changes
in XI:
SDK name: In XI, the SDK is called the Desktop Intelligence SDK.
However, for compatibility with previous versions, ProgIDs and other
technical names used in the code remain unchanged.
Repository interaction: Login, document send/retrieve, and reference to
repository 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
3
VBA macros: migration overview
Migration 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 from
5.1/6.x to an XI repository. However, the Import Wizard does not check VBA
code contained in .rep documents and whether the VBA macros must be
updated or not. Hence, after migration, VBA macros must be checked and
validated manually.
Some customers store VBA add-ins in the 5.1/6.x repository. Like agnostic
documents, the VBA add-ins (.rea files) are migrated by using the Import
Wizard. 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-side
execution:
Architecture - On the XI platform, the V5/V6 BOManager component is
replaced by the RAS21 component. While BOManager was a
multi-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 VBA
macros. For more information, see BCA custom macro migration on
page 29.
VBA add-ins - The VBA add-ins cannot be executed on the server. For
example, a document that includes a Web Connect data provider cannot
be refreshed (DPVBAInterface code must be in the document itself to be
executed).
CreateObject ("BusinessObjects.Application") - CreateObject will fail using
Desktop 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 on
the server and move the code to a VB program.
22 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
Migration of VBA macros to XI
Replace ActiveDocument with ThisDocument - While ActiveDocument
and ActiveReport still work on the client side, they no longer work on the
server side. Hence, they must be replaced.
API changes
Some APIs have been removed while others have been updated (with a new
operability 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 that
are introduced as replacements:
Login
Replacement in XI 6.x API- Removed
Function
Application. Logon (User As String,
Password As String, CMS As String,
Mode As String, ThreeTier As
Boolean, Offline As Boolean) As
Boolean
Function
Application.LogonWithToken (token
As String) As Boolean
Function
Application.LogonDialog ()As
Boolean
Function
Application.LoginAs ([User As String],
[Pass As String], [Offline As
Boolean], [RepositoryName As
String]) As Boolean
CMS name supersedes repository
name (.key file)
Desktop Intelligence Developer Guide 23
3
VBA macros: migration overview
API changes
Document exchange
Replacement in XI 6.x API- Removed
Sub Document.SaveToEnter-
prise(Folder As string, CategoryList
As String, Overwrite As Boolean)
Sub Document.SaveToEnterpriseDi-
alog()
Note:
Send to inbox and scheduling are not
available in Destkop Intelligence SDK.
You must use the BOESDK destination
plug-in.
Sub Document.Send([User As
String], [StoreGeneratedHTML As
Boolean], [HtmlLayout As BoHTML-
Layout], [CategoryList As String],
[ExchangeMode As BoExchange-
Mode], [ExchangeDomain As String])
HtmlLayout obsolete with dhtml
viewer
Application.BoExchangeMode
Function
Documents.OpenFromEnter-
pris(Name As String, Folder, As
String) As Document
Function
Documents.OpenFromEnterpriseDia-
log() As Document
Retrieve from inbox and from sc are
not available in Destkop Intelligence
SDK. You must use the BOESDK
destination plug-in.
Sub Documents.Receive([Name As
String], [DestDir As String])
EnumBODocumentLocation =boEnter-
priseFolder
Application.BoExchangeMode
24 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
API changes
Replacement in XI 6.x API- Removed
Function
Documents.OpenFromEnterpriseDia-
log(DocumentOrigin As BODocumen-
tOrigin) As Document
Sub Documents.Receive([Name As
String], [DestDir As String])
No replacement in XI
Application.BoExchangeModeDistinct
method replace echange mode Appli-
cation.ExchangeDomain Folders su-
persede domains
Scheduling
Replacement in XI 6.x API - Removed
You must use the BI PLATFORM
SDK while migrating
Class DocAgentOption
Domains replaced by enterprise folders
Replacement in XI 6.x API - Removed
Function AddQueryTechnique(Uni-
verseName As String, EnterpriseFold-
erName As String)
Function DataProviders.AddQuery
Technique(UniverseName As String,
[UniverseDomainName]) As DataPro-
vide
Desktop Intelligence Developer Guide 25
3
VBA macros: migration overview
API changes
Replacement in XI 6.x API - Removed
No replacement in XI
Property Universes.Item(Index As
Variant, [RepositoryName As String])
As Universe )
No replacement in XI Universe.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, and
SAP BW cubes. Hence, the OLAP data provider is removed from Desktop
Intelligence and the SecurityPrompts class is obsolete.
Note:
Desktop Intelligence documents support only SAP BW universes.
New interoperability API in XI 6.x API
No replacement in XI Class SecurtyPrompts
26 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
API changes
New interoperability API in XI 6.x API
No replacement in XI
Sub Application.SetSecuri
tyPrompt(sUserName As String,
sUserPasswordVarName As String,
sUserPassword As String, sDBName
As String, sDBPasswordVarName
As String, sDBPassword As String)
No replacement in XI
Function Document.GetSecuri
tyPrompts() As Security Prompts
Application-level variables
The variables available through collection Application.Variables have
changed. The following table summarizes the changes:
Variable name Availability of variables
BOLANGUAGE
BOSECURITYDOMAIN
BOUSER
BUSER_UPPER
6.5 variables available in XI
Desktop Intelligence Developer Guide 27
3
VBA macros: migration overview
API changes
Variable name Availability of variables
COMPUTERNAME
CommonProgramFiles
HOMEDRIVE
HOMEPATH
ProgramFiles
SystemDrive
SystemRoot
USERDNSDOMAIN
USERDOMAIN
USERNAME
USERPROFILE
6.5 variables not available in XI
DOCNAME New variable in XI
Windows system variables such as TEMP and
PROCESSOR_ARCHITECTURE are available in both XI and 6.5.
Use cases
This section briefly describes the use cases of Desktop Intelligence SDK.
Scheduling by using DocAgentOption class
The DocAgentOption calls must be replaced by Enterprise SDK scheduling
API, because scheduling is no longer supported in Desktop Intelligence SDK.
28 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
Use cases
In the following use case for Application.LogonWithToken and
Document.CUID, Desktop Intelligence SDKand Enterprise SDKinteroperate.
Login BusinessObjects Full Client
Application.LogonWithToken(EntSession.LogonTokenMgr.CreateLo
gonEx) Dim strCUID As String
Call to BusinessObjects FC SDK to get document's CUID
strCUID = Application.Documents( " DocumentToScedule " ).CUID
Retrieve the InfoStore object
Dim IStore As InfoStore
Set IStore = EntSession("IStore")
Retrieve the BI PLATFORMSDKInfoObject that corresponds to the document
to be scheduled
Set Result=IStore.Query("SELECT SCHEDULEINFO FROM CI_INFOOBJECTS
_ WHERE SI_CUID = ' "+strCUID + "'""")
Dim FCDocumentObject As InfoObject
Retrieve the first document
Set FCDocumentObject =Result.Item(1)
Dim FCScheduleInfo As SchedulingInfo
Use the scheduling object to set the scheduling options
Set FCScheduleInfo = FCDocumentObject.SchedulingInfo
FCScheduleInfo.Type=4 (Schedule is monthly.)
FCScheduleInfo.IntervalMonths = 2
FCScheduleInfo.RightNow = 1
Schedule the document
IStore.Schedule Result
BCA custom macro migration
A use case for BCA Custom Macro is the Automatic distribution through
email of BusinessObjects documents in PDF format.
How it was done in 6.5:
Desktop Intelligence Developer Guide 29
3
VBA macros: migration overview
Use cases
A publisher.rep document contained the Sub ENotify() VBA macro to open
documents, save them in PDFformat, and send notification emails.
The publisher.rep document was scheduled through BCA; action specified
the 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 using
DocAgentOption 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 using
DocAgentOption class on page 28.
Document events, properties, and
methods
The following tables discuss the document events, properties, and methods
used in Desktop Intelligence client and their support on server side:
Desktop Intelligence InfoView Doc Event
OK OK Open
OK OK BeforeRefresh
OK OK AfterRefresh
OK Doesn't work BeforeClose
30 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
Document events, properties, and methods
Desktop Intelligence InfoView Doc Event
OK Not supported by procFC Activate
OK Not supported by procFC DeActivate
OK Doesn't work (Bug) Beforesave
Desktop Intelligence InfoView Property
OK OK ThisDocument
OK
Doesn't work (normal be-
cause there is no Activate
in ProcFC)
ActiveDocument
OK
Doesn't work (there is no
Activate in procFC)
ActiveReport
Desktop Intelligence InfoView Method
OK Doesn't work ThisDocument.Save
OK Doesn't work ThisDocument.SaveAs
OK Doesn't work
ThisDocument.SaveToEn
terprise
OK OK
ThisDocument.Expor
tAsPDF
OK OK
ThisDocument.Expor
tAsXML
Desktop Intelligence Developer Guide 31
3
VBA macros: migration overview
Document 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:
Description Event
In Report Server, this event is gener-
ated when the document is opened
for the first time (from the browser).
Report Server spawns a new child
process to handle the document.
Based on user rights and other secu-
rity information, this child process is
shared among the different user
sessions. Hence, next time the same
document is opened by the same
user or a different user with similar
rights, this event is not generated.
Note:
If the document goes to Cache, this
event is not generated.
OpenEvent
These events are generated all the
time in Report Server and Job Serv-
er. However, their functionality is
limited.
BeforeRefresh
AfterRefresh
32 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
Document events, properties, and methods
Description Event
This event is generated inconsistently
in the Report Server. The document
closes when the child process ex-
pires, because the child processes
are shared. Hence, this event is
generated when the document closes
(in the child process and not in the
viewer).
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 document
is being opened or closed.
The AfterRefresh event has the following limitation: Changes made by
the user (on the document) may not work all the time, because of the RE
SDK protocols. For example, if you set a prompt in the background, it
may not be set to the value.
The Desktop Intelligence server plug-in is mono-document; that is, it is
designed to handle a single document at a time. Hence, some of the APIs
related 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 the
document it is handling).
The Desktop Intelligence Server is more suitable for a single document
rather than multiple documents.
Testing limitations
This section describes how to test the limitations of Desktop Intelligence.
Desktop Intelligence Developer Guide 33
3
VBA macros: migration overview
Document 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 on
BeforeRefresh.
For example, pass the value through SDK on both BeforeRefresh and
AfterRefresh 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() instead
of Document.Variable(). It is added to the list of Application variables.
Regression Risk: If another document with the same prompt name is
refreshed in the same process, it uses the previously set value and
the prompt does not appear.
Refresh Data Provider - Fails on both BeforeRefresh and AfterRefresh
events.
Change Universe of a Data Provider - Fails on both BeforeRefresh and
AfterRefresh events.
Close Document - Fails on both BeforeRefresh and AfterRefresh events.
RE SDK protocol
When you performany of the operations discussed in this section, the report
in 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 AfterRefresh
and partially passes on BeforeRefresh.
For example, pass the value through SDK on BeforeRefresh event for
the prompt. Consider, Country = US.
34 Desktop Intelligence Developer Guide
VBA macros: migration overview
3
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 that
does not exist, give inconsistent results, or may fail.
Note:
The following functions may not work on both BeforeRefresh and AfterRefresh
events:
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 documents
in a process. Hence, these operations are not implemented.
Desktop Intelligence Developer Guide 35
3
VBA macros: migration overview
Document events, properties, and methods
36 Desktop Intelligence Developer Guide
VBA macros: migration overview
3 Document events, properties, and methods
Programming with Desktop
Intelligence
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 subroutines
A macro is a series of commands and functions that automate tasks you
need to performregularly. A macro is saved within a document and is enabled
each time you open the document. You can send a document containing a
macro to other users, just as you can send a regular Desktop Intelligence
document.
You can create macros in Desktop Intelligence by using the integrated VBA
environment.
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 Intelligence
4
Macros and subroutines
In the "Macros" dialog box, the names of add-ins, the macros contained
in the open document, or a combination of both is displayed.
3. Enter a name for the macro, and click Create. The VBA environment is
opened, and a module containing a skeleton sub-routine for the macro
is created, as shown in the following figure:
4. Begin writing the macro.
When you finish writing and compiling the macro successfully, select Close
and Return to Desktop Intelligence from the File menu. You can now run
Desktop Intelligence Developer Guide 39
4
Programming with Desktop Intelligence
Macros and subroutines
the macro from the "Macros" dialog box. If you want, you can also associate
the macro with a button on the tool bar. For more information, see
Customizing the user interface on page 49.
The Visual Basic tool bar
You can hide or show the Visual Basic tool bar in Desktop Intelligence by
right-clicking another tool bar or the menu bar, and selecting Visual Basic.
You can also select Toolbars fromthe Viewmenu, as shown in the following
figure:
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 VBA
environment for editing a procedure or a macro.
Run Associated Macro - Click Run Associated Macro to run a macro
associated 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 a
macro.
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 Intelligence
4
Macros and subroutines
3. Click the check box besides the number of the button with which you want
to associate the macro.
4. Type the name of the macro in the text box to the right. Alternatively, you
can click Browse besides the text box to select a macro. When a macro
is selected, the edit box displays AddIn.rea!module.macro or
Document.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 tool
bar. The macro details are now hidden. You can run the macro by clicking
the respective button on the Visual Basic tool bar.
Add-ins
Add-ins are programs that provide optional commands and features to
Desktop Intelligence. Each add-in is saved with a .rea extension.
Desktop Intelligence Developer Guide 41
4
Programming with Desktop Intelligence
Add-ins
Before you can use an add-in, you must load it on your computer and then
install it in Desktop Intelligence. Once you install an add-in, it becomes
available each time you launch Desktop Intelligence.
To conserve memory, uninstall add-ins you do not use often. Uninstalling an
add-in removes its features and commands from Desktop Intelligence.
However, the add-in programremains on the computer so that you can easily
install it again.
Unlike macros, add-ins are not associated with a single documentonce
installed, an add-in functions just like any other feature of the Desktop
Intelligence application.
You can distribute add-ins you have created to other users, and retrieve and
use add-ins that others have created.
Note:
Starting with XI, the add-ins are not supported when a Desktop Intelligence
document 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 among
other 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 Intelligence
4
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 to
update the saved add-in.
Tip:
To optimize the performance of the system, use one large .rea file containing
many 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 in
Desktop 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 displayed
in 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 can
associate 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
4
Programming with Desktop Intelligence
Add-ins
Desktop Intelligence events
An event is a change in the state of Desktop Intelligence, for which you can
program a response. For example, you can program Desktop Intelligence
to display a dialog box whenever a user opens a document. Programming
a response to an event is called implementing the event.
In Desktop Intelligence, you can implement events concerning Desktop
Intelligence documents (*.rep and *.rea). These events are made available
in general and specific senses. That is, you can implement an event for any
document, or only when it happens to a particular document.
General document events, those that apply to any document, belong to the
Application class and are called application events.
Specific document events, those that apply to specific documents, belong
to the Document class and are called document events.
The following table lists the application events and document events that
you can implement in Desktop Intelligence:
Document events Application events
Activate DocumentActivate
AfterRefresh DocumentAfterRefresh
BeforeClose DocumentBeforeClose
BeforeRefresh DocumentBeforeRefresh
BeforeSave DocumentBeforeSave
Deactivate DocumentDeactivate
44 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence
4
Desktop Intelligence events
Document events Application events
Open DocumentOpen
NewDocument
Event triggers
Events can be triggered by user actions or by use of methods in the Desktop
Intelligence SDK. For example, a BeforeRefresh event (application and
document) is triggered when the user clicks the Refresh button in the Desktop
Intelligence user interface, or when the user calls the Document.Refresh
method.
Triggering the events on the server side by using Desktop Intelligence
document 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 is
Doc1_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 its
corresponding object.
Desktop Intelligence Developer Guide 45
4
Programming with Desktop Intelligence
Desktop Intelligence events
To implement an event, insert the code that you want to execute in the
procedure 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 to
refresh:
Private Sub Document_BeforeRefresh(Cancel As Boolean)
'user's response to the message
Dim Response As Variant
Response = MsgBox("Are you sure you want to refresh?", vbOK
Cancel)
If Response = vbCancel Then
'user chose cancel, so cancel the refresh
Cancel = True
Else
'user didn't cancel, so continue with refresh
Cancel = False
End If
End Sub
Implementing application events
You cannot implement application events directly. To access the events of
the Application object, you need to create a reference to the object and
implement the events of the reference.
46 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence
4
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-down
list 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 Application
object.
The subroutine must execute before the implementation of the application
events is triggered.
5. Implement the events of the reference to the Application object.
The events for the application reference property appear in the procedure
drop-down list in the code window of the class module you created in
step 1.
The following diagramatic representation illustrates this sequence:
The events for the application reference property (boapp) appear in the
procedure list of the application reference class (AppRefClass).
Desktop Intelligence Developer Guide 47
4
Programming with Desktop Intelligence
Implementing application events
Example: Accessing events of the Application object
The following code fragments show the VBA statements you need to
establish a reference to the Application object. Once you have established
this reference, you can implement application events.
In a VBA class module called AppRefClass, for example, declare an
Application property called, for example, boapp, as follows:
Public
WithEvents 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 events
defined for the Application class. For more information on the Public and
WithEvents keywords, see the Visual Basic documentation.
In another module, create an instance of AppRefClass called, for example,
AppRef, as follows:
Dim AppRef As
New 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 using
AppRef.boapp.
48 Desktop Intelligence Developer Guide
Programming with Desktop Intelligence
4
Implementing application events
Customizing the user
interface
5
This chapter describes how to customize the user interface by using the
Desktop 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 classes
Some programs require input from a user or require the user to initiate a
process. With the Desktop Intelligence SDK, you can include a user-
interaction element to add-ins and macros. Using the Desktop Intelligence
SDK, you can also access elements of the Desktop Intelligence user interface
and extend the interface to accommodate the requirements of your program.
Each Desktop Intelligence Application object includes a collection called
CmdBars. The CmdBars collection is the access point for all menus, tool
bars, and pop-ups in the Desktop Intelligence interface. Using this collection,
you can integrate the user interface elements of your add-ins and macros
with the Desktop Intelligence interface, so that they appear as part of the
normal 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 interface
5
User interface classes
Command Bars
A command bar can be a tool bar, a menu bar, or a pop-up menu. For
information about adding tool bars and pop-up menus to the Desktop
Intelligence 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-up
menus present the list of buttons that can be used to perform actions, as
shown following figure:
Desktop Intelligence Developer Guide 51
5
Customizing the user interface
User 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 use
the specialized properties and methods. Normally, you need to use this
collection 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 interface
5
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 access
by using CmdBarPopup.Controls.
Adding a command bar
You can add tool bars and pop-up menus to the Desktop Intelligence user
interface. 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
5
Customizing the user interface
Adding 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 bar
Sub AddCommandBar()
Dim toolbar As CmdBar
Set toolbar = Application.CmdBars.Add
'add command bar
("Analysis Utilities", boBarFloating)
'make the tool bar visible
toolbar.Visible = True
'turn it on
toolbar.Enabled = True
...
'delete it when finished
toolbar.Delete
End Sub
After you have added a command bar, you must add controls that enable
users to access the functions you provide. For more information about adding
controls, 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, use
CmdBar.ShowPopup to display the pop-up menu, as follows:
popup.ShowPopup
Adding controls to a command bar
In general, you can add any control to any of the command bars in the
CmdBars collection. However, you cannot add pop-up controls to tool bars.
Use CmdBarControls.Add to add controls to a command bar. For information
about command bars, see Command Bars on page 51.
54 Desktop Intelligence Developer Guide
Customizing the user interface
5
Adding controls to a command bar
Example: Adding an extra item to the Desktop Intelligence Tools menu
Sub AddTool()
Dim menuCmdPop As CmdBarControl
Dim toolCmdBut As CmdBarControl
Set 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.Delete
End 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 the
surface of its command bar (and similarly, without any buttons, a command
bar appears as a thin line).
To add a face to a button, create the button and use the Clipboard object to
hold the file containing the face. The Clipboard object enables you to access
the 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 VBAfunction LoadPicture(),
which returns an object of the type StdPicture. For more information about
adding 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 good
programming practice to ensure that the clipboard is empty before and
after 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
5
Customizing the user interface
Adding controls to a command bar
4. Clear the clipboard.
The following code fragment illustrates this procedure:
Example: Adding a face to a button
Dim ToolBut As CmdBarControl 'the button
Dim Bitmap As New StdPicture 'the bitmap for the
button
Bitmap = LoadPicture("c:\Temp\images\Tool.bmp", , , Default)
'put the bitmap in the clipboard
Application.Clipboard.Clear 'clean up the clipboard
first
Application.Clipboard.SetData Bitmap, 2 '2
means it's a bitmap
ToolBut.PasteFace 'paste the bitmap onto the button
Application.Clipboard.Clear 'clean up for other
applications
Set Bitmap = Nothing 'free the space
Useful tips for adding buttons
Buttons attached to pop-up command bars do not need faces. Desktop
Intelligence uses the caption instead. However, you can add faces to
these buttons that appear in the menus. For example, in the Desktop
Intelligence Tools menu, the Visual Basic icon appears next to the Visual
Basic 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 to
what needs to be done when a user selects the button. You can add an
action 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 interface
5
Adding controls to a command bar
Example: Adding functionality to a button
Dim MultiPasteBut As CommandBarControl
...
MultiPasteBut.OnAction = "MPaste.rea!MPasteModule.DisplayMPa
ste"
...
Sub DisplayMPaste()
...
End Sub
Creating your own forms
A 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 set
of programming tools for creating forms visually and defining the behavior
of 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
5
Customizing the user interface
Creating your own forms
Example: Implementing a form event
58 Desktop Intelligence Developer Guide
Customizing the user interface
5
Creating your own forms
Data providers
6
This chapter discusses the concepts associated with creating data providers
by using the Desktop Intelligence SDK. It discusses the different types of
data 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 providers
In Desktop Intelligence, the term "data provider" refers to the source of data
that end users make use of to create reports. You can access the data
providers 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 on
page 62.
Some of the properties of the DataProvider class relate directly to the
information available from the Definitions tab of the "Data Manager" dialog
box. For example, by using the object model, you can read the state of the
Editable and Refreshable check boxes.
60 Desktop Intelligence Developer Guide
Data providers
6
Working with existing data providers
The columns in the Results tab of the "Data Manager" dialog box are the
same columns that you can access by using the Columns class.
Example: Accessing properties of a data provider
Sub Show_DP_Names()
Dim I As
Integer
Dim message As
String
For I = 1 To Application.ActiveDocument.Dat
aProviders.Count
message = message & Chr(10) &
Application.ActiveDocument.DataProviders.Item(I).Name
Next
MsgBox message 'display the names
End Sub
Desktop Intelligence Developer Guide 61
6
Data providers
Working 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 NewData wizard
or the New Report wizard. If editing is enabled for the data provider, you can
edit 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 use
the Desktop Intelligence Query Panel to create a query technique data
provider.
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 corresponds
to choosing the universe in the New Report wizard.
The query part defines which parts of the universe you are interested in. For
example, the Year object of the Time period class, and the Sales revenue
object of the Measures class, where Year is equal to 2000.
62 Desktop Intelligence Developer Guide
Data providers
6
Working with existing data providers
Freehand SQL
A freehand SQL data provider is one in which the data is retrieved by using
an 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, Microsoft
Excel, and dBASEfiles. You can use the personal text file option to configure
the information in the file, such as what is a value, what is a column name
and 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 executed
in a database.
A stored procedure data provider has no Queries object.
Desktop Intelligence Developer Guide 63
6
Data providers
Working with existing data providers
Loading and unloading a data provider
You can load and unload a DataProvider object to and from memory as
follows:
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 need
not 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 slow
down the system and the program may terminate unexpectedly.
Business Objects recommends that you include a call to DataProvider when
you load or unload a data provider. Unload a data provider in an
error-handling mechanism. If an error occurs while the data provider is loaded
to 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 is
removed from memory if an error occurs after it is loaded:
Sub Modify_DataProvider()
Dim boDP As DataProvider
On
Error
Goto DPError 'if there's an error handle it
Set boDP = Application.ActiveDocument.Dat
aProviders.Item(1)
boDP.Load 'load the data provider into memory
... 'do some processing with the data provider
boDP.Unload 'unload the data provider from memory
...
Exit
Sub
DPError:
boDP.Unload 'make sure that the data provider is not
in memory
64 Desktop Intelligence Developer Guide
Data providers
6
Working with existing data providers
MsgBox "An error occurred..." 'display an
error message
End
Sub
Creating a query technique
To 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 follows
the rules for a valid query. For more information on rules for a valid query,
see Desktop Intelligence User's Guide: Accessing Data and Data Analysis.
3. Run or refresh the query (execute the SQL) by using
DataProvider.Refresh.
Example: Creating a query technique data provider
Dim QT As DataProvider
Set 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 has
an empty query object. This is the programmatic equivalent of the Query
Panel stage in creating or editing a report.
From this point, just as in the user interface, you can choose objects for the
results and conditions, apply sorts, and run the query. The object model
includes a number of classes for this, all of which can be accessed through
the Queries object.
Desktop Intelligence Developer Guide 65
6
Data providers
Creating a query technique
Running and refreshing the query (filling the
microcube)
To run and refresh the query, use DataProvider.Refresh. This method
executes the SQL instruction you built with the Query, Conditions, and Results
objects, and populates a microcube with the results of the SQL statement.
Desktop Intelligence then builds a report based on the microcube and any
sort orders that you have specified.
66 Desktop Intelligence Developer Guide
Data providers
6
Creating a query technique
Get More Help
A
Online documentation library
Business Objects offers a full documentation set covering all products and
their deployment. The online documentation library has the most up-to-date
version of the Business Objects product documentation. You can browse
the library contents, do full-text searches, read guides on line, and download
PDF versions. The library is updated regularly with newcontent as it becomes
available.
To access the online documentation library, visit http://help.sap.com/ and
click 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 about
Customer Support programs and services. It also has links to a wide range
of technical information including knowledgebase articles, downloads, and
support forums.
http://www.businessobjects.com/support/
Looking for the best deployment solution for your company?
Business Objects consultants can accompany you from the initial analysis
stage to the delivery of your deployment project. Expertise is available in
relational and multidimensional databases, in connectivities, database design
tools, 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 can
offer a training package to suit your learning needs and preferred learning
style. Find more information on the Business Objects Education web site:
http://www.businessobjects.com/services/training
68 Desktop Intelligence Developer Guide
Get More Help
A
Send us your feedback
Do you have a suggestion on how we can improve our documentation? Is
there 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 next
release 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 about
Customer 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
A
Get More Help
70 Desktop Intelligence Developer Guide
Get More Help
A
Index
.rea 41
A
accessing
application events 46
Desktop Intelligence user interface 50
actions
adding to buttons 56
add-ins 10
creating 41
distributing 42
adding
actions to buttons 56
buttons 54
command bars 53
controls 54
macros 40
application events 44
implementing 46
Application object 46, 50
arrays
indexes 13
VBA 13
B
bitmaps
adding to buttons 55
building
query technique data provider 65
buttons
adding 54
adding actions 56
adding faces 55
buttons (continued)
definition 51
C
Chr function 16
classes
command bars 52
queries 62, 65
user interface 50
Clipboard object
pasting faces 55
collections
command bars 52
command bar controls
actions 56
adding 54
collection 52
definition 51
nested 52
command bars
adding 53
adding controls 54
collection 52
definition 51
controls
see command bar controls 51
creating
add-ins 41
macros 38
query technique data provider 65
customizing
Desktop Intelligence interface 50
Desktop Intelligence Developer Guide 71
D
data providers 60
freehand SQL 63
handling errors 64
loading and unloading 64
optimizing 64
personal text file 63
query technique 62
stored procedure 63
types 62
dBASE
querying 63
declaring
arrays in VBA 13
variables in VBA 11
Desktop Intelligence
customizing the interface 50
development environment
VBA 10, 15
disabling
macros 38
displaying pop-up menus 54
distributing
add-ins 42
document events 44, 45
E
errors
data providers 64
handling 64
handling in VBA 14
events
application 44
document 44, 45
form 57
implementing 11, 45
order 45
triggers 45
Excel
querying 63
executing macros 40
external object libraries 15
F
faces
adding 55
recommended size 56
filling a microcube 66
flow control
in VBA 12
forms
creating 57
freehand SQL data provider
definition 63
functions 11, 16
H
handling
errors in VBA 14
I
implementing
form events 57
implementing events 11, 45
including
external object libraries in VBA 15
indexing
arrays in VBA 13
L
loading
data providers 64
M
macros 10
adding 40
72 Desktop Intelligence Developer Guide
Index
macros (continued)
creating 38
running 40
tool tips 40
memory management
data providers 64
menu bar
definition 51
menus
nesting 52
microcube
filling 66
N
nesting controls 52
O
Object Browser 10
opening 15
object models
user interface 50
objects
browsing in VBA 15
external 15
On Error statement 14
optimizing
data providers 64
P
personal text file data provider
definition 63
pop-up menus
adding 53
definition 51
displaying 54
nesting 52
procedures 11
browsing in VBA 15
Q
Queries object 65
Query Panel 65
query technique data provider
creating 62, 65
definition 62
running and refreshing 66
R
referencing
external object libraries in VBA 15
refreshing
query technique data provider 66
reports 66
repository 62
running
macros 40
query technique data provider 66
S
showing pop-up menus 54
SQL 66
data provider 63
stored procedure data provider
definition 63
sub-routines 11, 38
T
tool bars
adding 53
definition 51
tool tips
macros 40
Desktop Intelligence Developer Guide 73
Index
U
universes
querying 62, 65
unloading
data providers 64
user input 50
user interface
customizing 50
V
VBA 10
arrays 13
creating forms 57
data types 11
events 11
flow control 12
VBA (continued)
functions 16
implementing an event 45
language summary 10
On Error statement 14
variables 11
With statement 14
writing macros 38
VBA procedure data provider
creating 62
Visual Basic
editor 10, 40
tool bar 40
W
With statement 14
74 Desktop Intelligence Developer Guide
Index