baan openworld broker 2.1 developer’s guide open world broker 2.1.pdf · 2017. 12. 4. · api...

Baan OpenWorld Broker 2.1

Developer's Guide

A publication of:

Baan Development B.V.P.O.Box 1433770 AC BarneveldThe Netherlands

Printed in the Netherlands

© Baan Development B.V. 2001.All rights reserved.

The information in this documentis subject to change withoutnotice. No part of this documentmay be reproduced, stored ortransmitted in any form or by anymeans, electronic or mechanical,for any purpose, without theexpress written permission ofBaan Development B.V.

Baan Development B.V.assumes no liability for anydamages incurred, directly orindirectly, from any errors,omissions or discrepanciesbetween the software and theinformation contained in thisdocument.

Document Information

Code: U7543A USGroup: User DocumentationEdition: ADate: January, 2001

i

Developer's Guide

1 Product overview 1-1

2 Organization of the system 2-1Introduction 2-1Server 2-1NT service 2-1Object repository 2-2Application objects 2-2Data storage 2-2Client 2-3Thin client 2-3Configuration utility 2-3Monitor - Debugging scripts 2-4

3 Repository browser 3-1Introduction 3-1To manipulate existing objects 3-2Object versions 3-2Object relations 3-2To create objects 3-5Object information 3-5To obtain object information 3-5To change object flags 3-6To export and import objects 3-7Special folders 3-8

4 Basic concepts 4-1Object and class 4-1Properties and operations 4-1Logical data type 4-1Value 4-2Expression 4-2Variable 4-2Scripting example 4-3

5 Logical data types 5-1Structure and purpose 5-1Creating logical data types 5-3

Table of contents

Table of contents

Developer's Guideii

6 Scripting language 6-1Purpose 6-1To create scripts and expressions 6-2Expressions 6-3Example expressions 6-3Structure of expressions 6-4Object references 6-4Operators 6-5Left-hand expressions 6-5Operations 6-6Row and array constructors 6-6Scripts 6-7Syntax 6-7Control commands 6-7Table and array loops 6-9Exceptions 6-9Run-time binding 6-10Available operations 6-10Operations on built-in types 6-10Operations on tables 6-10System operations 6-11

7 Component integration 7-1The component integration subsystem 7-1Design overview 7-2Example cases 7-2Components 7-6Code mapping 7-7Purpose 7-7Structure of the mapping table 7-7GUID 7-8Operations 7-9Technical details 7-9Logical data types and components 7-10Integration operations of types and values 7-11Synchronization 7-12Time stamp order 7-13Two-phase commit protocol 7-14Rollback 7-16Primitive operations 7-17Variables and parameters 7-18Examples of primitive operation implementations 7-18Iterators 7-22

Table of contents

Developer's Guideiii

Communication mechanisms 7-22Component integration subsystem � COM interfaces 7-23Design overview 7-24Design approach 7-24Return values 7-24Init and close methods 7-25IBaanCISConnector 7-25IBaanCISComponent 7-28IBaanCISIterator 7-30IDL listing 7-31Component instances 7-36Design overview 7-36Design approach 7-37Component editor enhancement 7-37Type Editor enhancement 7-39Run-time behavior 7-41IActiveScripting 7-42Types 7-52

8 Messages 8-1Introduction 8-1To handle incoming messages 8-1Purpose 8-1Supported technologies 8-2Actions 8-2Procedure 8-3Facilities for sending e-mail 8-4To send messages to users 8-4Messaging subsystem 8-5Design overview 8-7Design approach 8-8Message queues 8-8Message sources 8-9Message sinks 8-18Message handlers 8-22IDL listing 8-23

9 Tools and assistants 9-1Tool dock 9-1Expression tool 9-2Fields tool 9-2Fonts tool 9-2Color tool 9-3

Table of contents

Developer's Guideiv

Applying colors to objects 9-3To mix colors 9-4Named colors 9-4Action wizard 9-5Function of the action wizard 9-5Macros in e-mails 9-6Variables 9-6Poll message source action in Action Wizard 9-7Push to message sink action in the Action Wizard. 9-9Type assistant 9-11Expression assistant 9-11Script assistant 9-12

10 User interface 10-1Introduction 10-1Drop-down menus 10-1Windows and dialog boxes 10-1Forms 10-2Queries 10-2The main window 10-3Messages 10-3

11 Periodic processes 11-1

12 Alerts 12-1

13 Internet and HTML 13-1

14 User management 14-1User objects 14-1To log on 14-1Access rights 14-2User environment 14-3

15 Language support 15-1Introduction 15-1To enter texts in multiple languages 15-1To set the user language 15-2Text export 15-2

16 To export and import objects 16-1Introduction 16-1To export objects 16-2To import objects 16-2Component export & import 16-3Export labeled objects 16-5

Table of contents

Developer's Guidev

Expression export 16-5

17 Version control system 17-1Introduction 17-1Purpose 17-1Check out and check in 17-1To set up the VCS 17-2User data 17-2Object information 17-2Objects not under version control 17-3To view information about version-controlled objects 17-4Check out, check in, undo check out 17-4Locking 17-5Labels 17-6To put labels on objects 17-6To use labels 17-7Restore old object versions 17-8Get 17-8Rollback 17-9Export and import 17-9Impact of VCS on export and import 17-9Export labeled objects 17-9Discard old object versions 17-10

18 Logging system 18-1Introduction 18-1To set up the logging system 18-2Database connectors 18-2Configuration utility 18-3Component integration log 18-3User-defined logs 18-5The data in the logs 18-6The log event viewer 18-7Logging System Enhancements 18-7Design entities 18-8COM objects 18-10

19 COM interfaces 19-1Introduction 19-1Purpose of the COM interfaces 19-1COM components 19-2How to use the COM interfaces 19-3Co-classes 19-4Interfaces 19-6

Table of contents

Developer's Guidevi

Overview example 19-7IBaanIntegrationServer 19-8IBaanConnection 19-10IBaanRepository 19-14IBaanAttributes 19-16IBaanObject 19-19IBaanFolder 19-21IBaanType 19-21IBaanType2 19-24IBaanValue 19-26IBaanCodeMap 19-30IBaanPeriodic 19-34IBaanProfile 19-50To handle errors 19-51Enumerations 19-53ObjectKind 19-53Hidden and/or restricted interfaces 19-54IBaanConnectionProxy 19-54IBaanRepository 19-55IBaanObject 19-56IBaanFolder 19-57IBaanValue 19-58

20 Object type reference 20-1Introduction 20-1Alerter 20-4Component 20-6Database connector 20-9DLL proxy 20-12Environment 20-14File 20-16Form 20-26Introduction 20-26General form properties 20-28Form content 20-30Expression fields 20-35Input fields 20-36Push buttons 20-39Static text 20-40Picture 20-41Static box 20-43Operations 20-44Global variable 20-47

Table of contents

Developer's Guidevii

Iterator 20-49ITK Merge 20-54Configuration Utility 20-55Scripts 20-56Adapter - Service 20-57Tasks 20-59Profiles 20-64Logical data type 20-65Mapping 20-74Design Approach 20-75Mapping editor 20-75Transformer 20-84Scripting language 20-85Menu 20-85Message handler 20-88Message queue 20-91Message source 20-92Object set 20-99Periodic process 20-101Picture 20-103Point2Point 20-104Point-to-point object 20-106Query 20-110Resource 20-112Text table 20-114Timed variable 20-116User 20-118User group 20-120Workflow 20-121

21 Iterators 21-1Design overview 21-1Design Approach 21-1Design entities 21-2To verify or test an iterator 21-2To run an iterator 21-2Iterator properties 21-3

Table of contents

Developer's Guideviii

22 Recurrence schemes 22-1Interval recurrence scheme 22-1Monthly recurrence scheme 22-2Yearly recurrence scheme 22-3CODA softdate recurrence scheme 22-4Ranges 22-6

23 Built-in primitive types 23-1Introduction 23-1Overview of primitive types 23-1

24 Broker as an Adapter Server 24-1Functional overview 24-1Broker services 24-3Broker BOI Development 24-6Run-time configuration - Bus Components 24-10

25 Index 1

Table of contents

Developer's Guideix

Developer's Guidexi

This document can be used in the following ways:

� Developers can use this document if they integrate applications using theBaan OpenWorld Broker.

� Administrators and developers can also use this document if they want toconfigure and customize the Broker, for example, by adding menus andcommands.

� System administrators can use this document when they manage useraccounts, the logging system, database connections, and so on.

Chapters 1 through 6 introduce the Broker and the main components of theBroker.

Chapters 7 and 8 provide a detailed description of the component-integrationsystem and the messaging system.

Chapter 9 describes a number of system utilities, such as the tool dock and thetype assistant.

Chapters 10 through 19 explain the other features that you can use to buildapplications in the Broker.

Chapter 20 provides detailed instructions for the creation and use of all the user-definable types of objects.

Chapter 21 describes the Broker's built-in types.

For details about the scripting language, refer to the Scripting LanguageReference (U7278D US).

About this document

About this document

Developer's Guidexii

Definitions, acronyms, and abbreviationsTerm DefinitionAMI Application Messaging Interface.

AMI is the OAG's standard Application Messaging Interface,endorsed by IBM. AMI uses a set of policies which holddetails of how messages are to be handled, for example,priority, confirmation of delivery, timed expiry.

API Application Programming Interface.Asynchronouscommunication

Data-communication system in which the application thatsends data does not wait for the completion of thecommunication.Typical technologies for asynchronous communication aree-mail, message queue software, and batchwise exchangeof data files.

Baan OpenWorld Baan OpenWorld is a suite of products that provides thecomplete integration framework to connect Baanapplications with one another as well as with any third partyor homegrown application.

BOI Business Object Interface.DLL Dynamic-Link Library; a file containing software functions

which are ready for use by any application that links to theDLL.

DNS Domain Name System; Domain Name Server.GUID The Globally Unique Identifier of an object.

A GUID is displayed in the form "{19091955-BB74-11D2-95E2-00805FA3A240}.�

HTML Hypertext Markup Language.MAPI Mail Application Programming Interface.MDI Multiple-document interface; a user interface in an

application that enables the user to have more than onedocument open at the same time.

MSMQ Microsoft Message Queue Server.ODBC Open Database Connectivity; a programming interface that

enables applications to access data in databasemanagement systems that use SQL as a data accessstandard.

SMTP Simple Mail Transfer Protocol.SQL Structured Query Language; a data access standard for

databases.

About this document

Developer's Guidexiii

Synchronouscommunication

Data-communication system in which a transaction in oneapplication component involves immediate data transfer tothe other application component. The communication is sofast, that the component can wait for completion of thecommunication before proceeding.Typical technologies for synchronous communication areCOM, DCOM, and CORBA.

UNC Universal Naming Convention; the system for indicatingnames of servers and computers, such as"\\Servername\Sharename."

VCS Version Control System.XML eXtensible Markup Language.

About this document

Developer's Guidexiv

Developer's Guide1-1

The Baan OpenWorld Broker is a system you can use to develop and runapplications, and it is very flexible in communicating with other applications. Assuch, it is an excellent tool to integrate business applications using bothsynchronous and asynchronous communications methods.

The Broker applications consist of collections of objects, stored in a repository.By building logical data types, you can define a data structure which isindependent from any physical representation. If you model your businessdomain by using these logical data types, you can link the data model to anyapplication. You can use this link to send data between applications, but you canalso enable multiple applications to participate in operations on your data. In thisway, you can combine component applications to form a well-integrated,component-based system.

The component applications do not need to be modified, provided that theysupport reasonable interfaces to the outside world.

The Broker's component integration subsystem is described in detail inChapter 7, �Component integration.�

The Broker has a scripting language with a syntax based on C++. You can usethis scripting language to define any action that must be performed. For moreinformation, see Chapter 6.

The following tables present an overview of features of the Broker.

1 Product overview

Product overview


Supported technologies to connect applicationsFeature Description Where

documentedCOM Automation The Broker can access Microsoft COM

Automation objects from within its scriptinglanguage. This feature offers a powerfulmethod to integrate with other applicationsthat provide access through a COM client.

Chapter 7

COM interfaces The Broker exposes its services to COMclients by means of COM interfaces. A COMinterface enables external programs accessto the objects in the object repository.

Chapter 19

Thin client The Broker's COM interfaces can be usedas a thin client for work with an application,data entry and retrieval, and so on. You canrun the thin client in any container thatworks with COM components, for exampleInternet Explorer, Visual Basic, and so on.

Chapter 19

DLLs The Broker can access DLLs on theworkstation of the user.

The DLLproxy sectionin Chapter 20

Supported communication technologiesFeature Description Where

documentedE-mail The Broker supports the SMTP, POP3, and

MAPI protocols for e-mail systems. TheBroker can send e-mail messages andprocess incoming e-mail messages.Incoming e-mail messages can beconverted to internal data types.

Chapter 8

Message queues The Broker can receive messages fromMicrosoft's MSMQ and IBM's MQSeriesmessage queue software.

Chapter 8

XML, Biztalk The Broker can process messages in XMLand Biztalk framework format.

Chapter 8

Internet protocols The Broker supports the HTTP and FTPInternet protocols and handles documents inHTML format.

Chapter 13

Product overview


Database connectionsFeature Description Where

documentedODBC databases The Broker can access ODBC-compliant

databases either by using a mapping ofinternal table types with database tables, orby using free-style SQL statements.

The Databaseconnector andFile sectionsin Chapter 20

File access The Broker can write to and read from textfiles.

The Filesection inChapter 20

Additional functional featuresFeature Description Where

documentedUser interface Building blocks to create user interfaces,

such as forms, menus, and message boxes.Chapter 10

Periodicprocesses

Automatic execution of recurring activities,such as system administration tasks.

Chapter 11

Alerts Continuous monitoring of criticalperformance indicators and alerting a user ifthe indicator exceeds certain limits.

Chapter 12

Messages tousers

A system to send messages to themailboxes of users of the Broker.

Chapter 8

Workflow A system to control the flow of documents tousers for further handling.

The Workflowsection inChapter 20

Technical featuresFeature Description Where

documentedVersion controlsystem (VCS)

A system to control and store versions ofobjects.

Chapter 17

Logging system A system to log errors and other events. Chapter 18Export and import Exporting and importing of objects for

backup or distribution of objects to otherservers.

Chapter 16

Language andtranslationsupport

Storing texts in multiple languages anddisplaying the user interface in the user'slanguage.

Chapter 15

Product overview



IntroductionThe Baan OpenWorld Broker has a client-server architecture. Users can start theBroker client program on their workstations. The client connects to the serverthrough a TCP/IP protocol.

The server runs under the Windows NT operating system. The client runs onWindows 95, and Windows 98, and Windows NT.

The system can be configured by means of a configuration utility based onMicrosoft Management Console (MMC).

ServerThe Broker server consists of a kernel and an object repository. The kernelexecutes the processes of the server and an object repository stores all objects.

The main functions of the server are:

� To store objects in the central object repository.� To serve objects to clients that edit or use the objects.� To execute periodic processes and alerters.� To run the workflow engine.

NT serviceThe server program runs as a Windows NT service. The server program does nothave a user interface. The Broker service is configured to start automaticallywhen the server system is started. You can also start or stop the Broker servicemanually.

2 Organization of the system

Organization of the system


To start or stop the Broker service:

1 On the Windows task bar, click the Start button, point to Settings, and clickControl Panel.

2 In the Control Panel, double-click Services.

3 Click the Baan OpenWorld Broker service.

4 Click Start or Stop.

Object repositoryThe object repository is a simple, proprietary database, optimized for Brokerobjects. The object repository is stored in a single file. You can specify the objectrepository file in the configuration utility.

Objects are serialized and stored as a stream of bytes. Broker uses several cachesto achieve a high performance level. Objects can be stored in compressed form.

The integrity of the object repository is ensured by a transaction system. Theobject repository never implements an incomplete transaction. If the applicationterminates abnormally, the system uses a roll-back mechanism to restore theobject repository to its last secure status.

Application objectsThe central object repository contains both system objects and applicationobjects. If you create new objects, you can develop your own applications in theBroker. These objects contain all the application logic.

The Broker contains a set of predefined objects, which you can use forintegration with particular applications, for example, between BaanFrontOfficeand BaanERP.

Data storageUsually, you do not store your data internally in the Broker. The Broker hasspecial features to connect to external databases, which you use for permanentdata storage.

If you do need to store data in the Broker, you can create global-variable objects,which are held in the object repository.



ClientThe Baan OpenWorld Broker client program runs on the user�s workstation. Theclient can be used by developers of applications and by the end users that runthese applications. You can use the client to:

� Send commands to the server.� Display objects.� Open a repository browser to access the objects in the object repository.� Create and edit objects.

To open a repository browser and to edit objects, you must have superuseraccess.

Thin clientThe Broker provides COM interfaces that enable access to the object repositoryfrom any container that works with COM components, for example InternetExplorer, Visual Basic, and so on. You can develop a thin client based on theCOM interface. You can use this thin client for data entry and retrieval, and soon.

To use a thin client, users must register the bsrvitf.dll file on their workstation. Ifyou install the Installation Server client, the install program registers bsrvitf.dllfor you. For more information, see Chapter 19, �COM interfaces.�

Configuration utilityA special configuration utility enables you to configure the server and clientprograms. The configuration utility is a plug-in for Microsoft ManagementConsole (MMC). If you install the Broker, the installation program installs andregisters a COM control that you can open in MMC.

To configure the server or the client, take the following steps:

1 Start the Baan OpenWorld Broker Configure program.

2 In Microsoft Management Console (MMC), open the folders in the ConsoleRoot window.

3 Right-click the Server or the Client icon.

4 In the shortcut menu, click Properties.

5 Specify the settings as you like.

NOTE



In general, the changes you make in the configuration utility will take effect afteryou restart the Broker server, the client, or both.

Monitor - Debugging scriptsThe Baan OpenWorld Broker Monitor enables you to see which clients arecurrently connected to the server.

A new capability is added to the Server Monitor of OpenWorld Broker. A newtab is added, in addition to the tab that displays connected clients.

This tab receives debug notifications from the server for all clients. For example,using the System.debug script operation, or using the printf statements in scripts,will result in these messages being routed to all active Server Monitors. Note thatthe printf statement still displays a message box if the script is evaluated on theclient, for example, in buttons on forms.

You can configure the Server Monitor to accept these messages or not. You canalso configure to how many messages the Server Monitor must buffer.


IntroductionBoth system objects and application objects are stored in a single central objectrepository. If you have superuser access, you can open the repository browser tomanage the objects in the object repository. To open the repository browser, onthe File menu, click Repository browser. The following figure (see Figure 1)shows a screen shot of the repository browser.

Figure 1 The repository browser

3 Repository browser

Repository browser


To manipulate existing objectsIn the repository browser, you can modify, move, copy, rename, and deleteexisting objects. For most of these operations, you must first select an object byclicking the object in the repository browser. You can then click thecorresponding command on the File menu or on the Edit menu.

You can also:

� Modify an object by double-clicking the object.

� Move an object by dragging the object to another folder. To create newfolders, you must click the New Folder button on the toolbar.

� Copy or move an object by means of the Cut, Copy, and Paste commands onthe Edit menu.

� Rename an object by double-clicking the name of the object.

� Open a shortcut menu with additional functions by right-clicking an object.

Object versionsIf an object is maintained under the version control system (VCS), you mustcheck the object out before you can make any changes. Earlier versions of theobject are automatically archived for future reference.

You cannot modify the VCS status of objects unless you have access rights forthe VCS.

For more information, see Chapter 17, �Version control system.�

Object relationsOW Broker can now store relations between repository objects in a separatedatabase table. The repository server automatically updates object relations asobjects are modified and saved in the repository.

The object relations table (bis_objrelations) contains the following columns:

� Frompath (VARCHAR).� Reltype (VARCHAR).� Topath (VARCHAR).� Parameter (VARCHAR).

Repository browser


You can access the relations table through the database connector object\sys\databases\relations, or \sys\databases\default, if relations do not exist, whichmust point to a valid ODBC System Data Source Name (System DSN) on theOpenWorld Broker server. If the bis_objrelations table does not exist in thedatabase, the table is automatically created with the appropriate indices.

Microsoft Access 2000 has a documented problem with regards to creation oftables with VARCHAR columns from ODBC. Microsoft advises users to use thelightweight SQL engine (MSDE) that ships with Microsoft Office 2000 insteadof MS Access 2000 for this type of application. An even stronger engine, such asSQL Server 7 or Oracle, is recommended to maintain OpenWorld Broker tables,including the bis_objrelations table.

The most common relation between objects is the DEPENDS_ON relation. Forexample, a particular type X can depend on type Y and workflow object W. Thisrelation is stored as follows in the bis_objrelations table:

Frompath Reltype Topath Parameter\SomeFolder\X DEPENDS_ON \SomeFolder\Y\SomeFolder\X DEPENDS_ON \SomeFolder\W

NOTE

Repository browser


Using this information, you can easily query which objects are dependent on aparticular object. This information is available to the user through the Info dialogbox in the repository browser menu, as shown in the following figure:

You can also store other relations. Currently, following three relation types arealso maintained by the system:

� HAS_DOCUMENT_TYPE: Relates a workflow object to the object�sdocument type.

� MAPS_FROM: Relates a mapping object to the object�s source type.

� MAPS_TO: Relates a mapping object to the object�s target type.

To navigate object relations from C++ source code, you can use new memberfunctions such as navigate, navigateInverse, queryRelation,queryInverseRelation, and queryDependents, all of which are available on theNamedObjectRef class.

Repository browser


To create objectsTo create objects, you can either use the buttons in the repository browser, orclick the New button on the Objects menu. If you create a new object of aparticular type, the editor for that type of object is started, for example, the formeditor.

Naming rules

Object names must be no longer than 24 characters, must consist only ofalphanumerical characters plus the underscore (_) character, and must not startwith a number. Object names are case-sensitive.

For detailed instructions on how to create objects, see Chapter 20, �Object typereference,� and the online Help.

Object informationTo obtain object informationYou can obtain useful information about the status of an object in an object'sdialog box. To open an object�s dialog box, take the following steps:

1 Select the object in the repository browser.

2 On the File menu, click Info.

The dialog box shows information about, for example, the object�s creation dateand the user that created the object, the locking status, and so on.

Repository browser


To change object flagsThe following table lists the object flags that you can set on the Flags tab of anobject�s dialog box.

FlagsFlag DescriptionCompressed If you enable this option, the object is stored in

compressed form.Compressed objects require additional processor timefor decompression, but they occupy less space in cachesand are transmitted more quickly over a network.

Protected You cannot modify protected objects.The protected status is used for objects that are requiredfor the system to work. You can only enable turn theprotected flag on or off if you use the Archive.setFlagsoperation in the scripting language.

Enable VCS Specifies that the object is under version control. Formore information, see Chapter 17, �Version controlsystem.�

Logging flags The logging flags specify the events for which the Brokergenerates a log entry. For more information, see Chapter18, �Logging system.�

To modify the flag status of multiple objects from several folders in a singleaction, you can use the Change Object Storage Flags dialog box. This dialogbox is started by means of the setFlags operation of the Archive object.

Repository browser


To open the Change Object Storage Flags dialog box, take the following steps:

1 Click Open Tool Dock on the File menu. You can also find the Open ToolDock command on the Objects menu in the repository browser.

2 Enter the following expression in the Tool Dock�s Expression tab:Archive . setFlags

3 Click Evaluate.

To make operations such as this more readily available to you, place theseoperations in a menu. For more information, refer to �Menu� in Chapter 20,�Object type reference.�

To use the Change object storage flags dialog box:

1 In the Change object storage flags dialog box, add or remove objects fromthe Objects to change list until you are satisfied with the resulting selection.

2 Indicate which flags you want to turn on or off by selecting one or more ofthe following check boxes:−−−− Set Compressed Flag.−−−− Set Protected Flag.−−−− Set Version Control System Flag.−−−− Set Logging Flags.

3 Select or clear the Compressed check box to indicate whether the flag mustbe turned on or off.

4 Set the remaining check boxes and option buttons according to yourrequirements.

5 Click OK.

To export and import objectsYou can export objects from the object repository to a file. You can keep this fileas a backup of your objects, or you can import the objects on another server. Formore information, see Chapter 16, �Exporting and importing objects.�

NOTE

Repository browser


Special foldersThe following table lists a number of object repository folders that have a specialfunction.

Special foldersFolder Function\apps Stores a number of predefined applications, such as the

mailbox viewer and the event-log viewer.\predef\CODA Stores objects used to communicate with CODA-

Financials servers.\predef\system Stores built-in objects, for example the objects that

represent predefined types. You cannot change theseobjects.

\sys Contains subfolders that store system objects, such asdatabase connectors for the code map and loggingsystem, user mailboxes, and so on.

\sys\alertvalues Used by alerters to store the results of the evaluation ofa checked variable or expression.

\sys\biztalk Stores logical data types used by the translator of Biztalkmessages.

\sys\codes Stores a database connector for the code mappingservice.

\sys\logging Stores database connectors for the logging system.\sys\mailboxes Stores the user mailboxes.\sys\processes Stores active periodic processes and alerters.\sys\system\abrowse Stores the menu for the repository browser.\sys\system\default Stores the Broker default menu.\sys\vcs Used by the version control system to store internal

information about object versions.\sys\xml Stores logical data types used by the translator of XML

documents.\users Stores users and user groups.\vars Stores timed variables that can be monitored by alerters.


In this chapter, the basic concepts of the Broker are explained.

Object and classProperties and operationsThe Baan OpenWorld Broker has an object-oriented structure. In other words,the Broker consists primarily of objects. Each object has certain properties andoperations that the user can access through the scripting language. For example,the system object Abrowse represents the repository browser. This object has anoperation smallIconView(), which switches the view of the repository browser tosmall icons.

In addition to the predefined objects of the system, such as Abrowse, System,and CodeMap, you can define your own objects. Each object belongs to a certainclass. An object's class determines the types of properties and operations theobject has. For example, all objects of the User class have properties such asName, Password, and E-mail address, and operations such as sendMessage.

Logical data typeLogical data types, which are also sometimes called types, describe the natureand structure of data. This logical data description is independent of the physicalform of the data being processed. Some simple types are predefined, forexample, String, Number, and Time. You can use these simple types to buildcomposite logical data types, which represent objects in your application domain,such as a customer or a sales order.

The most common kinds of logical data types are row types and table types:

� A row type consists of a number of fields, for example, the Name, Address,and Phone fields.

� A table type is a collection of values of a row type on which you can runoperations, for example, you can insert a new row, delete a row, sort, and soon.

4 Basic concepts

Basic concepts


ValueEach unique instance of logical data types is called a value. The numbers 42096and -0.107 are values of the logical data type Number. The text �honeybee� is avalue of the logical data type String. For example, suppose that you have defineda CustomerRow row type to store data about customers. As a result, an instanceof this logical data type is a value that represents one particular customer.

ExpressionAn expression is a sort of calculation procedure. If an expression is evaluated(calculated), the expression produces a value. Example expressions:

� 12+3.� System.queryTime.

The expression 12+3 produces 15, which is a value of type Number. Theexpression System.queryTime produces the system time, which is a value of typetime.

VariableA variable is capable of holding a value of a certain logical data type. You canuse these variables in an expression.

In a script, you can define variables to store values while the script runs. If youwant a variable to hold a value during a longer period, you can define one of thefollowing types of objects in the object repository:

� Global variable.� Timed variable.� File objects.

You can also use these objects as variables in an expression. For a detaileddescription, see the relevant sections in Chapter 20, �Object type reference.�

If you assign a new value to a variable, the type of the value must match the typeof the variable. You can invoke the operations of the logical data type of thevariable. For examples of variables, refer to the following section.

Basic concepts


Scripting exampleThis section shows what variables and types look like in the scripting language.However, the syntax and semantics of this example script are not explained indetail.

The example script contains:

� The logical data types String and CustomerType.� The variables strName and cust.� The operations new, uppercase, and store.

This scripting example first defines two variables, and then assigns values tothese variables; the values are the results of expressions. You can also see howoperations are invoked.

{

String strName;

CustomerType cust;

strName = "Theodorus";

cust = CustomerType . new ();

cust.name = strName . uppercase();

cust . store ();

}

Basic concepts



Structure and purposeLogical data types describe the nature and structure of data. This logical datadescription is independent of the physical form of the data being processed.

Logical data types are often simply called types.

The Broker has a number of built-in logical data types, such as String, Number,Time, and Sound. These built-in types are described in Chapter 21, �Primitivetype reference.� You can combine these primitive types to create compositelogical data types. To define operations for logical data types, you can use thescripting language.

There are four different variants of user-defined logical data types, as describedin the following table.

Logical data typesData type DescriptionRow A collection of data fields, each of which can have a different

logical data type. You can use a row type to define the structureof records. For example, Employee number (Number), Name(String), Date of birth (Time), Department (String).

Table A collection of elements of the same type. The number ofelements in a table can grow or shrink as required. Forexample, you can store a list of customers in a table.

Array A collection of elements of the same type. Arrays have a fixednumber of elements. For example, you can use an array ofstrings with 12 elements to store the names of the months.

Enumeration An enumeration type is a logical data type describing the statusof an object or event. Each possible status is represented by aname. For example, an enumeration type StudentLevel canconsist of the names: Novice, Intermediate, or Advanced.

Applications defined in the Baan OpenWorld Broker are usually built around anumber of table types and row types.

A logical data type only describes the nature and structure of data. The logicaldata type cannot store any data in itself. The Broker provides several ways tostore the data.

5 Logical data types

NOTE

NOTE

Logical data types


Global variable

You can use a global variable to store tables directly in the Broker repository.

File object

You can use a file object to link a table directly to an external source, such as anODBC-compliant database or a comma-delimited ASCII file. In the scriptinglanguage, you can use the file object as a variable of the table type. For moreinformation, see �File� in Chapter 20, �Object type reference.�

Multicomponent applications

In more complex situations, the table data is stored in multiple externalapplications. Each external application, also called a component, can participatein a logical data type by means of the component integration subsystem.

For example, suppose you are a supplier of chemicals and you have a databaseapplication with safety information on hazardous materials and a businessapplication with sales data. You can create a logical data type for chemicals inwhich both applications take part.

In the scripting language, you can declare a variable of a logical data type, anduse the load operation to populate the variable with data from the participatingcomponents. For more information, see Chapter 7, �Component integration.�

Logical data types


Creating logical data typesThe following figure (see Figure 2) shows the type editor that you can use tocreate logical data types. This example shows the CustomerRow row type thathas fields such as the CustomerId and CompanyName fields. You can also seehow the components, BFO and CF, are placed in the definition of the type. Thetype definition exactly specifies how values of this type interact with thecomponents BFO and CF.

For detailed instructions for the creation of logical data types, refer to �Logicaldata type� in Chapter 20, �Object type reference,� or the online Help.

Figure 2 The type editor

Logical data types



PurposeThe Baan OpenWorld Broker has a powerful scripting language. You can use thescripting language to create scripts and expressions.

You can use scripts and expressions to define:

� Actions that must be performed if the user clicks a button or a menucommand.

� The response of the system to other events that can occur, for example, amessage is received or an alerter variable exceeds a critical limit.

� Conditions. A condition is something that can be true or false, for example,the statement �The current user has superuser access� is a condition.

� Operations on data.

Scripts and expressions

Scripts and expressions are similar items. Both define a sort of calculationprocedure. The difference between a script and an expression is:

� A script is a list of statements between braces: { and }. Each statement endswith a semicolon (;). If the system executes a script, the script can returnvalues with the help of the return command.

� An expression is something that produces a value, for example, theexpression 1+2+3+4 produces the result 10.

6 Scripting language

Scripting language


To create scripts and expressionsYou can enter scripts and expressions in many objects. For example, if youcreate a user object, you can write a script that must run automatically if the userlogs on to the system.

The scripting language is structured similarly to C and C++. However, thescripting language has a number of special features, such as:

� On-the-fly data types.� Table and array loops.

For more information on these features, refer to Chapter 2, �LanguageSemantics� in the Scripting Language Reference (U7278D US). This referenceguide also contains all details about the syntax, classes, objects, and operations.

Tool dock

The tool dock has an expression tool in which you can enter an expression andevaluate the expression immediately. For more information, refer to �Expressiontool� in Chapter 9, �Tools and assistants.�

Script assistant

In places where you can enter a script or expression, you can press F4 to open anexpression assistant or a script assistant. For more information, refer toChapter 9, �Tools and assistants.�

Scripting language


ExpressionsExample expressionsAn expression is something that produces a value. The following table providesseveral examples to help get a better idea of what expressions are:

Examples of expressionsExpression Result

typeExplanation

12+3 Number A simple calculation. The result is 15.42 Number The result of this expression is 42.Item.price = 120.95 + 5 Number This expression calculates the sum

of 120.95 and 5, and assigns theresult to the price field of the Itemobject. The value 125.95 is also theresult of the entire expression.

System.queryTime Time This expression produces the systemtime.

"The current time is " + Time() . queryFormattedTime ()

String This expression produces the systemtime as a text string.

\users\SUPERUSER.edit BOOL Evaluation of this expression opensthe dialog box to edit the propertiesof user SUPERUSER.If the user completes the edits andclicks OK, the result of theexpression is TRUE. Otherwise, theresult is FALSE.

"You are " + System .queryCurrentUserName ()

String If your user name is Pete, thisexpression results in the string "Youare Pete.�

" Total debt of all customersis: " + Customers . sum(Debt).asString

String This expression performs the sumoperation in the Debt field of theCustomers table.

CustomerEntryForm . run(Customers . select(PostalCode == "101") . sort(Name))

Void This expression first selects allcustomers with postal code 101.Then these customers are sorted byname.Finally, a form is opened whichdisplays these customers.

Scripting language


Structure of expressionsExpressions consist mainly of objects and operators. Remember that a simplenumber or string is also an object, for example, �abcd.� You can build complexexpressions, as illustrated with the following example.

The expression abcd.uppercase() produces ABCD, which is again aString object.

You can use this string in another expression, for example:

abcd.uppercase() + efgh

You can then apply an operation to that string object:

(abcd.uppercase() + efgh) . length ()

This operation returns the number 8, which is the length of the string.

Object referencesTo refer to objects in the object repository, you must indicate the full path, as inthe following examples:

� \users\SUPERUSER.� � \sys\system\defaults\StartupMenu.

You can perform operations on these objects. In the following example, the loadoperation is performed on the logical data type CustomerRow:

\types\CustomerRow . load ("BAANERP,” "00-2039")

File objects, global variables, and timed variables can be used as variables inexpressions, as shown in the following example:

The timed variable TotalSize and the global variable MAXIMUM_SIZE arestored in the \vars folder.

TotalSize calculates and stores the sum of the sizes of a number of data files.

MAXIMUM_SIZE stores a maximum size.You can now define the followingexpression:

( \vars\TotalSize <= \vars\MAXIMUM_SIZE ) .

EXAMPLE

Scripting language


OperatorsThe built-in logical data types all have conventional operations for addition,subtraction, division, and multiplication. You can apply these operations tovalues of these types. These operations can be applied by using the followingoperators:

+ - * / % += -= *= /= %= ++ --

Conventional comparison operations are also defined:

== != > < >= <=

The same applies to logical operations:

&& (and-operation) and || (or-operation)

In conditions, a zero number denotes FALSE, and non-zero denotes TRUE.

Left-hand expressionsA left-hand expression is an expression that can occur on the left-hand side of anequal sign (=).

For example, Days[0] is a left-hand expression. “Sunday” is not a left-handexpression. As a result, the following expression is correct:

Days[0] = “Sunday” .

The following expression is incorrect:

"Sunday" = “Dimanche” (Incorrect!)

Assignment operators ( =, +=, -=, *=, /=, and %= ) and increment and decrementoperators ( ++ and -- ) change the value of a variable. You can use theseoperators only in combination with left-hand expressions.

Left-hand expressions are also required to refer to fields of a row type, as shownin the following example.

The table type CustomerTable is a table of Customer rows.

The row type CustomerRow has a Name field.

The file object Customers, which has type CustomerTable, connects to adatabase table storing customer data.

The following expression is incorrect:

Customers.first () . Name (Incorrect!)

NOTE

EXAMPLE

Scripting language


You cannot retrieve the name of the first customer from a customer table in thisway, because Customers.first () is not a left-hand expression.

OperationsThe built-in types have a number of useful operations. You can invoke theseoperations on objects of these types. The Broker also has several predefinedoperations on table objects. These operations are described in the ScriptingLanguage Reference (U7278D US).

If an operation call has no parameters, you can omit the parentheses. Forexample, the following expressions are equivalent:

� "abcd.”uppercase()� "abcd.”uppercase

Row and array constructorsIn some instances, the Broker creates new logical data types on the fly. Forexample, to create a new value with an array logical data type, simply type list(3,4,5,6,7). The Broker constructs a new array logical data type with fivenumerical entries that will exist as long as the value exists.

You can create row types in a similar way with the row key word. If you want tocreate a row with text, number and color, you do so in the following way:

row ("Árni,” 197, Color (0,255,255)).

The fields are named column1, column2 and column3. To name the fields, youmust type a colon and the name of the field, for example:

row (100 : numField, "abc" : strField, Color (0, 255, 255) :

colorField).

Scripting language


ScriptsSyntaxA script consists of an opening brace ({), followed, optionally by one or morestatements, followed by an ending brace (}). Example script:

{

Number n;

n = 5 + 21;

return a;

}

Two other examples:

{

printf ("Display this text.");

}

{ \types\CustomerRow . load ("BAANERP,” "00-2039"); }

All statements end with a semicolon (;). A statement can be, for example, anexpression or a declaration, followed by a semicolon. A script can also containcontrol commands, which are described in the following section.

Control commandsAs mentioned before, the scripting language has the same library of controlstatements as C and C++. Here are a few short examples of using the maincontrol statements of the processing language.

if statements

The If statement is structured as follows:

if (condition)

statement;

If the conditions in the parentheses are true, the command is carried out,otherwise, the comman is not carried out. For example:

if (System . queryCurrentUserName () == "Arni")

printf ("Good day master");

If the logged-on user is Arni, the message appears on the screen.

If you must run more than one command, you must type the commands in thebraces ({ and }). For example:

Scripting language


if (Customers . count () == 0) {

printf ("Empty table!");

return FALSE;

}

If-else statements

With If-else, you can build up statements that say what to do if conditions are notmet. You can also chain If statements together to form a long row of Ifstatements.

For example:

if (n < 0)

handleLessThan ();

else if (n == 0)

handleZero ();

else

handleGreaterThan ();

For statements

Using the For statement, you can run iterations.

For example:

Number n;

for (n = 0; n <= 10; n++) {

printf ("%d times %d is %d,” n, n, n*n);

}

The first part of the For statement initiates variables you must use, in this case,the number variable n. Next, the statement specifies how many times to executethe operations in the braces. Here, the loop is repeated if n is less than or equal to10. Finally, the statement specifies what must be done at the end of everyiteration of the value in the braces. In this case, the number n must be increasedby one. This short program writes the following on the screen in 11 dialog boxes:

0 times 0 is 0

1 times 1 is 1

2 times 2 is 4

...

10 times 10 is 100

Scripting language


While statement

You use the While statement to have something carried out, as long as certainconditions occur. An example of a While loop that will accomplish the samething as the For loop mentioned in the previous section is:

Number n = 0;

while (n <= 10) {


n = n + 1;

}

Do statement

With the Do command, you can do something first and ask later.

The following example illustrates how you can accomplish the same thing withthe Do statement as with the For loop mentiond previously:

Number n = 0;

do {


n = n + 1;

} while (n <= 10);

Table and array loopsIn addition to while, for, do, and other C and C++ control statements, the Brokerprovides table and array loops. To set up these loops, you must write a table or alist expression and commands that will run once for each entry in the table or list.For more information, refer to Chapter 2, �Language semantics� in the ScriptingLanguage Reference (U7278D US).

ExceptionsThe Broker also enables the C++ commands throw and try/catch. You can usethe throw command to generate an exception, and you can use a catch commandto trap an exception in try-blocks. The system can also generate exceptionswithout the use of a throw statement, for example, if a division by zero occurs.

In the following example, the computer�s processor monitors whether an attemptis made to divide by zero, and then triggers an exception in these instances. Thescripting language traps this exception and gives notice of the exception in thecatch block.

try {

Scripting language


Number avg = nSum / nCount;

}

catch (Exception e) {

if (e . code () == 8)

// Divided by zero

printf ("Divided by zero, count is zero.");

else

throw; // Not interesting, throw it again

}

The catch operation accepts one parameter which is always of the Exceptionlogical data type. For more information, refer to the section �Class Exception� inthe Scripting Language Reference (U7278D US).

Run-time bindingThe Broker enables the so-called run-time binding of objects and operations.Among other things, this makes it possible to store various types of objects inone parameter. You can use operations without knowing when the process or theexpression is compiled, no matter to what RuntimeClass the relevant objectbelongs. For more information, refer to Chapter 2, �Language semantics� in theScripting Language Reference (U7278D US).

Available operationsOperations on built-in typesThe Broker's built-in types have a large number of useful operations. All of theseoperations are documented in the document Scripting Language Reference(U7278D US).

The following list provides several examples of built-in types and theiroperations:

� Number: Round, abs, asString, and so on.� String: Find, length, trim, uppercase, asNumber, and so on.� Time: QueryFormattedTime, queryFormattedDate, asString, and so on.

Operations on tablesThe Table class has many useful operations, for example, first, find, select, sort,max, sum, count, edit, and view. You can perform these operations on all thevalues of a table type.

Scripting language


System operationsThe Broker has a number of system objects, such as System, View, Environment,and Abrowse, which provide a number of operations that you can use in thescripting language. All of these operations are fully documented in the documentScripting Language Reference (U7278D US). The following table lists theseobjects:

System-wide objectsObject DescriptionAbrowse Contains operations which apply to the repository browser.

Most of these operations work on the currently selected objector directory in the repository browser. Example operations:new, copy, delete, export, and open.

Archive Contains operations that work on the object repository.Most of these operations are mainly used by the system.Other operations start a dialog box that enables you toperform a special task, for example, setFlags,exportLocaleStrings, or multiLabel.

Environment Contains operations that you can use to customize the systemper user or user group. Every user has an associatedenvironment.Example operations: arrangeIcons, and setLanguage.

Internet Contains operations to access Internet resources, forexample, getURL.

System Contains many operations that work on the Broker system.For example, changePassword, msgBox,queryCurrentUserName, readFile.

Workstation Contains operations associated with the current user�sworkstation.

Scripting language



The component integration subsystemThe component integration subsystem enables you to develop integrationsbetween applications. In this way, you can connect independent applications ascomponents of a comprehensive information system.

The following table lists the characteristics of the component integrationsubsystem:

Characteristics of the component integration subsystemAspect DescriptionLogical datamodeling

Integrations are built around common logical businessobjects of the enterprise, independent of the components�physical data definitions or low-level communicationmethods.The component integration subsystem models the stateand behavior of common objects, not just the movement ofdata from one component to another.

Communicationtechnology

Many means of communications are supported, bothsynchronous and asynchronous. For example, APIs, BOIs,direct database updates, COM-based object interfaces,and XML messages.

Loose coupling The components being integrated do not need to knowabout each other. The complete overview is stored in theBroker, which enables you to easily add, modify, orreplace components.

Nonintrusiveintegration

You do not need to change the source codes of theapplications that you integrate. The components only mustsupport some reasonable interfaces to the outside world.

Vendorindependence

The component integration subsystem works with users�in-house or third-party components in exactly the sameway as Baan�s own components.

7 Component integration

Component integration


Design overviewThe following list provides the three basic object types used in the componentintegration subsystem of Baan OpenWorld IS.

� Compenents describe the participation of a component in the intergrationscenario.

� Iterators objects are used to invoke batch transfer from source to onedestination or many destinations.

� Types: Definitions of logical business objects. Each type can have one ormore active components, and each component can implement a series ofprimitive operations used in data synchronization.

Example casesThe following case descriptions provide a clear picture of the capabilities of thecomponent integration subsystem. The scenarios described in this section are:

� Data synchronization.� Synchronization in a batch process.� Online update.� Query.� Remote entry of documents.� Submission of reports by e-mail.� Event notification by e-mail.

These examples are not explained in detail here, however, later sections explainhow you can use this functionality .

Data synchronization

A component notifies the Baan OpenWorld Broker that data has changed, forinstance a customer�s address. The Broker then updates the components tosynchronize the other components� information.

The following steps describe the process to synchronize the components:

1 A component sends out a message to inform the Broker that a piece of datahas changed. The component can send a message through a message queuesuch as MSMQ or MQSeries, by e-mail, or through another way.

2 The Broker messaging system picks up the message through a messagesource object, translates the message, and writes the message to an internalmessage queue.



3 A message handler object picks up the message and decodes the componentID and local code. The message handler deducts the logical data typeinvolved from the contents of the message. For example, the logical data typecan be Customer.

4 The message handler calls the synchronize operation of the logical data type.

5 The Broker first loads the object data from all participating components, andthen stores the compound object back into the participating components. Inthis way, every component receives the latest version of all data for thisobject.

Synchronization in a batch process

An ERP application contains a master item master file with codes anddescriptions for all items. Every night, the changes in the item file must be sentto a warehouse management system that manages the storage locations of theseitems. This can be controlled by a periodic process in the Broker. An iteratorobject is used for efficient synchronization.

The following steps make up the process to send changes to the warehousemanagement system:

1 The periodic process calls the synchronize operation of an iterator.

2 The iterator accesses the ERP application through a COM interface.

3 The iterator retrieves a table of all new and modified records in the itemmaster file. This table also lists the items deleted from the ERP application.

4 The Broker iterates through the table of modified records. For each record, aninstance of the Item logical data type is populated with up-to-dateinformation, and stored back into all participating components. If necessary,items are deleted from all participating components. The data is not updatedin the originating component (the ERP application), because that componentis considered to be up-to-date. This implies that only the warehousemanagement system is updated.



Online update

In this case, a client wants to read, update, then resave an existing objectinstance. A typical client for this scenario would be an in-house application tomaintain customer information.

The following steps describe the process to make online updates:

1 The client application accesses the Broker through the COM object, which isprovided as part of the Broker.

2 The load operation of the logical data type runs to fetch the object from allparticipating components.

3 The client modifies the instance data, using the Broker's COM interfaces.

4 The client calls the object�s store operation to store the object in allparticipating components.

Rollback

If the Store operation fails in any of the components, you can use a rollbackfunction to undo the entire update operation.

Query

A user wants to read an existing object instance for query purposes. The useruses a client application that accesses the Broker, for example, a self-serviceWeb page.

The following steps make up the process to read an existing object instance forquery purposes:

1 A script in a Web page accesses the Broker through the COM object, whichis provided as part of the Broker.

2 The load operation of the logical data type is run to fetch the object. Acomponent ID and code are passed to the operation. The object data isobtained from all participating components.

3 The client displays the data.



Remote entry of documents

An accounting document is entered in a Web page or spreadsheet and sent to theBroker for processing.

The following steps describe the process to enter the accounting document, andsend the document to be processed:

1 A script in the Web page or a spreadsheet macro accesses the Broker throughthe COM object which is provided as part of the Broker.

2 A fresh instance of an AccountingDocument logical data type is created.

3 The instance is populated with data from the client.

4 A post operation is applied to the AccountingDocument object. The COMclient sends the populated value to the Broker remote object server, whichcalls the post operation in the various components.

5 The result of the posting is returned to the client.

Submission of reports by e-mail

Expense reports can be submitted using e-mail messages, which are queued andprocessed by Baan OpenWorld Broker.

This scenario is similar to the online case, except that the population of the objectinstance derives from an arriving message, not from the Broker's COM client.

The following steps describe the process to submit reports by e-mail:

1 A user sends an asynchronous message to the Broker, for example throughe-mail or MSMQ.

2 The message is picked up by a Broker message source object, and is thentranslated and put into a message queue in the repository.

3 A message handler scans the queue. The message is retrieved and processed.As a part of this processing, a fresh instance of an ExpenseReport logical datatype is created and populated with data.

4 A post-operation is applied on the ExpenseReport object. The Broker callsthe post operation in the various components.

5 Optionally, a result message is sent back to the client.



Event notification by e-mail

A message is sent to the Broker notifying that, for example, a customer has beenclosed for business.

This scenario is similar to the offline operation invocation. The logical data typethat is used to process the data can represent an event, for example,CustomerClosed, or one of the business objects, for example, Customer.

After the incoming message is processed, a fresh instance of this logical datatype is created and populated with data. A notification operation, which can beany of the user-defined operations on the object, is applied. Multiple componentscan participate in this operation to implement their response to the event.

ComponentsBefore you can define the relationships between the logical data types and theexternal applications, you must define the component objects. A component is anobject in the repository that describes an external application, for example,BaanFrontOffice or CODA-Financials.

If you want to interact directly with a component, you will usually need a logonscript for the component. In this logon script, you can store relevant informationabout the connection in a Session variable. The Session variable is passed to anycomponent-specific operations, such as Load and GetTimestamp. For moreinformation and examples, see �Component� in Chapter 20, �Object typereference.�

Session

The connection with a component, the period between log on and log off, iscalled a session. A component can have multiple sessions runningsimultaneously.



Code mappingPurposeThe code mapping table translates codes (primary keys) between components.For example, the same customer can have the code JS in BaanERP, JSMITH inBaanFrontOffice, and 00.100.JSMITH in CODA-Financials. The code mappingtable lets the Broker know that each of these codes pertain to one and the samecustomer.

If the component integration subsystem updates objects to the participatingcomponents, the subsystem uses the code mapping service to find the local codesof the object.

If the component integration subsystem stores a new object in a component, thecomponent is expected to inform the Broker of the code that the componentassigns to the object. This new code is automatically stored in the code mappingtable. If an object is deleted, the code mapping table is also updated.

The code mapping service is also available to external applications through theIBaanCodeMapper COM interface. This feature is described in Chapter 19,�COM interfaces.�

Structure of the mapping tableThe code mapping table has the following columns:

Columns of the code mapping tableName Type DescriptionObjguid String The globally-unique identifier (GUID) of the object.Component String The identification of the component.Subsystem String The identification of the subsystem within the

component that stores this object, for example, atable.

Code String The code of the object as defined in the component.



To give an impression of a code mapping table, a part of a hypothetical codemapping table is shown here. This section of the code mapping table containsinformation about two different objects, which are stored in three differentcomponents.

Example code mapping tableGUID Component Subsystem Code{FCA1116E-1D99� BAANERP TCIBD010 JS{FCA1116E-1D99� BFO CUST JSMITH{FCA1116E-1D99� CODA-FIN A 00.100.JSMITH{FCA13174-1D99� BAANERP TDSLS010 TJ{FCA13174-1D99� BFO CUST TJOHNSON�

GUIDEvery instance of a logical data type automatically receives a system-generatedglobally unique identifier (GUID). The GUID can be used as a component-neutral identifier and a source for mapping into component-specific codes.GUIDs are defined and standardized in the X-Open Distributed ComputingEnvironment (DCE) specifications. A GUID is a 32-byte code that is guaranteedto be unique across the universe.

A GUID is only associated with an object if the object was originally stored bymeans of the synchronize or storeNew operation. These operations are describedin the section �Logical data types and components,� later in this chapter. Theseoperations automatically update the code mapping table.



OperationsThe code mapping table has a number of operations that you can access bymeans of the scripting language. The following table shows these operations.

Integration-specific operations of types and valuesOperation Descriptionadd Creates a new row in the code mapping table.

The following conditions are checked:For each combination of component and subsystem, every codemust be unique.Every object (GUID) can occur only once in every component.

map Returns the code in the target component. The input parameterscan be the object's code in another component or the object'sGUID.

modify Modifies an object's code in a component.remove Removes one row (the object code in a particular component) or

all rows that pertain to a specific object.

For more information, see the description of the CodeMap object in thedocument Scripting Language Reference (U7278D US).

You must be careful if you modify the code mapping table directly. Theoperation of the component integration subsystem depends heavily on theintegrity of the code mapping table.

If the Subsystem field in a logical data type definition is left blank for a specificcomponent, no code mapping is performed for that component.

Technical detailsThe code mapping table is stored in a relational database and manipulatedthrough a database connector object defined in the object repository. AnyODBC-compliant database is supported.

The code map table is created automatically, as long as there is a databaseconnector object called \sys\codes\CodeMapData that specifies a valid ODBCsource. In \predef\system, two types, CodeMapRowType andCodeMapTableType, specify the attributes of the code map table.

For more information, refer to the section �Database connectors� in Chapter 20,�Object type reference.�

For the COM interface to the code mapping table, refer to the section�IbaanCodeMap� in Chapter 19, �COM interfaces.�

NOTE

NOTE



Logical data types and componentsLogical data types describe the nature and structure of data independent of thephysical form of the data. To do any actual processing, an instance of this logicaldata type must be created and stored somewhere. In simple situations, a logicaldata type can be stored in a single database table or in a text file. In morecomplex situations, the data is stored in multiple external applications, calledcomponents. These components can participate in the logical data type. In thiscase, you must create scripts to define the implementations for operations suchas:

� To load a logical data type instance into the Broker.� To store the instance back in the external applications.� To permanently delete the instance.

You must create these scripts for each component that participates in the logicaldata type.

This works as follows. A logical data type has a number of primitive operations,such as Construct, Load, Store, and StoreNew. For each participating component,you can provide scripts that implement these primitive operations, as ilustrated inthe following example:

A Finance application and a Sales application participate in the Customerslogical data type. The Customers type contains information about the totalamount owed by the customer and the current credit limit. In the Customerslogical data type, you create a Store script for the Finance application that sendsrelevant data, for example, Amount owed, to the Finance application. AnotherStore script sends relevant data, for example, Current credit limit, to the Salesapplication.

You cannot invoke these component-specific operations directly. In the scriptinglanguage, you can call higher-level operations on logical data types, for example,synchronize. These operations activate the component integration subsystem,which invokes the appropriate primitive operations for each component.

Type-specific operations

Components can also participate in logical data type's high-level, user-definedoperations, such as Post, Approve, Query, and so on. You must define theimplementation of each component�s participation in these operations.

NOTE



Integration operations of types and valuesThe component integration subsystem has a number of operations on logical datatypes and values that you can invoke to achieve some integration function. Theseoperations can be initiated from within the Broker, for example:

� A synchronization process that is activated by a periodic process.� A synchronization process that is started through a menu command in a

Broker client.

The user can also initiate these operations through an external application thatcommunicates with the Broker by means of the Broker's COM interfaces or bymeans of a messaging system. For more information, see Chapter 19, �COMinterfaces,� and Chapter 8, �Messages.�

The following table lists the available operations for data integration on logicaldata types and values.

Integration operationsClass Operation DescriptionType load Loads a particular object instance, identified by code,

from all participating components.This operation uses the Construct, GetTimestamp,and Load primitive operations.

Type synchronize The user can call this operation to notify the Brokerthat an object was inserted or modified in acomponent.The Broker first loads data from all components, andthen stores the resulting compound object in allparticipating components.

Type delete Removes an object instance from all participatingcomponents.

Type map Looks up a component-specific code (primary key) ofan object in the code mapping table.

Row new Returns a freshly created, empty instance of thelogical data type.

Row store Updates the object in all participating components, byinvoking the Store primitive for each component.

Row storeNew Inserts a new object in all participating components byinvoking the StoreNew primitive for each component.

queryGUID Returns the Globally Unique Identifier (GUID)associated with the object instance.



In the scripting language, these operations are defined for the Type and Rowclasses. For details about these operations, refer to the Scripting LanguageReference (U7278D US).

You can use the operations of the Type class on logical data types. You can alsouse the operations of the Row class on variables of row types. For example:

{

// Create a variable to store instances of CustomerType

\types\CustomerType cust;

// (The load operation is an operation on a type).

cust = \types\CustomerType . load ("BAANERP", "012");

// Change the address

cust . Address = "100 Seaview Drive";

// Store the updated record in all

// participating components

// (The store operation is an operation on a row).

cust . store ();

}

SynchronizationThe synchronization operation is used if an object is inserted or modified in oneof the components. This component is called the originating component.

In general, the process to perform a synchronization operation consists of thefollowing steps:

1 Constructs an empty instance of the logical data type.

2 Optionally retrieves a time stamp for the instance from each component.Time stamps are explained later in this chapter.

3 Loads any existing data from the other components into this instance.

4 Loads the new data from the originating component.

5 Checks the code mapping table to see if the object already exists.

6 Updates the resulting object into the other components by using the Storeprimitive operation. If the object is new, the operation uses the StoreNewprimitive operation to insert the object into the other components.

7 Updates the code mapping table if the object was new.



Flags

Usually, the Broker assumes that the originating component already contains anup-to-date version of the object. The Broker will not store the object in theoriginating component, unless you specify the SYNC_STORE_ALL flag.

If you are certain that the object is new, you can specify theSYNC_ALWAYS_NEW flag to improve system performance. In that case,Broker uses the StoreNew operation without checking the code mapping table.

Time stamp order

You can use the time-stamp function to influence the order in which thecomponents are accessed for loading existing data. For more information, refer tothe section �Time stamp order� later in this chapter.

Two-phase commit and rollback

You can use operations such as PrepareStore and RollbackStore to ensure theconsistency of compound transactions. For more information, refer to thesections �Two-phase commit protocol� and �Rollback� later in this chapter.

For more details and examples, refer to the document Scripting LanguageReference (U7278D US).

Time stamp orderIf the same information is stored in more than one application, you can decide tomake one of the applications leading, and synchronize the other applicationsfrom this originating component. However, sometimes you prefer to usewhatever information is most recent.

Two components store address information. You want to synchronize the addresses basedon the most recent information.

In that case, you can use the time stamps of the address records to determinewhich is the most recent.

To achieve loading and synchronizing in time-stamp order, take the followingsteps:

1 Open the editor for the logical data type.

2 Create a script to implement the GetTimestamp primitive operation for eachcomponent.

3 Select the Load Data in Time Stamp Order check box.

EXAMPLE



The GetTimestamp primitive is called for each participating component beforeretrieving a previously stored instance. The Broker loads the oldest data first, andthe newest data is last. However, for the synchronize operation, the data from theoriginating component is always loaded last.

The following example provides a sample loading cycle:

Data is loaded from components A, B, and C.

Time-stamp ordering is active.

The following steps make up the loading cycle:

1 The component integration subsystem calls the Construct operation for A.2 The Construct operation is called for B.3 The Construct operation is called for C.4 The GetTimestamp operation is called for A, which returns February 10,

2000.5 The GetTimestamp operation is called for B, which returns March 1, 2000.6 The GetTimestamp operation is called for C, which returns January 8, 2000.7 The Load operation is called for C, because C had the earliest timestamp.8 The Load operation is called for A, which had the second earliest timestamp.9 The Load operation is called for B, which had the latest timestamp.

If you do no require timestamp loading, you can leave this primitiveunimplemented.

Two-phase commit protocolA two-phase commit protocol helps to ensure the consistency of compoundtransactions. If you decide to use the two-phase commit protocol, the Brokercalls the PrepareStore primitive operation for each participating componentbefore calling the first Store primitive. You must provide an implementation forthe PrepareStore primitive that performs the following tasks:

� Request the component to prepare for the Store operation.

� Check the data or the condition of the component on errors. For example, youcan check whether a certain Number field is not zero, and you can checkwhether the component is ready to receive data.

� If an error is found, the PrepareStore primitive must throw an exception.

If an exception is thrown in the PrepareStore operation, the following happens:

� The Broker stops calling PrepareStore and Store.� The store or synchronize operation that initiated the store cycle returns with

the exception.



The PrepareStoreNew and PrepareDelete operations are called before theStoreNew and Delete operations. These operations work in the same way as thePrepareStore operation.

To apply a two-phase commit protocol, take the following steps:


2 Create a script to implement the PrepareStore, PrepareStoreNew, andPrepareDelete primitive operations for each component.

3 Select the Store Data using a Two-Phase Protocol check box.

The following example shows an implementation of the PrepareStore primitiveoperation.

The component has a prepareTransaction method to prepare for varioustransactions. The method returns a negative value if an error occurs.

The Code variable contains the local code of the object. The second parameterindicates the type of transaction.

{

Exception e;

if ( Session.Interface.prepareTransaction (Code,

"UPDATE")< 0 ) {

e . code = Session.Interface.lastErrorCode;

e . reason = Session.Interface.lastErrorReason;

e . description = Session.Interface.lastErrorDescr;

// The store operation will be aborted.

throw e;

}

}

EXAMPLE



RollbackIf an exception is thrown in the Store primitive in any component, the Brokerwill optionally call the RollbackStore primitive for any component that haspreviously completed its Store primitive successfully. Typically, RollbackStoreundoes or reverses any changes made in the Store primitive.

Similarly, the RollbackStoreNew and RollbackDelete operations are called if anexception is thrown in the StoreNew or Delete operations.

To enable rollback, take the following steps:


2 Create a script to implement the RollbackStore, RollbackStoreNew, andRollbackDelete primitive operation for each component.

3 Select the Invoke Rollback if Errors occur when storing Data check box.



Primitive operationsThe component integration subsystem calls the Primitive operations to achievedirect interaction with external applications. If required, you must define therelevant script in the type editor to provide implementations for these operationsfor each component. The following table presents an overview of theseoperations.

Primitive operationsOperation DescriptionConstruct The Construct primitive is called for each participating

component whenever a fresh instance of the type iscreated. The component can initialize any information inprivate or public data members.

GetTimestamp If time-stamp ordering is requested, the GetTimestampprimitive is called for each participating component beforeretrieving a previously stored instance. The component isexpected to return the time and date when thecomponent�s instance was last updated. (More details areprovided later in this section).

Load The Load primitive is called for each participatingcomponent if the Broker must retrieve a previously storedinstance.

Store The Store primitive is called for each participatingcomponent if the Broker must save (update) a previouslycreated instance.

StoreNew The StoreNew primitive is called for each participatingcomponent if the Broker must create (insert) a freshinstance.If you assign a string value to the Code variable, the codemapping table is updated with information about thisinstance. (More details are provided later in this section).

Delete The Delete primitive is called for each participatingcomponent if you invoke the delete operation of the logicaldata type.

PrepareStore,PrepareStoreNew,PrepareDelete

These primitives are used if you apply a two-phase commitprotocol, as explained in the section on two-phase commitprotocol, earlier in this chapter.

RollbackStore,RollbackStoreNew,RollbackDelete

If an exception is thrown in the Store primitive in anycomponent, the Broker will optionally call theRollbackStore primitive for any component that hassuccessfully previously completed a Store primitive. TheRollbackStoreNew and RollbackDelete primitives servesimilar purposes.This concept is explained in the section on rollback, earlierin this chapter.

Note that the printf function does not work in a primitive operationimplementation, because the primitive scripts run on the server.



Variables and parametersThe following variables are visible in all primitive operations:

� Session: Holds data about the logon session to the component.� GUID: The object's globally unique identifier.

The Code variable holds the code by which the object is known in a particularcomponent. In most of the primitive operations, this variable is available as anincoming variable. In other words, you can use the value of the Code variable inyour implementation.

StoreNew

In the StoreNew operation, the Code variable is an outgoing parameter. Thecomponent is expected to return the code that is chosen for the new object. Youmust assign this code as a string value to the Code variable. The code mappingtable is updated with this information. If you leave the Code variable as anempty string, no new record is inserted in the code mapping table. You can usethis to control the size of the code mapping table, and to avoid crowding the tablewith unnecessary relations.

In the RollbackStoreNew operation, the Code variable is an incoming variable.

GetTimestamp

In the GetTimestamp operation, the Timestamp variable is an outgoing variable.The component is expected to return the time stamp of its instance in thisvariable. You must assign this value as a Time value to the Timestamp variable.

The GetTimestamp primitive is called for each participating component beforeretrieving a previously stored instance. If time stamp loading is not needed, thisprimitive can be left unimplemented.

Examples of primitive operation implementationsThis section provides several example implementations of primitive operations.

For example, suppose you define two components: Conf and EMail.

Component Conf contains a list of participants of a conference. The participantsare registered in a table with the following String fields:

� ParticipantNumber.� Name.� Category.� EmailAddress.



You use an OleObject object to connect to Conf's COM interface. You entered\predef\system\OleObject in the component's Session type field.

You must use the following script in the logon script field of the componentobject to make the connection:

OleObject obj ("Conf.Participant");

Session = obj;

Now, you can access the methods and properties of the participants table asfollows:

Session . method(); // Calls method() on the instance

Session . property = "ABC"; // Sets the property

String str = String (Session . property); // Retrieves the

property

Component EMail contains a directory of e-mail addresses. EMail is actually asimple database that is created in a ODBC-compliant database managementsystem. The e-mail addresses are stored in a table with the following Stringfields:

� ID.� Name.� EmailAddress.

You have defined the following objects in the repository:

� \email\EmailRow.� \email\EmailTable.� \email\EmailFile.

EMailRow is a logical data type with the three fields of the EMail table.EMailTable is a table of EMailRow. The EMailFile file object is based on theEMailTable table type. This file object enables you to access the data.

You defined the PersonRow row type to represent a participant of theconference. Both Conf and EMail participate in this logical data type.PersonRow has the following String fields:

� Name.� Category.� EmailAddress.� strConfCode.� strEMailCode.

The following examples show possible implementations for the Load, Store, andDelete operations.



The Code variable contains the local code of the object. The system retrieves thiscode from the code mapping table.

The Session variable stores a pointer to the component's COM interface.

Load (Conf)

The implementation of Conf's Load primitive operation:

{

try {

if (Code == "")

return; // Nothing to load if we don't have a code

// Session refers to the COM interface

if (Number (Session.OpenParticipant (Code .

asNumber)) != 0) {

strConfCode = Code;

Name = String (Session . Name );

Category = String (Session . Category);

EMailAddress = String (Session . EMailAddress);

}

}


printf ("Exception when loading PersonRow code

= %i, reason = %s", e.code, e.reason);

}

}

Load (EMail)

The implementation of EMail's Load primitive operation:

{

strEMailCode = Code;

\email\EMailRow emrow;

emrow = \email\EMailFile . find (ID == Code);

Name = emrow . Name;

EMailAddress = emrow . EMailAddress;

}



Store (Conf)

The implementation of Conf's Store primitive operation:

{

try {

if (Code == "")

return;

Session . ParticipantNumber = Code.asNumber;

if (Name . length() > 0)

Session . Name = Name;

if (Category . length() > 0)

Session . Category = Category;

if (EMailAddress . length() > 0)

Session . EMailAddress = EMailAddress;

if (!Number (Session . Update()))

printf ("Error in Conf Store");

}


printf ("Exception when storing Conf participant");

}

}

Delete

The implementation of Conf's Delete primitive operation:

{

try {

if (Code == "")

return;

Session.EraseRecord(Code);

}


printf ("Exception when deleting = %i, reason = %s",

e.code, e.reason);

}

}



IteratorsIterators are used for fast bulk synchronization of data between a singleoriginating component and multiple destination components. Iterators are usuallyapplied in batch processes that run at regular intervals to synchronize the databetween applications (components).

The synchronize operation on a logical data type runs load and store operationson a record-by-record basis. The synchronize operation of an iterator gives youmore flexibility and potentially a better performance. For an example, see the�Synchronization in a batch process� case in the �Example cases� section, earlierin this chapter.

For more information, refer to �Iterators� in Chapter 20, �Object type reference.�

Communication mechanismsYou can apply several different communication mechanisms, synchronous aswell as asynchronous. These mechanisms are described in other chapters.

COM Automation

For information on the use of Microsoft COM Automation objects, refer to thedescription of the OleObject class in the Scripting Language Reference(U7278D US).

BaanERP BOIs

If you use the Baan OpenWorld Enterprise Connector wrappers, you can accessBaanERP Business Object Interfaces (BOIs) as OleObjects,.

Messaging

For information on the use of the Broker's messaging system, see Chapter 8,�Messages.� Protocols such as POP3 and SMTP are supported.

Internet

The Internet protocol http is available through the Baan OpenWorld Broker'sInternet object. For more information, refer to the �Internet object� section in thedocument Scripting Language Reference (U7278D US).



Direct database access

You can obtain direct access to tables in ODBC-compliant databases by means ofDatabase connector objects and File objects. For more information, refer to�Database connector� and �File� in Chapter 20, �Object type reference.�

DLL proxies

For information on access to DLLs on your client PC, refer to �DLL proxy� inChapter 20, �Object type reference.�

COM Interfaces

For information on the use of the Broker's COM interfaces by externalapplications, see Chapter 19, �COM interfaces.�

Component integration subsystem � COMinterfacesThis section defines a series of COM Interfaces that Baan OpenWorld Brokersupports and uses in the component integration subsystem. By implementingCOM objects that support the COM interfaces, Baan component owners, such asSCS, FOS, and other BaanSeries products, as well as Baan partners andcustomers, can write fast, low-level implementation of the functions that arerequired to plug in to Broker.

Three COM Interfaces, which are described in the following section, are used inthe Component Subsystem: one for Types, one for Components, and one forIterators. By implementing these COM Interfaces, Baan component owners, whouse Baan Openworld Broker to integrate into BaanSeries, can use moduleswritten in other programming languages to implement the necessary primitiveoperations instead of writing them in the OWB scripting language.

Using these COM Interfaces, you can reuse executing code from applications orcreate new code to integrate with Baan OpenWorld Broker. Using otherprogramming environments, developers have more control over data access.Often, modules written in other languages are faster than the scripting language.To access the data is sometimes problematic, because no ODBC drivers areavailable for some databases, the database is a proprietary database and to accessthe data, some checks must be calculated, and so on. You can use COM objectsin the OWB scripting language in the CIS system, however, this process isslower than using �direct to the metal� COM in the core system.



Design overviewThe following three COM Interfaces are available for you to implement to usethe component integration subsystem of OWB:

� IBaanCISConnector: Describes the participation of a component in a Typefrom the OWB repository.

� IBaanCISComponent: Comparable to the Component class in the OWBrepository.

� IBaanCISIterator: Comparable to the Iterator class in the OWB repository.

These COM Interfaces are explained in detail in Chapter 3, �Repositorybrowser.�

Detailed information on the Component Integration Subsystem as whole, whichincludes descriptions of each primitive type, is provided in the �Baan DEIIntegration Technical Design.doc.�

Design approachDesign principles for the COM Interfaces on the component integrationsubsystem are as follows.

� You must be able to write the primitive operations in several programminglanguages, for example, all languages that support writing COM objects, suchas Visual Basic, Visual C++, Java, and Delphi.

� You can use any COM object that implements the IBaanCIS COM Interfacesin an appropriate way in the CIS part of OWB.

The COM Interfaces all support IsupportErrorInfo, therefore, if the execution ofa method fails, the COM Interface can be asked about the error, and returndetailed information about the failure. The returned HRESULT must have thecode 0x800403E7.

Return valuesThe methods use the IBaanValue interface pointers, such as the components data,session, and other variables, that uses OWB data types in CIS. The methods willreturn S_OK on success, 0x800403E7 when the primitive operation must returnfalse, and E_* error for other possible errors.



Init and close methodsThe init method is called each time a instance of current interface is created.Here the object can, for example, be connected to the database or anything elsethat must be done at the beginning of the process.

The close method is called each time the interface is released. The object can doall the clean up that is required before the interface is released.

IBaanCISConnector

Description

OWB enables the definition of data types, which are stored in the repositoryunder a path and a name.

OWB types are used to define high-level business objects, such as ExpenseReport, Customer, Invoice, and Insurance Claim. OWB then enables the user tospecify how various components contribute to the implementation of theseobjects, which is carried out in the following two ways:

� Using predefined primitive (technical) operations, such as Construct, Load,Store, and StoreNew

� Using high-level, user-defined business operations on the type, such as Post,Approve, Query, and so on.

Note that you can only use the COM classes to implement the primitiveoperations, not the user defined operations.

Class Properties� IBaanRepository* pBaanRep: A OWB repository object.� BSTR bstrPath: The full path to the associated type in the repository

Class Methods

The following items are the methods that are available on theIBaanCISConnector. The list shows method parameters and return values.

� Init:− [In] IBaanRepository* pBaanRep A OWBrepository object.− [In] BSTR bstrPath: The full path to the associated type in the repository



� Construct:− [In] IBaanValue* pSession. This is the session context.− [In Out] IBaanValue** ppData. The data that gives the component a

chance to participate in the construction of a new value of this type. Aninstance of the type is passed as a parameter. The component can modifythis instance at will.

� GetTimestamp:− [In] IBaanValue* pSession is the session context.− [In] BSTR bstrCode component�s own identifier of the instance to get the

timestamp for.− [In] IBaanValue* pData is an instance of the component�s data.− [In Out] DATE* pTimestamp is the timestamp of an instance.

� Load:− [In] IBaanValue* pSession is the session context.− [In] Code is the component�s own identifier of the instance that must be

loaded.− [In Out] IBaanValue** ppData is an instance of the component�s data.

� PrepareStore:− [In] IBaanValue* pSession is the session context.− [In] IBaanValue* pData is an instance of the components data to store.

� Store:− [In] IBaanValue* pSession is the session context.− [In] BSTR bstrCode is the component�s own identifier of the instance.− [In] IBaanValue* pData is an instance of the component�s data to store.

� RollbackStore:− [In] IBaanValue* pSession is the session context.− [In] BSTR bstrCode is the component�s own identifier of the instance.− [In] IBaanValue* pData is an instance of the component�s data to store.

� PrepareStoreNew:− [In] IBaanValue* pSession is the session context.− [In] IBaanValue* pData is an instance of the component�s data to store.

� StoreNew:− [In] IBaanValue* pSession is the session context.− [In Out] BSTR bstrCode is the local code of the component− [In] IBaanValue* pData is an instance of the component�s data to store.



� RollbackStoreNew:− [In] IBaanValue* pSession is the session context.− [In] BSTR bstrCode is the component�s own identifier of the instance.− [In] IBaanValue* pData is an instance of the component�s data to store.

� PrepareDelete:− [In] IBaanValue* pSession is the session context.− [In] IBaanValue* pData is an instance of the component�s data.

� Delete:− [In] IBaanValue* pSession is the session context.− [In] BSTR bstrCode is the component�s own identifier of the instance.− [In] IBaanValue* pData is an instance of the component�s data.

� RollbackDelete:− [In] IBaanValue* pSession is the session context.− [In] BSTR bstrCode is the component�s own identifier of the instance.− [In] IBaanValue* pData is an instance of the component�s data.

� Close:

User Interface

Figure 3 Type Editor � Component.



For each component, you can assign a COM CLSID or PROGID. This COMclass is only used for this particular component

IBaanCISComponent

Description

Components are objects in the OWB repository that describe externalapplications. Two primitive operations are available, which enable you to:

� Log on to the component, for example, to establish a session.� Log out from the component, for example, to close a session.

You must be able to write these operations as COM classes, rather then use ascripting language implementation.

Class Methods

The session is of type IBaanValue.

� Init:− [In] IBaanRepository* pBaanRep A OWBrepository object.− [In] BSTR bstrPath is the full path to the associated type in the repository.

� Login:− [In] IBaanValue** ppSession is the session context.− [In] BSTR bstrConnectionString String to use when log on to various

component instances.

� Logout:− [In] IBaanValue* pSession is the session context.

� Close:



User Interface

Figure 4 Component dialog box, Attributes tab.

One of the component attributes is an edit field to enter a COM CLSID orPROGID. If you call the login operation for this particular component, aninstance of this COM class is created, with CoCreateInstance. This coclass mustimplement the IBaanCISComponent interface. The interface�s Login method isthen called, which returns an IBaanValue interface pointer that denotes thesession.



IBaanCISIterator

Description

OWB Iterators have the following two main phases:

� An initialization phase that initializes the iterator state variable, which is thenpassed to the iteration phase.

� An iteration phase, which iterates (loops) through data and does whatevermust be done to map the loaded data into the iterator�s row type. Finally,OWB stores the resulting row into the participating components.

You must be able to write these operations as COM class instead of invokingOWBscripts.

Class Methods

All the parameters are of type IBaanValue.

� Init:− [In] IBaanRepository* pBaanRep An OWB repository object.− [In] BSTR bstrPath The full path to the associated type in the repository.

� Initialization:− [In] IBaanValue** ppSession is the session context.− [In] IBaanValue* pIteratorParam is an optional parameter that can be

passed to the run and synchronize methods.− [In Out] IBaanValue** ppIteratorState is the iterator state that is passed to

the iteration phase.

� Iteration:− [In] IBaanValue** ppSession is the session context.− [In Out] IBaanValue** ppIteratorState the state of the iterator coming

from the initialization.− [In Out] IBaanValue** ppIteratorResult is the result value of each

iteration.− [In Out] BSTR* pbstrCode is the components identifier of the instance.

� Finish.

� Close.



User Interface

Figure 5. Iterator Properties dialog box, Attributes tab

One of the iterator� attributes is an edit field to enter COM CLSID or PROGID(see Figure 5). If you call the initialization and the iteration for this particulariterator, you can use this COM Interface.

IDL listing// COMIntfOnCIS.idl : IDL source for COMIntfOnCIS.DLL

//

// This file will be processed by the MIDL tool to

// produce the type library (COMIntfOnCIS.tlb) and

marshalling code.

import "oaidl.idl";



import "ocidl.idl";

import .”.\bsrvitf\bsrvitf.idl";

[

object,

uuid(D4BD5625-718F-11D3-A23D-00105A6B6AD6),

dual,

helpstring("IBaanCISConnector Interface"),

pointer_default(unique)

]

interface IBaanCISConnector : IDispatch

{

[id(1), helpstring("method Init")]

HRESULT Init (

[in] IBaanRepository* pBaanRep,

[in] BSTR bstrPath);

[id(2), helpstring("method Construct")]

HRESULT Construct (

[in] IBaanValue* pSession,

[in, out] IBaanValue** ppData);

[id(3), helpstring("method GetTimestamp")]

HRESULT GetTimestamp (


[in] BSTR bstrCode,

[in] IBaanValue* pData,

[in, out] DATE* pTimestamp);

[id(4), helpstring("method Load")]

HRESULT Load(


[in] BSTR bstrCode,

[in, out] IBaanValue** ppData);

[id(5), helpstring("method PrepareStore")]

HRESULT PrepareStore(


[in] IBaanValue* pData);

[id(6), helpstring("method Store")]

HRESULT Store(




[in] BSTR bstrCode,

[in] IBaanValue* pData );

[id(7), helpstring("method RollbackStore")]

HRESULT RollbackStore(


[in] BSTR bstrCode,


[id(8), helpstring("method PrepareStoreNew")]

HRESULT PrepareStoreNew(



[id(9), helpstring("method StoreNew")]

HRESULT StoreNew(


[in, out] BSTR* pbstrCode,


[id(10), helpstring("method RollbackStoreNew")]

HRESULT RollbackStoreNew(


[in] BSTR bstrCode,


[id(11), helpstring("method PrepareDelete")]

HRESULT PrepareDelete(



[id(12), helpstring("method Delete")]

HRESULT Delete(


[in] BSTR bstrCode,

[in] IBaanValue* pData );

[id(13), helpstring("method RollbackDelete")]

HRESULT RollbackDelete(


[in] BSTR bstrCode,




[id(14), helpstring("method Close")]

HRESULT Close();

};

[

object,


dual,

helpstring("IBaanCISComponent Interface"),


]

interface IBaanCISComponent : IDispatch

{


HRESULT Init (



[id(2), helpstring("method Login")]

HRESULT Login(

[in, out] IBaanValue** ppSession,

[in] BSTR

bstrConnectionString);

[id(3), helpstring("method Logout")]

HRESULT Logout(

[in] IBaanValue* pSession);


HRESULT Close();

};

[

object,

uuid(D4BD562B-718F-11D3-A23D-00105A6B6AD6),

dual,

helpstring("IBaanCISIterator Interface"),


]

interface IBaanCISIterator : IDispatch

{




HRESULT Init (



[id(2), helpstring("method Initialize")]

HRESULT Initialize(


[in] IBaanValue* pIteratorParam,

[in, out] IBaanValue** ppIteratorState);

[id(3), helpstring("method Iterate")]

HRESULT Iterate(


[in, out] IBaanValue** ppIteratorState,

[in, out] IBaanValue** ppIteratorResult,

[in, out] BSTR* pbstrCode);

[id(4), helpstring("method Finish")]

HRESULT Finish(


[in, out] IBaanValue** ppIteratorState);


HRESULT Close();

};

[

uuid(B91A3689-718E-11D3-A23D-00105A6B6AD6),

version(1.0),

helpstring("COMIntfOnCIS 1.0 Type Library")

]

library COMINTFONCISLib

{

importlib("stdole32.tlb");


[


helpstring("BaanCISConnector Class")

]

coclass BaanCISConnector

{

[default] interface IBaanCISConnector;

};



[


helpstring("BaanCISComponent Class")

]

coclass BaanCISComponent

{

[default] interface IBaanCISComponent;

};

[

uuid(D4BD562C-718F-11D3-A23D-00105A6B6AD6),

helpstring("BaanCISIterator Class")

]

coclass BaanCISIterator

{

[default] interface IBaanCISIterator;

};

};

Component instancesDesign overviewThe descriptive details of the component instances must be stored in a databasetable. The connection to this database is configured through the ODBCDatasource connector in the Broker repository. (\sys\databases\CIS.) Anadditional table, the control table, holds data that indicates whether or not acomponent instance participates in synchronization for a type (Business Object).This table is an exclusion table, therefore, all component instances aresynchronized, unless the tables are added to the exclusion table.

Two enhancements to the user interface facilitate the easy management ofcomponent instances. In the component editor, you can add instances, and alteror remove their details altogether. In the type editor, the user is presented with alist of all instances configured for a particular component, and can synchronizeor exclude each instance independently.



Design approachThe following list provides several design principles for these enhancements:

� To enable the user to easily configure multiple instances of a component,which differ by geographical location and connection string.

� To synchronize all instances by default, but enable the user to exclude eachindividually. New instances of components must be automaticallysynchronized.

Component editor enhancement

Description

Components are objects in the OpenWorld Broker repository that describeexternal applications. To edit a component in the object repository, theComponent Editor is invoked. You must set the unique code on the Attributestab, because the component instances are referenced by this code. If you enablecomponent instancing on the Instances tab, you cannot alter the unique codeafter the code is set.

After you open the Instances tab, the instance database table is queried for allinstances that correspond to the component being edited. The location,description and connection strings, as well as the geographical coordinates aredisplayed. The user can create new instances of the component, edit existinginstance entries, and delete instances. For each new instance added, a GUID isgenerated to uniquely identify the instance, although the end user has no accessto the GUID.

To optimize a single instance component, you can disable component instancingfor the component.



User Interface

A new tab is added to the component editor, as shown in Figure 6.

Figure 6. Component editor, Instances tab.

The user is presented with a list view of the instances currently configured for thecomponent. The check-box is used to enable or disable component instancing. Todisable component instancing means that no database query is performed for thecomponent, which slightly speeds the synchronization process.



You can use the Add, Edit, and Remove buttons to define, alter, or remove newor existing instances. If you click either the Add or Edit buttons, theParticipating Instance dialog box starts (see Figure 7).

Figure 7 Instance editor dialog.

After you add or edit instances, you can select a site name from currentlyconfigured sites, and enter the connection string appropriate for connection tothat particular component instance.

Type Editor enhancement

Description

OpenWorld Broker enables you to define data types, which are stored in therepository under a path and a name. Types are used to define high-level businessobjects, such as Expense Report, Customer, Invoice, and Insurance Claim.OpenWorld Broker then enables the user to specify how various componentscontribute to the implementation of these objects. The type editor enables theuser to add participating components to the type. If you select a component in thetype editor, you are presented with a list of component instances defined in thecomponent editor. For more information, refer to �Introduction,� in Chapter 3,�Repository Browser�. By default, all instances are synchronized, but you canexclude any of the component instances from the integration. This exclusion iscarried out on a per-type basis, and an excluded component instance will remainsynchronized on all other types in which the component participates. If a newinstance is defined for a component, that instance will automatically besynchronized rather than excluded.



User Interface

An Instances tab is added to the component window of the type editor, as shownin Figure 8. Here, the user sees the list of component instances configured for theselected component.

Figure 8. The type editor

Each instance of the component appears with an icon to the left, which indicateswhether the component participates in, or is excluded from, the integration. Ifyou select an instance, you can select the Excluded option in the Site Statusbox, and enter a short comment as to why this particular instance is excludedfrom this type.



Run-time behavior

Type integration

The following list provides several facts related to type integration:

� Several integration-specific operations exist for types:

� The component integration subsystem�s run-time behaviour performsintegration over multiple instances of many components. If a participatingcomponent is included in a type, all instances of the component areautomatically included in the integration. The operations that can be calledfrom the scripting language are modified slightly to enable the originatingcomponent to specify the originating site name (instance).

� Value Type::load (String strComponent, String strCode [, StringstrSiteName, Number numFlags]).

� The strSiteName parameter indicates the instance of strComponent, whichhas the newest data, and therefore must be loaded last. The flag,LOAD_SINGLE, tells the subsystem to perform a load operation only on thecomponent specified. If the strSiteName is given, the load is performed onthat instance only, otherwise all instances of the specified component areloaded from.

� BOOL Type::synchronize (String strComponent, String strCode [, StringstrSiteName, Number numFlags]).

� The strSiteName parameter indicates the site name that originates thesynchronization, if component instancing is enabled on the component. Theoptional numFlags parameter contains the flag bits SYNC_STORE_ALL andSYNC_ALWAYS_NEW. If instances are enabled on the originatingcomponent, the SYNC_STORE_ALL flag indicates that the updatedinformation must be stored into all the component�s instances, including theoriginating instance.

� BOOL Type::delete (String strComponent, String strCode [, StringstrSiteName, Number numFlags]).

� The delete operation also takes the extra parameter, strSiteName, to indicatethe originating instance of the originating component.

� All other operations accessible through the scripting language are called asdescribed in the document Component Integration Subsystem.



� Primitive operations.

In all primitive operations defined in a type, the Connection parameter isvisible in the script. During run-time, this parameter is read from thecomponent�s instance setup, and the primitive is applied to each instance ofthe component.

Iterator

The iterator wizard enables the user to specify which instance of the originatingcomponent originates the iteration (see Figure 9). A combo-box lists theavailable sites on the database. If the selected component does not havecomponent instancing enabled, the list is disabled. The selected site name is thenstored with the iterator, and passed to the synchronise operation at run-time.

Figure 9 Iterator wizard, Component window

IActiveScriptingThis following section describes new features that are added to the BaanOpenWorld Broker to support Microsoft IactiveScripting, rather than the built-inscripting language used in the OpenWorld Broker.

Design principles for the IActiveScripting support in the Component IntegrationSubsystem are as follows:

� You cannot mix OpenWorld Broker scripts and IActiveScripting scripts in aspecific object.



� Some components use Intergrations Server scripts to implement primitivetype operations, while other components use IActiveScripting.

� Broker objects that are exposed as COM objects are the parameters that arecurrently available to OpenWorld Broker scripts. Parameters such as Code,GUID, and Result are all available as COM objects, but no other C++ objects,for example, System or Environment.

� Baan OpenWorld IS - COM Client can be used to gain access to other objectsstored in the repository.

� All parse-able scripting engines must be supported, including VBScript andJavaScript.

Scripts are stored in an external file. In this case, all operations for the object inquestion are stored in the same script file.

Components

Components are objects in the BIS repository that describe external applications.Two primitive operations are available:

� An operation to log on to the component, in other words, to establish asession.

� An operation to log out from the component, in other words, to close asession.

You can implement these operations in IActiveScripting.

Exposed Objects

Exposed Broker objects to the Login operation are:

Name Description[In]Session IBaanValue instance representing the Component

Session value.[In]strConnectionString BSTR string containing the connection string, if any,

for this component

In VBScript, this operation is assumed to be implemented in the following way:

Public Function Login (Session, strConnectionString)

The return value is the success of login to the component.



Exposed Broker objects to the Logout operation are:

Name Description[In]Session IBaanValue instance representing the Component Session value.

In VBScript, this operation is assumed to be implemented like this:

Public Sub Logout (Session)

User Interface

Several changes are made to the user interface. When users first createComponent, the users are prompted with a utility, where they are, for example,asked to select which scripting language must be used. If users reinvoke theeditor for Component, the editor appears as a tabbed dialog, which enables usersto more easily jump to the script pages. However, users cannot change betweenscripting languages after they created the object. To change between scriptinglanguage after the obejct is created, users must recreate the object.

Iterators

Baan OpenWorld IS Iterators have the following three main phases:

� An initialization phase that initializes the iterator state variable, which is thenpassed to the iteration phase.

� An iteration phase, which iterates (loops) through data and performs therequired tasks to map the loaded data into the iterator�s row type. Finally,Baan OpenWorld IS stores the resulting row into the destination components.

� A finish phase that frees any object that was previously created in theinitialize phase, as well as commiting outstanding transactions.

You can implement these operations in IActiveScripting.



Exposed Objects

Exposed Broker objects to the Initialization operation are:

Name Description[In]Session IBaanValue instance that represents the Component Session

value. Only visible if an originating component is selected.[In]Parameter IBaanValue instance that represents the Iterator Parameter

value. Only visible if a non-Void parameter type is defined in theeditor.

[In]This IBaanValue instance that represents the Iterator State value.Only visible if a non-Void state type is defined in the editor.


Public Sub Initialize (Session, Parameters, This)

Exposed Broker objects to the Iteration operation are:

Name Description[In]Session IBaanValue instance that represents the Component Session

value. Only visible if an originating component is selected.[In]This IBaanValue instance that represents the Iterator State value.

Only visible if a non-Void state type is defined in the editor.[Out]Code IBaanValue instance used to return a unique identifier for the

object that is being loaded.


Public Function Iterate (Session, This, Code)

The return value of the Iterate function is the object that is iterated, for example,customer record or sales order. When the iteration is finished, the return valuemust be Nothing.

Exposed Broker objects to the Finish operation are:

Name DescriptionSession IBaanValue instance that represents the Component Session

value. Only visible if an originating component is selected.This IBaanValue instance that represents the Iterator State value.

Only visible if a non-Void state type is defined in the editor.


Public Sub Finish (Session, This)



User Interface

Several changes are made to the user interface. When users first create Iterators,the users are prompted with a utility in which the they can, for example, selectwhich scripting language must be used. If users reinvoke the editor for Iterators,the editor is displayed as a tabbed dialog to enable users to jump to the scriptpages more easily. However, users cannot change between scripting languagesafter they created the object. To change between languages after objects arecreated, users must recreate the object. For details about the Iterator object andthe objects properties, please refer to the Iterator specification.

On the first page, users enter the name and optional description for the object, asshown in the following figure (see Figure 10):

Figure 10. Iterator, Name dialog box



On the following page, users are asked to select the type of parameters, statevalues, and the result value for each iteration:

The following page is used to enter information about the originating component,which is the component from which that the data is read.



On next page, users select which scripting option to use:

The default option is native scripting, therefore, if IactiveScripting support isselected, the dialog will change to the following:

If users enter a valid file name in the Link to external file list, the script will beread from that file. If changes are made to the Iterator, this file is updated. On thedrop down list, users can select which script language to use. This list will reflectwhat is installed on the client�s computer.



If you select a ProgID support, the user interface changes to the following:

For details about the ProgID support, see the corresponding specification.

If users select the native scripting language, the following three pages are used toenter the scripts for the Initialize, Iterate, and the Finish step. These pages are notshown here. The page after the Finish step is the Option page.

If users select IactiveScripting, the next page is a multiline edit box to enterscripts:

At the moment, this edit box is a simple multiline edit box, with no features suchas syntax highlighting or advanced copy-and-paste functionality. After this page,the option page appears.



If you select a ProgID support , the following dialog box is the Logging page:

The Logging page is always the last page in the wizard.

When the editor is reinvoked, the editor appears as shown in the followingfigure.



VBScript example

' Iterator Object - Example Script

' Assuming that the This object has a OleObject

' member called comIter which has a Initialize (nMax)

' member and a Iterate member Our Parameters type has a

' nMax member we like to get warning on unknown objects

Option Explicit

Public Sub Initialize (Session, This, Parameters)

On Error Resume Next

'Assuming that we have a COM iterator object

set This.comIter = CreateObject ("Iterators.Customers")

This.comIter.Initialize ()

End Sub

Public Function Iterate (Session, This, Code)


if (This.comIter.Iterate () = true) then

set Iterate = This.comIter

' Assume that this object has unique Name member

' that can be used as Code.

Code = This.comIter.Name

else

set Iterate = Nothing

end if

End Function

Public Sub Finish (Session, This)


End Sub



Types

Description

Baan OpenWorld IS enables you to define data types, which are stored in therepository under a path and a name.

Baan OpenWorld IS types are used to define high-level business objects, such asExpense Report, Customer, Invoice, and Insurance Claim. Baan OpenWorld ISthen enables the user to specify how various components contribute to theimplementation of these objects, which is carried out in two ways:

� Using predefined primitive, �technical� operations, such as Construct, Load,Store, and StoreNew

� Using high-level user-defined business operations on the type, such as Post,Approve, Query, and so on.

You can only use the IactiveScript to implement the primitive operations, and notthe user-defined operations.

Exposed Objects

Current parameters, as used in primitive operations, are packed in a COM objectand made visible as an object named �Parameters.�

Exposed Broker objects to the Construct operation are:

Name Descriptionthis IbaanValue instance that represents the value that is being

constructed.Session IbaanValue instance that represents the Component Session

value.

Exposed Broker objects to the Load operation are:

Name Descriptionthis IbaanValue instance representing the value that is being

constructed.Session IbaanValue instance representing the Component Session

value.Parameters IbaanValue instance representing the parameters to the

operation. Those parameters are (BSTR Code, BSTR GUID,BSTR Origin).

NOTE



Exposed Broker objects to the Store operation are:

Name Descriptionthis IbaanValue instance representing the value that is being

constructed.Session IbaanValue instance representing the Component Session

value.Parameters IbaanValue instance representing the parameters to the

operation. Those parameters are (BSTR Code, BSTR GUID,BSTR Origin).

Exposed Broker objects to the StoreNew operation are:



value.Parameters IbaanValue instance that represents the parameters to the

operation. Those parameters are BSTR Code, BSTR GUIDand BSTR Origin.

Exposed Broker objects to the Delete operation are:




operation. Those parameters are BSTR Code, BSTR GUID,and BSTR Origin.

Exposed Broker objects to the GetTimeStamp operation are:




operation. Those parameters are BSTR Code, BSTR GUID,BSTR Origin, and DATE Timestamp.



Exposed Broker objects to the PrepareStore operation are:



valueParameters IbaanValue instance that represents the parameters to the


Exposed Broker objects to the PrepareStoreNew operation are:





Exposed Broker objects to the PrepareDelete operation are:





Exposed Broker objects to the RollbackStore operation are:







Exposed Broker objects to the RollbackStoreNew operation are:





Exposed Broker objects to the RollbackDelete operation are:


constructedSession IbaanValue instance that represents the Component Session



User Interface

Figure 11 Type Editor � Component



For each component you can run IActiveScript instead of OpenWorld Brokerscripts. One component can implement the operations using OpenWorld Brokerscripts, while other components use IActiveScripting.

If you select IActive scripts, you can specify an external file and the enginedefaults to VBScript.

The Iactive implementation page is as follows:



VBScript example

The following is an example VBScript of the GetTimestamp primitive, whichindicates how the returned value must be returned through the function name andnot the parameters. Any Iactive primitive that returns a value must return thevalue in the following way.

Option Explicit

Public Function GetTimestamp (Session, Code, This,

Timestamp)

Dim ReturnValue = Timestamp

ReturnValue = Time

GetTimestamp = ReturnValue

End Function

If the return type is not available in the parameter list, the type must be fetchedfrom the Broker repository as follows:

Dim Ret

Dim Server

Dim Conn

Dim Rep

Dim Obj

Set Server=CreateObject("Baan.IntegrationServer")

Server.Address="10.2.59.163:7250" ‘any valid ip addressSet

Conn=Server.LogonAsUser("SUPERUSER","SUPERUSER","RANDOM")

Set Rep=Conn.Repository

Set Obj=Rep.Object("\ReturnType")

To fetch the type from the Broker repository, the Baan COM client must beregistered on the computer that runs the script and \ReturnType must be a validtype in the repository. The Object is then an instance of the return type and canbe modified and returned through the script function name.


IntroductionThis chapter describes the Baan OpenWorld Broker's messaging facilities. Thesefacilities can be divided into the following groups:

� Facilities for automatic handling of incoming messages.� Facilities for sending e-mail.� Facilities for sending messages to users who are connected to the Broker.

Message objects

The facilities for automatic handling of incoming messages, and for sendingmessages to users, are based on message objects. A message object contains anBroker value, for example, a string or an instance of a row type. The messageobject can also hold information regarding the object�s sender, recipient, asubject, and so on. Usually, messages for automatic processing are stored in amessage queue folder and messages for manual processing are stored in a user'smailbox.

To handle incoming messagesPurposeThe Broker can receive and act upon a wide variety of signals and messages fromoutside sources. This messaging system plays an important role in the Broker'sintegration capabilities.

For example, you can:

� Listen for notifications of data changes from external applications. Upon sucha notification, a synchronization cycle is initiated to update all applicationsthat share this data.

� Feed information from front-end systems, for instance, in local branches, intothe back-end financials through the Microsoft Message Queue Server overthe Internet or over leased lines.

� Enable users to send e-mail to the Broker to initiate or control workflows.

8 Messages

Messages


For more examples, refer to �Example cases� in Chapter 7, �Componentintegration.�

Supported technologiesThe following message transports are supported:

� Internet e-mail (POP3/MIME).� Operating system files.� Microsoft Message Queues (MSMQ).� AMI message (for example, IBM MQSeries).

The following types of message encoding can be handled:

� Plain text strings.� XML documents.� BizTalk Framework.

The architecture is extensible through Microsoft�s COM to support user-definedmessage formats and transports.

For detailed information about message transports and message translators, referto �Message source� in Chapter 20, �Object type reference.�

ActionsTo handle a message that is received and translated, the Broker uses any of thefacilities of the objects in the repository, or uses the scripting language. You candefine the response to messages by means of the action wizard. Example actionsare:

� Send an e-mail.� Send a Broker message.� Run a script to initiate a synchronization cycle.

For more information, refer to �Action wizard� in Chapter 9, �Tools andassistants.�

Messages


ProcedureMessage sources, message queues, and message handlers all handle incomingmessage as follows:

� Message source objects define how to retrieve and handle incomingmessages.

� Message queue objects enable the Broker to buffer incoming messages until amessage handler is free to deal with these messages. Queued messages arestored in a folder in the object repository.

� Message handlers pick up messages of a particular logical data type from aqueue in the object repository and perform an operation on the messages.

For detailed information, refer to see the corresponding sections in Chapter 20,�Object type reference.�

The following list describes the procedure to process an incoming message:

1 A message source looks for messages when the its poll operation is called.

2 The message source receives the available messages through its transportlayer.

3 The message source puts each incoming message through a messagetranslator.

4 The message source�s translator parses the incoming message stream andcreates a meaningfully typed Broker value.

5 The message source packages the value inside a message object and storesthe value in a message queue in the object repository. A message queue cancontain messages of multiple types.

6 A message handler connected with the message queue picks up messages of aspecific logical data type. The message handler is activated when its polloperation is called.

7 The message handler executes a specified action for each message themessage handler picks up.

Messages


Facilities for sending e-mailIn the action wizard, you can define an action to send an e-mail message.

You can also use the scripting language; the String class has two operations thatyou can use to send e-mail messages:

� sendMail.� sendMAPI.

To send e-mail, you must specify the SMTP server and some related data asfollows:



3 Right-click the Server icon.

4 In the drop-down menu, click Properties.

5 On the Internet tab, specify a legal SMTP mail server, the full name of thee-mail sender, and the e-mail account, in the format [email protected].

6 Enter the remaining fields if relevant.

For information on these operations, refer to �String::sendMail� and�String::sendMAPI� in the Scripting Language Reference (U7278D US).

To send messages to usersThe Broker enables you to send messages to internal users. A message containsan instance of a logical data type. Examples of such instances are:

� A String type that contains plain text.� A row type, for example, a purchase request.� A table type, for example, a list of customers.

The Broker's workflow system uses such messages to transfer documents to theusers for further handling.

You can define an action to send a message to an internal user or a user group byusing the action wizard.

You can also use the scripting language. The User class has a sendMessageoperation and the Query class has send and sendTo operations.

Messages


In general, if you use the sendMessage operation to send the message, theprocedure is as follows:

1 A script calls the sendMessage operation on a user object. The parameters ofthe sendMessage operation specify the value that is sent and the form is usedto display the message.

2 The sendMessage operation packages the value in a message object. Themessage object contains a reference to the form and information about thesender, recipient, date and time of dispatch, and so on.

3 The message is put in the user's mailbox folder.

4 The user is notified that new mail has arrived.

5 If the user clicks Read now, the message is displayed by the associated form.

Mailbox

The user's mailbox folder is automatically created if the user receives messages.The mailbox folder is \sys\mailboxes\USERNAME, where USERNAME is theidentifier of the user, which is the name of the user object.

To open your mailbox, on the Baan OpenWorld Broker menu, click Mailbox.

This menu is contained in the Broker's default menu. This menu is not visible ifthe repository browser is open. The menu command opens the predefined form\apps\misc\forms\Mail, which contains a Mailbox type input field.

You can also send messages to user groups.

For more information, refer to the sections �Message�, �User,� �UserGroup,�and �Query� in the ScriptingLanguage Reference (U7278B US).

Messaging subsystemThe messaging subsystem is an addition to BOW Broker. This subsystemprovides the system the ability to act as a publish and subscribe tool, which usesseveral message transports to handle incoming messages and generates outgoingmessages in a variety of formats. The messaging subsystem is an important partof the �Integration Framework� vision for BOW Broker.

Messaging, or publish and subscribe, refers to a software architecture in whichmultiple applications, in many cases running on several server computers,integrate by informing each other of significant events. An application can beboth a publisher of events and a subscriber to other events.

NOTE

Messages


For instance, a customer management application can often publish an eventevery time a customer�s address changes. Other applications, such as BaanERP,can subscribe to this event and update their databases, for instance, the elementmaster, automatically.

Many important developments have been made in messaging technology, and theadvent of the Internet also enables applications to communicate more easily overlarge distances. Starting with Windows 2000, Microsoft includes a messagingand publish/subscribe service called Message Queue Server with the operatingsystem. MSMQS is also available today as a separate, free-of-charge option packfor Windows NT 4. Message Queue Server enables applications to exchangemessages, both synchronously, in which the sender waits for anacknowledgement from the receiver before continuing, and asynchronously, inwhich the sender sends a message and continues immediately while the messagesystem guarantees eventual delivery of the message to the recipient. A singlesender can serve multiple recipients in a publish/subscribe scenario, which istypically asynchronous.

Messaging combines the security and integrity of on-line transaction serviceswith the front-end responsiveness of queued batch processing. Posting anasynchronous message is a quick operation, while delivery and eventual updatingof the central database is guaranteed. Posting can be seen as a near-real-timeoperation. In some scenarios, true real time operation is necessary, and a fulltraditional on-line transaction server must be deployed. In other cases, �near-realtime� is enough, and much more efficient. For instance, a restaurant chain canhave a number of restaurants that use front-end sales systems, which post salesinformation back to headquarters using messaging. At headquarters, near-realtime sales data is continuously available for analysis. Meanwhile, individualrestaurant systems operate at full speed, even if communications links go down.

Near-real-time posting is only appropriate for write only operations and datacollection at the back end. Read-and-update operations, such as when yousubtract sold goods from inventory after you check for availability, must havetrue on-line transaction processing.

At the most basic level, messages are simply blocks of bytes. Forpublish/subscribe to work, the participating applications must agree on themessage formats they generate and recognize. Standards that have beenestablished in this field include the Open Application Group�s Business ObjectDocuments, the ISO/United Nations� EDIFACT, and recently the W3C�s XMLeXtended Markup Language. To communicate with disparate systems, a modernpublish & subscribe applications must be flexible and support multiple messageformats.

NOTE

Messages


Design overviewVersion 1.0 of BOW Broker, Corelli release, included the Messaging Subsystem.Version 2.0 sees the addition of a Message Sink to the system.

Four types of objects are available in the object repository:

� Message sources.� Message sinks.� Message queues.� Message handlers.

Message source objects define how to retrieve and interpret incoming messages.Message source objects contain message transport and message translatorsubobjects, together with information on where to queue incoming messages.Message transports include SMTP and MAPI e-mail, Microsoft Message QueueServer queues, IBM MQSeries queues, Collaborative Application Framework,messages, and operating system files. The current message translators are plaintext, user-defined, XML, and BizTalk.

You can use COM interfaces to plug new message transports and messagetranslators into the architecture. This architecture is extensible and supports awide range of plug-in translators and transports in the future. The user canperiodically poll message sources to check for new messages, retrieve andtranslate the messages, and post the messages to queues for handling.

Message sink objects define channels for outgoing messages. Because messagesink objects are more or less mirror images of message sources, message sinkobjects accept data values, put the values through translators, and output thevalues to a specified message transport.

Message queue objects enable BOW Broker to buffer incoming messages until amessage handler handles the messages. Queued messages are stored in a folder inthe object repository.

Message handler objects are associated with message queues. Message handlerobjects pick up messages of a particular type from a queue and perform anyoperation on the messages, such as start a workflow document, trigger alerts,start a synchronization process, post to BaanERP, or send other messages.

With these additional tools, BOW Broker can listen to a variety of messagesources and obtain messages in multiple formats. Incoming messages can behandled by any of the powerful facilities of BOW Broker�s repository objectsand scripting language. Outbound messages can be generated at any time andposted to external recipients. The messaging subsystem is tightly integrated withservices such as Microsoft�s Message Queue Server.

Messages


Design approachTo support messaging, four new classes of repository objects are available whichare described in the following sections.

These classes are in addition to the Message object, which is a wrapper around aBOW Broker value of any type. For example, a message can contain a customer,a document, or an expense report. Messages can also have associated senders,recipients, and subject headers. The system automatically marks all messageswith date and time of creation and receipt. Messages can be stored anywhere inthe repository, however, if the messsages must appear in a recipient�s mailbox,the messages must be stored in the \sys\mailboxes\USERNAME folder, whereUSERNAME is the name of the recipient.

Message queuesMessage queue objects enable BOW Broker to buffer incoming messages in theBOW Broker repository until a message handler processes the messages. Amessage queue has no knowledge of the contents of the messages that areprocessed.

Messages


Message queues are defined as objects in the object repository. Message queuesconsist of a description and a pointer to a repository folder where messages in thequeue are stored. A message queue object works as an intermediary betweenmessage sources and message handlers. Incoming messages from messagesources are put into queues upon receipt, while message handlers extract themessages from a queue and perform an action on them. If you change thedefinition of a queue object, you can switch the traffic between variousrepository folders without modifying the sources and handlers that refer to thequeue.

Message queue objects support the following operations, which are availablefrom the scripting language:

get () Obtains the next message from the queue in FIFO order.Returns the message�s value, then deletes the message fromthe queue.

peek () Obtains the next message from the queue in FIFO order.Returns the message�s value, but does not delete the messagefrom the queue.

count () Returns the number of messages currently in the queue.

Message sourcesMessage source objects operate as shown in the following illustration:

CODA Business Server

Outside sources

Message transport

Message translator

Message queue

Message source object

Objectrepository

Messages are pulled in from outside sources through a message transport layer.After the messages are retrieved in raw, binary format from the source, themessages are routed through a translation layer, where a translator parses the rawbyte stream and creates a meaningful typed BOW Broker value from the rawbyte stream.

Messages


After this translation, the value that results is packaged inside a BOW Brokermessage object and stored in a message queue called the object repository.

Message sources are defined in the repository using a wizard. The pages of thiswizard are shown in the following figures:

The first page enables the user to specify to which queue this message sourcewrites incoming messages.

Messages


The second page enables the user to define the message transport used to fetchthe message from the outside world. The list box shows all the supported types ofmessage transports. Note that the list of transports that must be supported in v7can differ from the list shown in the screenshot. The Properties� button enablesyou to configure the message transport that you choose.

Messages


The POP3/MIME Internet e-mail transport is configured using the POP3Transport Properties dialog box, which is shown in the following figure:

The POP3 Transport Properties dialog box contains edit fields for the IPaddress of the POP3 server to poll for e-mail, as well as the user account, and thepassword to use when the user logs on to the server. The user can also elect tohave BOW Broker read only previously unread messages from the POP3 server,or to read all messages found on the server, and in the latter case optionallydelete the messages after reading them.

Messages


The Operating system file transport is configured using the File TransportProperties dialog box, as shown in the following figure:

The user can tell the system which folder must be watched for messages (files).If the system processes a file, the user can elect to delete the file or move the fileinto another folder to be archived.

Messages


You can use the MSMQ Transport Properties dialog box to configure theMicrosoft Message queue transport, which is shown in the following figure:

The MSMQ Transport Properties dialog box displays all available queues. Thequeues that are displayed are fetched from the BOW Broker server, which meansthat the MSMQ components must only be set up on the server, not on each client.

The AMI Message transport is defined using the MQSeries TransportProperties dialog box, as shown in the following figure:

Application Messaging Interface (AMI) is an API defined by IBM, and can sit ontop of many messaging subsystems. One such subsystem is IBM�s MQSeries.

The Collaborative Application Framework (CAF) transport is part of a laterversion of BOW Broker.

Messages


With the Custom Transport Properties dialog box, which is shown in thefollowing figure, you can use the user-defined transport that uses COM:

The custom transport facility enables a user-defined COM class to act as themessage transport. The user must fill in a COM CLSID or PROGID identifier,which BOW Broker passes to a CoCreateInstance call to create a freshinstance of the user�s transport object. This object is assumed to implement theBOW Broker messaging transport interface IBaanMsgTransport, definedin an interface definition file (IDL), that is shipped with the product. Themessaging IDL source is listed in �IDL listing,� in Chapter 8, �Messages.�

The third wizard page enables the user to select and configure the data translator(parser) that is applied to the raw incoming message:

Messages


The list of available translators, or parsers, appears in a list box. The user canchoose one of these translators and optionally configure the translator using theProperties... button.

The Text string translator is defined using the Plain Text Translator Propertiesdialog box, which is shown in the following figure:

For example, either the message is assumed to be in a single (SBCS) or amultibyte (MBCS) character set, or a Unicode character set.

You can use the Custom Translator Properties dialog box, which is shown inthe following figure, to define the user-defined translator:

The custom translator facility, similar to a custom transport, enables a user-defined COM class to act as the message translator. The user must fill in a COMCLSID or PROGID identifier, which BOW Broker passes to aCoCreateInstance call to create a fresh instance of the user�s translatorobject. This object is assumed to implement the BOW Broker messagingtranslator interface IBaanMsgTranslator, defined in an IDL, shippedwith the product. The messaging IDL source is listed in �IDL listings,� inChapter 8, �Messages.�

Messages


To define the Extended Markup Language (XML) translator, you can use theXML Translator Properties dialog box, which is shown in the followingfigure:

For example, you can apply an optional XSL style sheet to the incoming XMLbefore the XML translator handles the message. XML translators can onlytranslate message to types defined in the \sys\xml folder.

The BizTalk framework translator has no properties, however, like the XMLtranslator, Biztalk can only translate messages to types defined in the \sys\biztalkfolder.

After this translation is complete, the user presses the wizard�s Finish button tostore the message source object in the repository, ready for use.

Message source objects support the following operation, available from thescripting language:

poll () Poll the message source for incoming messages. If present, themessages are obtained from the message transport, put throughthe message translator, and written to the output queue. Theoperation returns the number of messages, that are successfullyprocessed.

Messages


Message sinksMessage sinks are the reverse of message sources. Message sinks accept datavalues, put the values through translators, and output the values to a specifiedmessage transport.

Message sinks are defined in the repository using a wizard. The pages of thiswizard are shown in the following figure:

This page simply describes the message sinks.

Messages


The message first goes through a message translator. The available messagetranslators are shown in the following page of the wizard:

The properties for each of the message tranlators are the same as for a messagesource. The XML translator�s optional XSL transformation occur after themessage goes through the internal XML transformation, before the message ispushed to the message transport.

Messages


The message then goes to the transport. The available transports are shown in thefollowing page:

Again, the properties for each are similar, except in the following:

The SMTP Internet e-mail transport is defined using the SMTP TransportProperties dialog box, which is shown in the following figure:

Messages


You can use the File Transport Properties dialog box, which is shown in thefollowing figure, to define the Operating system file transport:

Message sink objects support the following operation, available from thescripting language:

push (Value v) The value can be either a string or a row value. The valueis routed through a translator and then to a transport forcommunication to the outside world. The push operationreturns a nonzero number if the operation succeeds and amessage is sent, or zero if the operation fails.

Messages


Message handlersMessage handlers are associated with message queues. Message handlers pick upmessages of a particular type from the queue and perform any BOW Brokeroperation on them, such as start Workflow documents, trigger alerts, post toBOW Broker, or post other messages.

The following figure illustrates the message handlers:

CODA Business Server

Message action

Message queue

Message handler object

Objectrepository

You can use a wizard to set up message handlers. The following figure shows thefirst page of the Message Handler wizard:

BOW Broker message handlers depend on the type of the document beingprocessed. Message handlers are configured to only act on messages that containvalues of a specific type, and any types derived from that type.

Messages


This enables, for example, various XML messages, such as ORDERS,INVOICE, and so on, to be handled by various handlers.

The type associated with the handler that is defined is selected using a drop-down repository combo box.

The user specifies which queue the message handler must read from. The readingcan occur in first in, first out (FIFO) order, or last in, first out (LIFO) order.

The next pages of the wizard define the action to take on the message, and usethe standard Action Wizard of BOW Broker. This wizard enables you to start aworkflow document, execute an arbitrary script, send an e-mail, and performother common actions. Note that the argument that is sent into the messageaction always has the type specified in the type combo box.

IDL listingThe following box lists the IDL source for the BOW Broker messaging COMinterfaces. These interfaces are used by user-defined message transports andtranslators.

A user-defined message transport must implement the following interface:

� IBaanMsgTransport

A user-defined message translator must implement the following interface:

� IBaanMsgTranslator

In both cases, the user-defined class must be able to work with the followingBOW Broker supplied outgoing interfaces:

� IBaanMsgBuffer� IbaanMsgError

/*

BaanMessage.IDL

IDL source for Baan OpenWorld Broker Messaging

Copyright (C) 2000 by Baan Company

*/

// This file will be processed by the MIDL tool to

// produce the type library (BaanMessage.tlb) and

marshalling code.

EXAMPLE

Messages


import "oaidl.idl";

import "ocidl.idl";

import .”.\bsrvitf\bsrvitf.idl";

[

object,

uuid(F85C2EE3-B4FE-11D1-95B9-00805FA3A240),

helpstring("IBaanMsgBuffer Interface"),


]

interface IBaanMsgBuffer : IUnknown

{

[propget,helpstring("Obtain the current total size of

the byte buffer")]

HRESULT Size (

[out,retval] LONG* pl);

[helpstring("Copy to the buffer from a BSTR")]

HRESULT CopyFrom (

[in] LONG lOffset,

[in] BSTR bstr);

[helpstring("Copy from the buffer to a BSTR")]

HRESULT CopyTo (

[in] LONG lOffset,

[out] BSTR* pbstr,

[in] LONG lSize);

[helpstring("Copy to the buffer from a byte array")]

HRESULT CopyFromBuffer (

[in] LONG lOffset,

[in,size_is(lSize)] BYTE* pbBuffer,

[in] LONG lSize);

[helpstring("Copy from the buffer to a byte array")]

HRESULT CopyToBuffer (

[in] LONG lOffset,

[out,size_is(lSize)] BYTE* pbBuffer,

[in] LONG lSize);

};

Messages


[

object,


helpstring("IBaanMsgError Interface"),


]

interface IBaanMsgError : IUnknown

{

[propget,helpstring("Get the text of the error

message")]

HRESULT Message ([out,retval]BSTR*);

[propput,helpstring("Set the text of the error

message")]

HRESULT Message ([in]BSTR);

};

[

object,


helpstring("IBaanMsgTranslator Interface"),


]

interface IBaanMsgTranslator : IUnknown

{

[helpstring("method Open")] HRESULT Open ([in]

IBaanRepository* pRep);

[helpstring("method Decode")] HRESULT Decode([in]

IBaanMsgBuffer* pBuffer, [in,out] IBaanValue** ppvValue,

[in] IBaanMsgError* pmeMsg);

[helpstring("method Encode")] HRESULT Encode([in]

IBaanMsgBuffer* pBuffer, [in] IBaanValue* pv, [in]

IBaanMsgError* pme);

[helpstring("method Close")] HRESULT Close ();

};

[

object,


Messages


helpstring("IBaanMsgTransport Interface"),


]

interface IBaanMsgTransport : IUnknown

{

[helpstring("method Open")] HRESULT Open ();

[helpstring("method IsReadyForRead")] HRESULT

IsReadyForRead ([out, retval] short* retvalue);

[helpstring("method IsReadyForWrite")] HRESULT

IsReadyForWrite ([out, retval] short* retvalue);

[helpstring("method Read")] HRESULT Read([in]

IBaanMsgBuffer* pBuffer, [in] IBaanMsgError* pme);

[helpstring("method Write")] HRESULT Write([in]

IBaanMsgBuffer* pBuffer, [in] IBaanMsgError* pme);

[helpstring("method Close")] HRESULT Close ();

};

[

object,

uuid(D97BE300-A8D1-11d3-A285-00105A6B68E3),

helpstring ("IDummy Interface"),

hidden

]

interface IDummy : IUnknown

{

};

// We do not want a type library because all the

interfaces above are IUnknown interfaces, not

// IDispatch. We handle the marshaling ourselves in

the msgProxy.DLL which is built using

// the files generated when this file is compiled

(using MIDL.exe).

// Note that it is neccessary to register the

msgProxy.DLL in order to be able to use the

// Baan Messaging Subsystem in an inter-threaded

environment.

[

uuid(F85C2ED3-B4FE-11D1-95B9-00805FA3A240),

version(1.0),

Messages


helpstring("Baan OpenWorld Broker Messaging 1.0 Type

Library")

]

library BaanMessageLib

{



[

uuid (FC4CA630-61C2-11d2-AB14-00805F638D68),

helpstring ("Dummy Class definition to satisfy the

MIDL rules to produce a valid type library"),

hidden

]

coclass Dummy

{

[default, restricted] interface IDummy;

interface IBaanMsgTransport;

interface IBaanMsgTranslator;

};

};

Messages



Application development is facilitated by a number of powerful tools. Thefollowing table lists these tools, and the tables are then further explained in thefollowing sections.

Tools, helpers, and assistantsTool DescriptionTool dock A window that contains the expression tool, fields tool,

fonts tool, and the color tool.Expression tool A tool in which you can enter and test a scripting language

expression.Fields tool A tool to add fields to forms.Fonts tool A tool to select and apply font styles to texts.Color tool A tool to mix and store colors and to apply colors to

objects.Action wizard A wizard that helps you to define automated actions, such

as automatic sending e-mails, starting workflows, orstarting periodic processes.

Type assistant A tool that helps you to select a type. You can select eithera user-defined type from the repository or a predefinedprimitive type (Number, String, and so on).

Expressionassistant

A tool that helps you to enter valid expressions.

Script assistant A tool which enables you to enter a script and, undercertain circumstances, test and debug the script.

Tool dockThe tool dock contains four tools that can help you to design Broker objects:

� Expression tool.� Fields tool.� Fonts tool.� Color tool.

These tools are described in the following sections.

To open the tool dock, on the File menu, click Open Tool Dock.

9 Tools and assistants

Tools and assistants


You can also find the Open Tool Dock menu command on the repositorybrowser's Objects menu.

Expression toolIn the expression tool, you can enter and evaluate a scripting languageexpression. Example expressions include:

� 12+3.� \users\SUPERUSER.edit.� System.queryTime.

The expression tool contains a history list. To enter an expression that you typedbefore, click the drop-down arrow next to the expression field and click anexpression on the history list.

Click Expression assistant to open the expression assistant. The expressionassistant is explained later in this chapter.

Fields toolIf you edit a form that is linked to a row type, the field tool displays a list offields that you can drag onto the form. The use of the fields tool is explained in�Form� in Chapter 20, �Object type reference.�

Fonts toolYou can use the fonts tool to change the text styles of text boxes, as follows:

1 Open the tool dock and a form.

2 Configure a font style in the fonts tool.

3 Drag from one of the four shadowed T icons to the Preview field to add ashadowing effect, if desired. To remove shadowing, drag from the top,unshadowed, T icon.

4 Click on the sample in the preview window, and drag the sample onto anytext box or onto a tab of a background query. The type changes accordingly.



Color toolYou can use the color tool to quickly apply color to many elements of an objectand to the background of some windows. The elements that you can apply colorto are mostly those used when you create a form.

Named colors

You can give arbitrary names to colors, for example, BackgroundColor orAttentionColor. If you use named colors, you can more easily maintain aconsistent color scheme. For example, if you change BackgroundColor fromgreen to a yellowish color, all objects with that color then change appearance.

Applying colors to objectsTo apply a color, take the following steps:

1 Open the Tool Dock and a form object.

2 Drag any color out of the Color tool and drop the color over the backgroundof a window or over an object. If the mouse pointer comes at a point whereyou can drop a color, the mouse pointer changes to a paint roller.

Several additional options are available for you to use to change the color of atext box on a form:

You can drop a color on a text box in one of the following three ways:

� Simply drag the color to change the background color of the text box.

� Hold down SHIFT while you drag a color onto some text to change the text�sforeground color.

� Hold down CTRL while you drag a color onto some shadowed text to changethe color of the text shadow.

You can also color the tabs of background queries in the same way, changingtheir background, text, and shadow.



To mix colorsYou are not limited to the colors supplied on the Color tab of the Tool Dock, butcan mix your own.

To mix a new color, take the following steps:

1 Open the Tool Dock.

2 Select the Color tab.

3 Drag a color to the mixing tank.

4 Change the color with the red, green, and blue slider controls until you havethe color you want.

You can now:

� Drag and drop the color onto an object to apply the color.� Drag and drop the color onto one of the cells on the Color tab to store the

color for future use.� Create a named color. For more information, refer to �Named colors,� later in

this chapter.

Named colorsThe definition of named colors enables you to more easily maintain a consistentcolor scheme. For example, you can define a collection of named colors:

� BackgroundColor.� BorderColor.� MainText.� WarningText.� TextShadow.

If you later change the color of a named color, all the objects to which youapplied that named color will be changed accordingly.



The following table explains the use of named colors.

The use of named colorsIf you want this Do thisDefine a named color 1 Create a color in the mixing tank as described in

�Mixing colors,� earlier in this chapter.2 Enter a name for the color in the text field and click Plus (+) to store the color with the name.

Apply a named color to anobject

Drag the color from the mixing tank to the object(background, text box, and so on).Use the SHIFT key to apply a color to theforeground of a text and the CTRL key to apply acolor to a text shadow.

Load a named color backinto the mixing tank.

Select the name of the named color in the text box.

Change the color of anamed color

1 Load the named color in the mixing tank by selecting the color�s name from the drop-downlist.2 Change the color with the slider controls.3 Click Plus (+) to save the changes.

Delete a named color 1 Select the named color from the drop-down list.2 Click Minus (-). The color is deleted from the system.

Action wizardFunction of the action wizardIf one of the following situations occurs, the Broker must respond with a certainaction:

� A user clicks a button on a form.� A user clicks a menu command.� A value that is monitored by an alerter becomes higher or lower than the

prescribed bounds.� A message handler receives an incoming message.

You must specify the appropriate action when you define the form, menu, alerter,and message handler objects that handle these situations. If you must define suchan action, the action wizard appears automatically.



In the action wizard, you can select one of the following types of action:

� Send e-mail.� Start workflow.� Send Broker message.� Run script.� Display form.� Start periodic process.� Evaluate timed variable.� Do nothing.

After you select the type of action, the action wizard prompts you for anyinformation that is required to execute the action, for example, an e-mail address.

Macros in e-mailsIf you specify that an e-mail must be sent, you can use the following macro codesin the subject and in the message text:

� %DATE% for the current date.� %TIME% for the current time.� %VALUE% for a value, for example, the current value of an alerter.� %PREVVALUE% for the previous value, which can be useful in alerters.� %<any expression>% for the expression result,

The Broker will expand the macros before sending the message.

VariablesIf you press the Run script action for a form button, you can use the specialvariables for forms:

� Page.� Value.� State.

The operations of the View object are also available. For more information, referto �Forms� in Chapter 20, �Object type reference.�

If you select the Run script action in a message handler object, you can accessthe value contained in the message by means of the �this� variable.



Poll message source action in Action WizardThe action Poll message source is added to the Action Wizard. This actionenables the user to select individual message sources from the repository with auser interface, and trigger the poll method of the selected message sourcethrough the action wizard. The optional choice is also added to select associatedmessage handler to the selected message source. This action results in a messagebeing retrieved and handled as soon as the message arrives.

The definition of the poll method:

Poll( ) Poll the message source for incoming messages. If present, themessages are obtained from the message transport, put through themessage translator, and written to the output queue. The operationreturns the number of messages successfully processed.

The user interface to select the Poll message source action is as follows:



The user interface to select the message source from the repository is as follows:

On this page of this wizard, the Poll associated message handler check boxenables you to specify an optional message handler. If you do not select thecheck box, the wizard ends here, and the result a triggering of the poll method ofthe selected message source through the action wizard.



If you select the check box, the wizard shows the following page to select amessage handler associated with the message queue from the former selectedmessage source.

If you select an associated message handler from this page, this will result in amessage of the selected message handler type being retrieved and handled assoon as the message arrives

Push to message sink action in the Action Wizard.The Push to message sink action is added to the action wizard. This actionenables you to write expressions that must either result in a string or a row valueand push the value of the expression to a selected message sink that is triggeredthrough the action wizard.

The user can select message sink from a user interface and write the expressionfor the selected message sink with a script interface.

The definition of the push method for message sink:

Push (Value v) The value can be either a string or a row value. The value isrouted through a translator and then to a transport forcommunication to the outside world. The push operation returnsa nonzero number if the operation succeeds, and a message, orzero, is sent if the operation fails.



The user interface to select the Push to message sink action is as follows:

The user interface to select a message sink from the repository is as follows:



The user interface to write an expression that results in a string or row value forthe formerly selected message sink is as follows:

Type assistantIf you must enter a logical data type in a field, you often find the icon for thetype assistant next to the field. You can click this icon, or press F4, to open thetype assistant. You can select a type in one of two ways:

� Click a user-defined type in the tree view of the repository

� Click a button to select a predefined primitive type, such as Number, String,and so on. You can find additional predefined types in the \predef\systemfolder.

Click Close to accept the selection.

Expression assistantIf the input cursor is in an expression field, you can usually press F4 or click themagnifying glass icon to open the expression assistant. The expression assistanthelps you to enter valid expressions.

While you enter an expression, the expression assistant displays a list ofvariables or operations that you can add to the expression.



For example, if you type This is a string in the input field, the list will show theoperations that you can perform on values of type String.

To add something from the list to the expression, you must double-click the itemin the list.

If the expression contains errors, a red traffic light is displayed. If the expressionassistant cannot determine whether the expression is valid, the light is yellow.

Click OK to accept the expression.

Script assistantIn places where you can enter a script, you can press F4 to open the scriptassistant. The script assistant enables you to enter a script and, under certaincircumstances, test and debug the script.

The following functions are available:

Script assistant functionsButton DescriptionLoad Loads a text file.Save Saves the script to a text file.Parse Checks the code in the Script Input field and displays a message box

that indicates whether errors were found. If errors do exist, the errorsare detailed on the Error tab. If you click on an error in the Error listbox, you can move the cursor to the location of the error.

Test Tests the code in the script input field.This button is enabled only when the code belongs to an object at theoutermost scope in the system, at the level of the object repositorybrowser.

Debug Enables you to debug your code. If you click this button, the ScriptAssistant window controls change to provide you with severaladditional options. The video-recorder-style buttons enable you tostep through the code line-by-line.Before debugging, the script is parsed, and debugging will not bepossible until all errors are fixed.This button is enabled only if writing scripts for timed variables andperiodic processes, because these are the only two objects that havea run-time context that enables their scripts to be debugged.

Close Closes the script assistant and transfers the code to the field fromwhich you called the script assistant.



If you select the Show tabs check box, the Identifiers tab and the Errors tabappear. The Identifiers tab lists the valid elements of the script that can be used.The Errors tab lists the errors found in the code. If you double-click an errorline, you can move the cursor to the error.

Several editing functions are available through the shortcut menu and a numberof shortcut keys. To find these functions, right-click in the script window.

To change syntax coloring, right-click in the script window, and click Propertieson the shortcut menu.


IntroductionIn the Baan OpenWorld Broker, to develop applications, you can create andconfigure objects in the repository browser. Only users with superuser status canopen the repository browser. The Broker has a number of user-interface elementsthat you can use to set up a user interface for end users that use the Broker in anoperational environment.

The most important types of user-interface elements are:

� Drop-down menus.� Windows and dialog boxes.� The background of the main Broker window.� Messages (for example, error messages).

This chapter gives you an overview of the functionality. For details, refer to thesections �Form,� �Menu,� and �Query� in Chapter 20, �Object type reference.�

For information about user interfaces in multiple languages, refer to Chapter 15,�Language support.�

Drop-down menusDrop-down menus enable the user to start actions. To define drop-down menus,you must define menu objects. You can define menus for a particular user or agroup of users. In this way, you can configure the user-interface for each user.

Windows and dialog boxesTo create windows and dialog boxes, you must define several forms and queries:

� A form defines the layout of the window. A form can contain data entryfields, buttons, pictures, and so on.

� A query combines a form with data. A query can display the fields of a tablerow, a grid with table data, or simply numbers or text.

10 User interface

User interface


FormsBroker forms define the layout and the functionality of windows and dialogboxes. A form is always linked to a particular logical data type. The form canonly display values of the type to which the form is linked.

Forms can contain tabbed pages. Forms can be configured to show at run-timeonly those controls that are appropriate to the current user. You can placestandard elements such as a company logo on a base form. The other forms caninherit these elements from the base form. If the company logo changes, youmust simply change the base form, and all the other forms will be changedautomatically.

A form can contain:

� Input fields.Used to control how data is displayed on the form and how the data can beedited.

� Display fields.Display the result of an expression.

� Push buttons.Used to enable the user to execute some action, for example, to switch toanother form.

� Static elements, such as text labels, pictures, and group boxes.

A form can also contain table viewers, multiline text fields, and even HTMLfields, which enables you to display HTML pages.

QueriesA query combines data of a certain type with a form to display the data. Thequery has an expression that determines the data that is displayed. The data canconsist of table rows, but the data can also be simpler, for example, numbers, ortext.

You can run a query as Multi Document Interface (MDI) window, or as a dialogbox. The following section describes yet another way to use queries.

User interface


The main windowYou can place queries on the background of the Broker main window. Thesequeries are called background queries. You can also place forms on thebackground. If a user has more than one background query, tabbed pages appear.The user can switch between background queries by clicking on the appropriatetab.

You can specify background queries in an environment object. The Broker willpresent these background queries automatically to all users linked to thatenvironment.

You can use background queries in several ways, for example:

� A particular user only uses a small number of data-entry windows. Thesewindows can be configured as background queries in the environment objectof that user.

� You created an application that offers a number of functions to the end user.You can define a form with buttons that start these functions. This form canbe placed in the background as the main menu of your application.

MessagesOften, you want to place a message on the user�s screen, for example, an errormessage. To display this message, you can use the printf function in the scriptinglanguage.

printf statements in scripts do not appear if the script is evaluated on the server.Periodic processes, timed variables, and alerts, as well as the componentintegration subsystem�s scripts, are all evaluated on the server.

If you want more control over the appearance of the message, you can define aspecial form to display messages.

{

\forms\MessageForm . run ("Negative value not allowed.",8);

}

You can also send messages to the mailboxes of users. For more information,refer to �Sending messages to user� section in Chapter 8, �Messages.�

You can also use the msgBox operation of the System object to display amessage box. For more information, refer to �System::msgBox� in the documentScripting Language Reference (U7278D US).

NOTE

EXAMPLE

User interface



A periodic process is an automatic process or task that can start at a predefinedtime and run from that point in time at predefined intervals. Periodic processescan run any script written in the scripting language. The server, not the client,executes all periodic processes. The user can specify the interval of the periodicprocess in seconds, minutes, hours, days, or weeks.

Periodic processes can perform a variety of tasks, for example:

� Collect a history of certain financial indicators for a company.� Start a daily data synchronization process.� Initiate system administration tasks, such as making backups, or performing

regular checks.� Poll message sources and message queues.

The Periodic processes dialog box provides a convenient way to start and stopperiodic processes. To open the Periodic processes dialog box, on the BaanOpenWorld Broker menu, point to Settings, and then click Active periodicprocesses in the submenu.

This menu is contained in the Broker's default menu. This menu is not visible ifthe repository browser is open. The menu command calls the scripting languageoperation System.runPeriodicCtrl () .

For more information, refer to �Periodic process� in Chapter 20, �Object typereference,� and Chapter 22, �Recurrence schemes.�

11 Periodic processes

NOTE

Periodic processes



An alert is a warning that a variable has a value that is either too high or too low,or increases or decreases at too high a rate. You can use this feature to monitorcritical business performance indicators.

Alerts are generated by a special type of periodic process called alerters. Analerter regularly checks the value of a specified timed variable or expression. Ifthe value exceeds certain bounds or changes very fast, the alerter automaticallyresponds by executing a user-defined action. For example, the alerter can send ane-mail notification, a Broker message, initiate a workflow, or run a script.

In its simplest form, an alerter monitors the value of a timed variable. For moreinformation on timed variables, refer to �Timed variable� in Chapter 20, �Objecttype reference.�

You can also create a program script to monitor the result of a complex formula.For details, refer to �Alerters� in Chapter 20, �Object type reference,� and inChapter 22, �Recurrence schemes.�

12 Alerts

Alerts



The Baan OpenWorld Broker has a number of features that enable you toconnect your application to the Internet.

HTML objects

A value of the HTML class stores parsed Hypertext Markup Language (HTML)documents. Two methods to obtain HTML objects are available:

� Construct a HTML object from a string.� Retrieve an HTML page from the World Wide Web.

The following example script shows the construction of an HTML object from astring:

HTML h ("<p>Paragraph one </p> <p> Paragraph two </p>");

To retrieve an HTML page from the World Wide Web, you can use the getURLoperation of the Internet object.

HTML objects have operations to extract text from within HTML values, forexample, from individual table cells or paragraphs.

Internet object

The Internet object offers operations to access Internet resources, mainly HTMLdocuments and pictures. One of these operations is the getURL operation. ThegetURL operation retrieves an HTML document stored on a web site.

{

// Get the latest exchange rate

HTML html = Internet . getURL ("http://www.rate.com", 4);

// Process ...

}

For more information, see the HTML class section and the The Internet objectsection in the document Scripting Language Reference (U7278D US).

HTML viewer

You can create an HTML viewer by placing an input field of type HTML on aform. For more information, refer to �Form� in Chapter 20, �Object typereference.�

13 Internet and HTML

EXAMPLE:

Internet and HTML


Web client

To develop a Web client, you can create HTML pages that access the Broker'sCOM interfaces. In this way, you can enable access to the Broker through a webpage.

FTP

You can send a string to an Internet File Transfer Protocol (FTP) server and storethe string as text file. For more information, refer to �String::sendFTP� in theScripting Language Reference (U7278D US).


User objectsFor each user that accesses the Baan OpenWorld Broker, a user object must existin the \users\ folder.

The functions of user objects are:

� Control access rights.� Configure the user environment.� Identify the person that performed certain actions. For example, the version

control system records which developer locks or modifies an object. Thelogging system records the user that initiated an event.

� Enable the system to send messages to users.� Distribution of documents in the workflow system.

To group users, you must define user groups. User groups can contain other usergroups. In this way, you can set up a hierarchical structure of users. You can useuser groups as distribution lists for messages.

The Users dialog box provides a convenient way to create and modify userobjects. To open the Users dialog box, on the Baan OpenWorld Broker menu,point to Settings, and click Users on the submenu.

For detailed information, refer to �User� and �User group� in Chapter 20,�Object type reference.�

To log onIf your Broker client is configured for trusted logon, you can start the programwithout entering a user name or password. The system uses your Windows NTuser name as user identification.

If you log on to the system for the first time, and your Windows NT user namedoes not exist in the \users\ folder, the Broker will automatically create a user foryou. Automatically created users do not have superuser status.

To log on with a different user identification or password, you must configureyour Broker client to start without trusted logon.

14 User management

User management


To configure your Broker client, take the following steps:



3 Right-click the Client icon.


5 On the Basics tab, select or clear the Enable trusted logon check box.

After you log on, the Broker sets up the user environment that is linked to youruser object.

Access rightsThe Broker uses the passwords of user objects to control access to the system.The user object has two options to differentiate access rights:

� Superuser.� VCS access.

Superuser

Only users with superuser status can create and modify objects. Users who arenot superusers cannot open the repository browser, and cannot right-click anobject to open a shortcut menu. You must have superuser status before you canchange the superuser status of any user. The Broker contains a predefined userobject SUPERUSER. After you install the system, you can use SUPERUSER togrant superuser status to other user objects.

VCS access

A user with VCS access can modify version-controlled objects. For moreinformation, refer to Chapter 17, �Version control system.�

User management


User environmentYou can link each user to an environment object. The environment objectcontrols the entire user environment, including:

� The language of the user interface.� The shortcut menus.� The queries shown in the background of the main window. A query can

contain pictures, data fields, buttons, and so on.

You can also use the environment to start a script whenever a user logs on, or tostart periodic processes.

User management



Environments can inherit the attributes of other environments. For moreinformation, refer to �Environment� in Chapter 20, �Object type reference.�

IntroductionThe Baan OpenWorld Broker can display texts in the user interface in multiplelanguages, depending on the settings of the user. If you want to use this feature,you must take the following steps:

1 Enter descriptive texts in multiple languages.

2 Enter the locale of the user.

The texts that can occur in multiple languages are called locale strings.

The system recognizes locales for many languages and countries, for example,Español � Argentina. In addition to the locales for specific languages, the systemhas a special locale named Default. If the system cannot find a text string for aspecific locale, the system always displays the text for the Default locale.

Translation

You can export all locale strings to a text file for easy translation of the userinterface.

To enter texts in multiple languagesMultilanguage fields

You can enter locale strings in multilanguage fields. Many objects havemultilanguage fields, for example:

� Description fields, such as the description of a form.� Menu items in menu objects.� Text fields on forms.

You can recognize multilanguage fields by the globe button next to the field. Ifyou enter text in a multilanguage field, you can open the language-independentinput box as follows: press F4 or click the globe icon.

15 Language support

Language support


If you enter a text directly in a multilanguage field, the string will be stored underyour current user locale.

Text tables

If you work with strings in expressions, you can use language-independent texttables. In a language-independent text table you can store many locale strings,that you can use in scripts and expressions.

Example situations where you can use text tables are:

� Error messages displayed by calling the printf function in the scriptinglanguage.

� Expression fields on forms.

For more information about text tables, refer to �Text table� in Chapter 20,�Object type reference.�

To set the user languageTo set the user language, you must specify the appropriate locale in the userobject of that user or in the environment object to which the user is linked. Thelanguage specified for the user usually overrides the environment language.However, if the user�s language is set to Default, the environment language isused.

If a user logs on to the Broker, the system displays all the locale strings in thelocale of the user.

To open a dialog box to change the current language, you must call thesetLanguage method of the Environment object. For more information, refer tothe document Scripting Language Reference (U7278D US).

For more information, refer to the sections �User� and �Environment� inChapter 20, �Object type reference.�

Text exportTo make the translation of the user interface easier, you can export the localestrings to a text file. The overall procedure is as follows:

1 Export the locale strings in the source language to a text file.

2 Translate the strings in the text file.

3 Import the translated strings in the locale of the target language.

Language support


To export locale strings, you must use the following procedure:

1 Start the Tool Dock.

2 Enter the following expression in the Tool Dock's Expression tab:Archive . exportLocaleStrings

3 Click Evaluate.The Export Locale Strings to File dialog box opens.

4 Enter a valid path and file name in the Name field for the file that will storethe exported locale strings. The file automatically receives the extension txt.

5 Add or remove objects from the Objects to export strings from list, untilyou are satisfied with the resulting selection.

6 Select the locale that must be exported.

7 Click OK.

Tip

To make operations such as this more readily available to you, you must putthese operations in a menu. For more information, refer to �Menu� in Chapter 20,�Object type reference.�

The procedure to import the translated strings is similar to the export procedure:


2 Enter the following expression in the Tool Dock's Expression tab:Archive . importLocaleStrings

3 Click Evaluate.The Open dialog box opens.

4 Select the file containing the locale strings that you want to import.

5 Open the Locale list and select the language that you want to import.

6 Click OK.

Language support



IntroductionYou can export objects to a file. You can then import the export file in anotherobject repository. You can also perform exporting for several purposes, forexample:

� To make a backup of (parts of) the object repository.� To distribute applications to other servers.� To restore your own objects after you install a new version of the Broker.

Export files have the extension .ofa, which stands for Object File Archive. Foreach exported object, the following data is also stored in the export file:

� Version number of the object.� Creation date and modification date (time stamp).� Import method.

The export operation does not export information about older versions of objectsin the Version Control System (VCS).

Relative or Absolute

The import method can be Absolute or Relative. An object�s import method isspecified when the object is exported and cannot be changed afterwards.

If objects are marked as Absolute, they objects are imported in exactly the samepath that the objects were originally in. If objects are marked as Relative, theobject�s import location is determined relative to a specified base location. Thefollowing example shows how this works.

The following objects were exported to a file:

� \vars\PriceList, a global variable, import method Absolute.

� \ABC\Test2\Sales, a query object, import method Relative.

Later, the objects are imported in another repository. The path used for import ofobjects marked with Relative path is defined as \Application.

The global variable PriceList is imported as \vars\PriceList (absolute).

The query object Sales is imported as \Application\ABC\Test2\Sales (relative).

16 To export and import objects

To export and import objects


Object sets

To export a set of objects more than once, you can define an object set. You canuse object sets to export all the objects that belong to a specific application in oneobject repository to a new object repository. For more information, refer to�Object set� in Chapter 20, �Object type reference.�

To export objectsTo open the Export Objects to File dialog box, take the following steps:

1 Open the repository browser.

2 On the Objects menu, click Export.

For detailed instructions, see the online Help.

In the Export Objects to File dialog box, you can store the list of objects toexport in an object set for later use. If you defined an object set previously, youcan use the object set here to reconstruct the same list of objects that youexported earlier.

To import objectsTo open the Import Objects from File dialog box, take the following steps:

1 Open the repository browser.

2 On the Objects menu, click Import.

3 Select a file to import.

For detailed instructions, see the online Help.

If you try to import an object into a nonexisting folder, the folder is createdautomatically.

If the export contains an object with the same path and name as an object in therepository, the following happens:

� If the size, version number, and time stamp of the objects are the same, theobjects are considered identical and the object is not imported.

� If the object in the repository is older, the object is overwritten.

� If the object in the repository is newer, the user is asked if the object must beoverwritten.



A version-controlled object cannot be overwritten by an imported object, exceptwhen the object is checked out and not locked.

An object with status Protected is never overwritten by an imported object.

Component export & importThe export and import capabilities are extended to enable bulk export of alldependencies of an object or group of objects, as well as the import of only thecontribution that a component makes to each type in which the componentparticipates. To function correctly in a new repository, an imported object musthave all of its dependencies. The export of object dependencies eliminates theneed to analyze scripts and object properties to find and export dependentobjects. Each dependent object can have additional dependencies, create anextensive tree structure of dependent objects for the original exported object. Ifyou clear the Include object dependencies in export check box on the Exportdialog box, you can also export objects without their dependence. The Includepredef\sys dependencies check box causes dependent objects from thepredef\sys folder to be included. These objects are present in all repositories,therefore, these objects usually do not need to be exported.

The following figure illustrates the export user interface:



The component import enhancement enables a component�s participation invarious types to be added to those types in a different repository. Thecorresponding types in each repository can have different participatingcomponents; a normal export/import that results in objects being overwritten inthe importing repository would not be satisfactory. To manually configure thecomponent reference in each affected object in the import repository ispotentially very time-consuming.

The following figure illustrates an import UI:

Select a type object and click References , the Participating Components dialogbox appears. The components that participate in the selected type are shown inthe list box. You can now select and import the components to the type in thearchive. A type with the same name as the selected type must already exist in thearchive.



Export labeled objectsYou can export all objects in the repository that are identified by a certainversion label. For more information, see �Export labeled objects� in Chapter 17,�Version control system.�

Expression exportYou can now export all native expressions from Broker to a text file. Thisfunctionality is part of the Archive.reparse operation, to which you can now entera name for a file export expressions. If you leave this field blank or point to anillegal folder or file name, no expressions will be exported


IntroductionThe version control system (VCS) controls the versions of objects during thedevelopment process.

PurposeUsing a VCS has the following advantages:

� The VCS contains a sort of archive of old versions of objects. You can viewthe history of objects and restore older versions. All the old object versionsare saved until you explicitly discard them.

� The VCS facilitates cooperative development. If one developer is editing anobject, the other developers can continue to use the existing version of theobject. After a developer completes the editing of an object, the updatedobject is made available to all others.

� The VCS enables you to put a label on the current version of a collection ofobjects. Later, you can export the labeled version of these objects. You canalso return the objects to the state the objects had when they were labeled.

Check out and check inThe VCS uses a check-out/check-in mechanism. A developer who wants to workon a version-controlled object must first check out the object. After the developeris satisfied with the changes, the object must be checked in again.

A version-controlled object that is not checked out cannot be changed byanybody. An object that has been checked out can be edited and modified at will,but only by the user that performed the check-out operation. Other users can stilluse the existing version of the object. After the object is checked in, the newversion is available for all users.

User A wants to add two fields to a form. The user checks out the form, adds thefields, and modifies several scripts in the form. If the result looks good, the userchecks in the updated form. Thanks to the VCS system, the other users cancontinue to use the form. The user will see the old version, until user A checksthe form in again.

17 Version control system

EXAMPLE

Version control system


To set up the VCSUser dataTo give a user access to the VCS, you must edit the User object as follows:

Select the VCS check box in the User dialog box.

Only users with the appropriate access permissions can use the VCS. Users mustbe superusers before they can be given access to VCS. Users without access tothe VCS can view the version-controlled objects, but they cannot change theobjects.

Object informationTo make an object version-controlled, you must edit the object information asfollows:

1 Select an object in the object browser.

2 On the Objects menu, click Info. The object information dialog box opens.

3 On the Flags tab, select the Enable Version Control check box.

If you clear the Enable Version Control check box, the previous versions arediscarded and you lose all version information.

Multiple objects

To enable the VCS on multiple objects in a single folder, take the followingsteps:

1 Select the objects in the object browser.

2 Right-click one of the selected objects.

3 On the Version Control submenu, click Enable Version Control.

If you do not see the Version Control submenu, you do not have access to theVCS.

Objects that cannot be version controlled are ignored. A folder cannot be versioncontrolled. The Enable Version Control option only affects the objects that areselected directly. The option does not affect the objects inside a selected folder.

You can enable version control on multiple objects from any number of foldersor even the entire object repository in a single action by using The ChangeObject Storage Flags dialog box.

NOTE



You can display this dialog box by means of the setFlags operation of theArchive object. This operation has the following specification:

VOID Archive::setFlags (VOID)

To open the Change object storage flags dialog box, take the following steps:


2 Enter the following expression in the Tool Dock's Expression tab:Archive . setFlags

3 Click Evaluate.

4 In the Change Object Storage Flags dialog box, add or remove objects fromthe Objects to change list, until you are satisfied with the resulting selection.

5 Select the Set Version Control System Flag check box.

6 Select the Version Control System check box.

7 Click OK.

Tip

To make operations such as this more readily available to you, you can put theseoperations in a menu. For more information, refer to �Menu� in Chapter 20,�Object type reference.�

VCS object

If an object enters the VCS, a VCS object is created in the VCS system folder,\sys\vcs. A VCS object has a unique name, which starts with the prefix VCSO.The system uses VCS objects to store information on versions for specificobjects. You must not edit or delete the objects in the VCS system folder.

Objects not under version controlAs long as an object is not placed under version control, the object can be editedwithout restrictions. Older versions of the object are not stored.

Several types of objects cannot be version controlled, for example, documents,messages, and system objects.



To view information about version-controlledobjectsIf an object is version controlled, you can view the following information on theVCS tab of the repository browser's object information box:

� The lock status and the related lock description.� The check-out status, and when and by whom the object was checked out.� The number of stored versions.

To find detailed information about stored versions, you can use the Show historycommand. To use this command, take the following steps:

1 Right-click an object in the object browser.

2 On the Version Control shortcut menu, click Show History.

3 Select a version

4 Click Details to display any check-in comments for a version.

The Show History dialog box shows every version of the object and severalactions that were performed on the object.

The Created action indicates when an object becomes version controlled, not thecreation of the object itself.

Check out, check in, undo check outA version-controlled object must be checked out before it can be edited. Only theuser that checked the object out can edit it.

Check out

To check out an object or a group of objects, take the following steps:

1 Select one or more objects in the object browser.


3 On the Version Control submenu, click Check out.

The selected objects are checked out.

NOTE



Check in

If you are finished editing, you must check the object in. The newly-editedversion becomes the current version, which is available to other users. If youcheck an object in, you must enter a short description of the changes.

To check in an object, click Check in on the Version Control submenu.

The old version is stored in a compressed format in the VCS system folder,\sys\vcs. Old versions are stored as a file whose name starts with the prefixVCSV. You can still access an old version by using a get or rollback operation.

Undo check out

If you do not want to save the changes that you have made to a checked outobject, you can use the Undo check out operation. The existing version of theobject is left intact and the checked out version is discarded.

To undo a check out, click Undo Check out on the Version Control submenu.

LockingNo user can delete, edit, or change an object that is locked. A locked objectcannot be checked out until the object is unlocked. Users with access to the VCScan unlock any object�even the objects that were locked by other users.

Locking can be useful if you are working on objects that are dependent on anumber of other objects. This is explained in the following example.

You are working on forms that depend on a number of logical data types. You donot want anybody to change these logical data types while you are still workingon the forms. In this case, you can lock the logical data types.

Lock

To lock an object or a group of objects, take the following steps:



3 On the Version Control submenu, click Lock.

4 Enter a description of the reason for locking the object.

The selected objects are locked.

The lock description is displayed on the VCS tab in the repository browser'sObject Information dialog box.

EXAMPLE



Unlock

To unlock an object, on the Version Control submenu, click Unlock.

LabelsTo put labels on objectsTo keep track of object versions, you can put a label on a version. This action isespecially useful if you put a label on all objects that belong to a certainapplication or subsystem. After you label the objects, you can recreate thehistoric version of the application or subsystem exactly as the version was on thedate and time of labeling.

For best results, you must label your objects regularly during the developmentprocess, because you cannot put labels on older versions afterwards.

After you use a certain label, you can no longer place the same label on otherobjects. You cannot add objects to an existing label.

To label an object or a group of objects, take the following steps:

1 Make sure that all objects that must be labeled are checked in. You cannotlabel objects that are checked out, but you can label locked objects.



4 On the Version Control submenu, click Label.

5 Enter a string in the Label Object dialog box. You must enter a string thathas not been used as a label before.

6 Click OK.

Label multiple objects

To label multiple objects from any number of folders, or even the entire objectrepository, in a single action, use the Label Objects dialog box. To start thisdialog box , you can use the multiLabel operation of the Archive object. Thisoperation uses the following syntax:

VOID Archive::multiLabel (VOID)

NOTE



To open the Label Objects dialog box, take the following steps:


2 Enter the following expression in the Tool Dock's Expression tab:Archive . multiLabel

3 Click Evaluate.

4 In the Label Objects dialog box, add or remove objects from the Objects toLabel list, until you are satisfied with the selection.

5 Click OK.

Tip

You can make operations such as this more readily available to you by puttingthese operations in a menu. For more information, refer to �Menu� in Chapter 20,�Object type reference.�

Technically, a label is stored as a version that is identical to the label�spredecessor.

To use labelsYou can perform the following actions on labeled object versions:

� Export the objects to a file. For more information, refer to �Export andimport� in this chapter.

� Make the labeled object version the actual version. For more information,refer to �Restore old object versions� later ins this chapter.

� Permanently remove the labeled version and older stored versions from theVCS. For more information, refer to �Discard old object versions� later inthis chapter.

You can execute these actions by means of the Export Labelled Objects to Filedialog box. This dialog box is started by means of the exportLabel operation ofthe Archive object. This operation uses the following syntax:

VOID Archive::exportLabel (VOID)



To open the Export Labelled Objects to File dialog box, take the followingsteps:


2 Enter the following expression in the Tool Dock's Expression tab:Archive . exportLabel

3 Click Evaluate.

Tip

To make operations such as this more readily available to you, you can put theseoperations into a menu. For more information, refer to �Menu� Chapter 20,�Object type reference.�

Restore old object versionsGetIf you use the Get command, you can retrieve an old object version and make theversion the current version. All other versions are left intact. In other words, youput the selected object version on top of the object stack. You have two differentGet commands:

� The Get command for a single object.� The Get command that works on all objects with a certain label.

To use the Show History command to perform a Get operation on a singleobject, take the following steps:


2 On the Version Control submenu, click Show History.

3 Select a version.

4 Click Get.

To perform a Get operation on all objects with a certain label, you must open theExport Labelled Objects to File dialog box. The �Labels� section later in thischapter describes how you can open this dialog box. To retrieve this version,select a label and click Get.



RollbackThe Rollback command restores an older version of an object, and discards alllater changes. Use this command with caution, because you cannot undo thiscommand. To perform a Rollback operation, take the following steps:


2 On the Version Control submenu, click Show History

3 Select a version.

4 Click Rollback.

Export and importImpact of VCS on export and importThe export operation does not export any version information. If you importobjects, the imported objects are initially not version controlled.

You can import an object over an existing version-controlled object if thefollowing conditions are met:

� The object is checked out.� The object is not locked.

Export labeled objectsTo export all objects in the repository that are identified by a certain label, takethe following steps.

1 Open the Export Labelled Objects to File dialog box:


3 Enter the following expression in the Tool Dock's Expression tab:Archive . exportLabel

4 Click Evaluate.The Export Labelled Objects to File dialog box opens.

5 Enter the path for the export file.

6 Enter the name of the export file.

7 Select a label.

8 Click Export.



For more information on exporting and importing, see Chapter 16, �Exportingand importing of objects.�

Discard old object versionsIf you are sure that you no longer need old object versions, you can delete theversions to save space. To delete old versions, take the following steps:

1 Open the Export Labelled Objects to File dialog box (see previous section).2 Select a label.3 Click Discard.

The Discard command deletes the versions with the specified label as well as allolder versions. If older labels exist, you must also discard these labels to save thespace that is taken up by these labels.


IntroductionThe Baan OpenWorld Broker logs several types of events in a database. Forexample, an error that occurs during database access, or the receipt of a message.

The logging system can be used to investigate what has happened in the system.Among others, the logs can be used by the following users:

� Help desk employees who offer customer support.� Developers who debug applications.� System administrators who investigate the performance of the system or

maintain security.

You can specify in a very detailed way which events must be logged. If theBroker is released, logging is turned off. You can turn logging on in the serverconfiguration utility. The logging system maintains logs for several subsystems,as indicated in the following table:

Logging subsystemsLog code Subsystem Eventssys System Logging on to the system. Use of a wrong

password. Selection of menus by users.cis Component

integrationExceptions and other events in theoperations defined in logical data types, forexample, the primitive operations Load,Store, and so on. Errors in the execution ofiterators.

odbc Databaseconnections (ODBC)

ODBC events, such as database queries,for database connectors and file objects.

periodic Periodic control Events associated with running alerters andperiodic processes, and recalculating timedvariables.

inet Internet and e-mail Events related to the Internet and the e-mailsystem.

msg Broker messages Events related to the message queue.com COM/OLE Events related to the use of the Broker's

OleObject class to access Microsoft COMAutomation objects.

18 Logging system

Logging system


You can add user-defined logs to the logging system.

The events are logged in database tables in ODBC-compliant database systems,for example, Microsoft SQL Server. If you do not use a database, for example ifthe database connectors have been deleted, the logging system logs the events intext files on the server's working directory. If the database connection of thelogging system fails, an event is logged in the Windows NT event log.

The workflow system has an individual logging system which records eventsrelated to documents.

Error levels

Three error levels are distinguished:

� Critical error.� Noncritical error.� Warning.

You can also log successful operations, for example, the successful execution ofa Load operation.

To set up the logging systemDatabase connectorsYou must first create the database connectors for the logs. These databaseconnectors must be stored in the \sys\logging repository folder. To use a singledatabase connector for multiple logs, the name of the database connector must beDefault. To have separate database connectors for each log, the databaseconnector must have the name of the log, for example, \sys\logging\cis or\sys\logging\odbc.

You can use the Database Connectors for Logging dialog box to manage thesedatabase connectors. To open this dialog box, on the Baan OpenWorld Brokermenu, point to Logging, and click Database Connectors.

The Baan OpenWorld menu is contained in the Broker's default menu. Thismenu is not visible if the repository browser is open.

If the system does not find a specific database connector for a log, the loggingsystem uses the \sys\logging\default database connector.

NOTE

Logging system


If the program logs for the first time, the program creates the logging tablesautomatically. The logging table in the database systems are namedbis_logging_xxx, where xxx is the name of the log.

If you must change the database connectors, the change will be active after yourestart the Broker service.

If you do not use a database, for example, if the database connectors have beendeleted, the program uses text files instead. The logging system creates the textfiles on the server's working directory, for example, bis_logging_odbc.log, orbis_logging_cis.log.

If the database connection of the logging system fails, an event is logged in theWindows NT event log.

Configuration utilityTo start and stop the logging for each log in the configuration utility, take thefollowing steps:





5 On the Logging tab, select the check boxes for which you want to activatethe logging system.

Component integration logYou can use the following types of objects to specify the events that must belogged for the component integration subsystem:

� Components.� Logical data types.� Iterators.

NOTE

Logging system


You must specify the error levels that must be logged for each of these objects.You can select the following options.

Logging optionsProperty DescriptionSuccess (checkbox)

Specifies that a log entry will be generated each time aspecified operation runs successfully.

Failure Specifies that a log entry will be generated each time aspecified operation fails. You can use the option buttonsto specify the level of logging.

Logged error level Specifies the class of errors that will generate a log entry.This property can have the following values:� Only critical errors.� All errors.� Warnings and errors.

To specify this information for components and iterators, take the followingsteps:

1 Double-click the component or the iterator in the repository browser.

2 Click the Logging tab.

3 Select an operation.

4 Specify the logging options.

To specify this information for logical data types, take the following steps:

1 Select the logical data type in the repository browser.

2 On the Objects menu, click Info.

3 Click the Flags tab.

4 Specify the logging options.

Logging system


If you specify various error levels for logical data types and components, themost restricted specification is used. The reason for this is explained with thefollowing example.

Example logging specificationObject Logged eventsSalesPerson (logical data type) All errorsCustomerRow (logical data type) Warnings and errorsComponent FinApp / Load operation Success and Warnings and errorsComponent SalesApp / Load operation Only critical errors

A SalesPerson object and a CustomerRow object are loaded. Both componentsparticipate in the load operation. The following events will be logged:

Example of logging a load operationLoaded object Component Logged eventsSalesPerson FinApp ErrorsSalesPerson SalesApp Only critical errorsCustomerRow FinApp Warnings and errorsCustomerRow SalesApp Only critical errors

ODBC operations

The integration operations can involve ODBC-commands on databases. If youactivated the odbc log, these operations are always logged in the odbc log,independent of the settings for the component integration log.

User-defined logsYou can define your own log in addition to the standard logs. You can also usethe scripting language operation System::addToLog to record events in this log.To set up a user-defined log, you must create a database connector in the\sys\logging\ folder. The name of this database connector is the name of the log.

For more information, refer to �System::addToLog� in the documentScriptingLanguage Reference (U7278D US).

Logging system


The data in the logsThe logging tables have the following structure.

Log data layoutName Type DescriptionDate_Time Datetime Date and time when the event was logged.Error_Level Varchar (20) Error level of event (success, critical error,

error, or warning).Exception Smallint Specifies whether the event is an exception.UserID Varchar (80) User logged on to the system when the event

occurred.Workstation Varchar (80) The name of the workstation where the event

occurred.Object Varchar (125) The object that caused the event.JobID Integer Identification of a process. For example, an

identification of the run of an iteration.UserDefined Integer User-defined number.NativeError Integer Native error code.

Native error codes can originate fromcomponents that participate in logical datatypes.

Component Varchar (32) Code of the participating component (if any).Code Varchar (32) Code of an object in the component

integration subsystem. For example, acustomer code or a product code.

Operation Varchar (32) The primitive operation in the componentintegration subsystem, for example, Load,Store, StoreNew.

LanguageCode Varchar (10) The code that identifies the type of event. Youcan use this code to translate the eventdescription to other languages.

Description Varchar (256) Description of the event.Message Varchar (256) Message or event.

Logging system


The log event viewerThe log event viewer enables you to view, filter, and delete the various logs. The\sys\logging\default database connector must first be configured to connect to thedesired file server.

To open the event viewer, on the Baan OpenWorld Broker menu, point toLogging, and click Error Logs.

This menu is contained in the Broker's default menu. This menu is not visiblewhen the repository browser is open. The menu command opens the predefined\apps\logging\LogForm form.

Logging System EnhancementsDesign Overview

Three new operations are now available in the scripting language for the LoggingSystem that are now available.

� System . setLoggingKind - to set up the logging kind.

� System . setLoggingBatchSize - to set up the batch size.

� System .commitLog - to commit the batch records to a database

There is a COM object interface for the Logging System named IBaanLogSys.The COM object handles all database access for the Logging System and has thefollowing methods defined. The first three methods were already mentionedearlier:

� setLoggingKind.

� setLoggingBatchSize.

� commitLog.

Secondly, five new methods for the ITK log tables:

� addToITKJobLog - to log to the ITK Job log.

� updateITKJobLog � to update timestamps and so on.

� addToITKTaskLog � to log to the ITK task log

� updateITKTaskLog � to update timestamps and so on.

� addToITKTransactionLog � to log to the ITK Transaction log.

NOTE

Logging system


And finally, a method to add records to the IS log database:

� addToLogAdvanced � to add to the IS logs.

The operations and the COM objects interface are explained in detail inChapter 19, �COM interfaces.�

Design Approach

These enhancements include the following :

� Capability to enable the developer, who implements applications in BaanOpenWorld Broker, and other users, to decide when the logs are written tothe database. To insert a record onto a database is an expensive operation. Bysetting up a batch and enabling the program to commit to a database afterrunning some script/batch can optimize the process.

Exposing the logging system as a COM object enables you to use the LoggingSystem in other applications.

Design entities

Operations

Several new operations will be available for the logging system. Some operationsenable you to work with the batch support, and others will log to the database. Asubset of these operations is accessible trough the scripting language, asdescribed in the sections from �setLoggingKind� to �addToLogAdvanced� laterin this chapter. You can access all of the operations through the COM interfacedescribed in �COM Objects� later in this chapter.

setLoggingKind

Parameters:

� String strSubsystem: The name of the logging subsystem, or ITK table, which refers to the nameof the database that is logged to both the database connector and the tablename in the database.

� Number nKind:A number that determines how/where the records are logged. A value of oneindicates that the records must be stored in a database only, with text file asback-up. A value of two indicates that the records must be stored in a textfile. These values can be combined and used simultaneusly.

Logging system


setLoggingBatchSize

Parameters:

� String strSubsystem:The name of the logging subsystem, and refers to the name of the databasethat is logged to both the database connector and the table name in thedatabase.

� Number nBatchSize:The number of records to keep in memory/flat file before committing to adatabase.If the number is zero, then the system will not commit to the database untilthe System::commitLog operation is called or the system shuts down. In otherwords, if the Logging System object must be deleted, then the commitoperation is prerformed if records still exist in memory. If the number is setto one, then there will be no batch. As a result, every record is written directlyto the database.If the number is larger than one, the system stores the selected number ofrecords in memory before commiting the records to a database. In all cases,all records in memory are committed to the database if the system must beshut down.

commitLog

Parameter:

� String strSubsystem:The name of the logging subsystem/database on which the commit operationmust run.

� An option enables you to manually commit the records in memory to adatabase by calling this operation. If the batch size is set to zero, then you canassume that this operation will be called manually. This operation can alwaysbe called if required.

AddToLogAdvanced

This operation logs to the IS log database, or alternatively a text file. Anoperation exists to enable you to perform this function, however, this operationhas more parameters. More fields in the database are set at once.

Parameters:

� String Subsystem - The subsystem or table name.

� String UserId - The user ID.

Logging system


� String WorkstationId - The workstation ID.

� Number ErrorLevel - Error level.

� Number Exception -Is the number an exception?

� String Object- Object name/path.

� String LanguageCode - Code to map between languages.

� String Code - Customer/product/account�.

� String Component - Component identifier.

� String Operation - Operation that originates the event.

� Number JobID - The ID of the job that originates the event.

� Number UserDefEventNo � User-defined event number.

� Number NativeEventNo - Native error codes from, for example, integrationcomponents.

� String Description - Description of the event.

� String Message - The event message.

These parameters/fields are explained in more detail in the Logging Systemtechnical design specification.

COM objects

The Logging System object

The Logging System will now be a separate/standalone COM Object that anyonecan use. The interface IBaanLogSys defines this COM object.

The COM object handles all database access for the Logging System. Severalmethods on this object enable you to insert events to the Logging Systemdatabases. BaanEAI IS uses this COM object to insert into the logging tables.The existing logging mechanism has been moved from BaanEAI IS to this COMobject. The check for the logging flags for each named object and primitiveoperations in IS will still be carried out on the IS server, however, the insertoperations and batch storage are carried out in the COM object.

New operations for logging to the ITK log tables have also been added.

The Logging System object will use Microsoft ActiveX Data Object Recordsetlibrary to work with the database and this COM Object will be written inMicrosoft Visual Basic 6.0.

Logging system


DNS Configuration

The snap-in DLL for the configuration utility will change. One data source willbe setup in the snap-in for the logging subsystems.

Figure 12. Logging System Configuration.

addToLog

This method does the same as the operation System::addToLogAdvance, asexplained in the previous section, �addToLogAdvanced.�

Parameters:

� [in] BSTR bstrSubsystem.

� [in] BSTR bstrUserId.

� [in] BSTR bstrWorkstationId.

� [in] long lErrorLevel.

� [in] bool fException.

Logging system


� [in] BSTR bstrObject.

� [in] BSTR bstrLanguageCode.

� [in] BSTR bstrCode.

� [in] BSTR bstrComponent.

� [in] BSTR bstrOperation.

� [in] long lJobID.

� [in] long lUserDefEventNo.

� [in] long lNativeEventNo.

� [in] BSTR bstrDescription.

� [in] BSTR bstrMessage.

Again, these parameters/fields are explained in the Logging System TCspecification.

addToITKJobLog

A method for adding records to the ITK Job table (see ITK merge specification).

Parameters:

� [in] long lJobId.

� [in] date dJobStart.

� [in] date dJobEnd.

� [in] long lJobStatus.

� [in] BSTR bstrProfileName.

� [in] long lJobExecStatus.

� [in] BSTR bstrNote.

Logging system


updateITKJobLog

A method to update records in the ITK Job table (see ITK merge specification).

Parameters:


� [in] date dJobEnd.


� [in] long lJobExecStatus.

addToITKTaskLog

A method to add records to the ITK Tast table (see ITK merge specification).

Parameters:

� [in] long lTaskId.


� [in] BSTR bstrCompInstSrcName.

� [in] BSTR bstrCompInstDstName.

� [in] BSTR bstrClassSrcName.

� [in] BSTR bstrClassDstName.


� [in] long lTaskType.

� [in] date dTaskStart.

� [in] date dTaskEnd.


updateITKTaskLog

A method to update records in the ITK Task table (see ITK merge specification).

Parameters:



� [in] date dTaskEnd.


Logging system


addToITKTransactionLog

A method to add records to the ITK Transaction table (see ITK mergespecification).

Parameters:

� [in] long lTransactionId.


� [in] date dTransDate.

� [in] long TransAcType.

� [in] BSTR bstrJobStatus.


� [in] BSTR bstrSource.

� [in] BSTR bstrTarget.


IntroductionPurpose of the COM interfacesTo expose services to COM clients, the Baan OpenWorld Broker uses COMinterfaces. A COM interface enables external programs access to the objects inthe object repository. You can create a program, for example, in a MicrosoftOffice application, to execute an operation from an object in the repository.

After you establish a logon session and a connection to the repository, you have anumber of possibilities:

� Evaluate expressions, which offers you all the power of the scriptinglanguage.

� Create and manipulate instances of logical data types.

� Access objects and folders to retrieve information about objects. In thisrelease of the COM components, objects are read-only.

� Use the code map to translate object codes between integrated applications.For example, you can translate the supplier code in one application to abusiness-partner code in another application.

More features are described in the sections about each interface.

COM Automation

This chapter describes how external applications can access the functions of theBroker. The opposite is also possible. You can use the operations of theOleObject class in the Broker's scripting language to access Microsoft COMAutomation objects. For example, you can address a cell in a Microsoft Excelspreadsheet. The OleObject class is described in the document ScriptingLanguage Reference (U7278D US).

19 COM interfaces

COM interfaces


COM componentsThe COM interfaces are implemented by a number of COM components orco-classes.

The following table lists the co-classes.

CoclassesClass DescriptionBaan.IntegrationServer

The starting point for obtaining a Baan.Connectioncomponent.

Baan.Connection A connection to a server.Baan.Repository An object for operating on the Broker repository.Baan.Object A general Broker repository object.Baan.Attributes A set of object attributes.Baan.Folder A repository folder.Baan.Type A logical type (Row, Table, Array or Enum).Baan.Value An instance of a logical type.Baan.CodeMap A connection to the central code (instance) mapping service.

The Baan.IntegrationServer class is the starting point for using the Broker'sservices. Baan.IntegrationServer is the only class for which you can useCoCreateInstance from a COM client to directly create instances. Instances ofother classes can be directly created, but will not do anything. Such instancesmust be created through properties and methods on other already existinginstances.

The coclasses implement a number of interfaces, for example,IBaanIntegrationServer, IBaanConnection, and IBaanRepository. The propertiesand methods that these interfaces offer are described later in this chapter.

If you register the bsrvitf.DLL file on your computer, you can access theseproperties and methods from within any COM client.

COM interfaces


How to use the COM interfacesYou can use the COM components with several tools and programminglanguages. Use the documentation of the tool you use to find the proper way toaccess COM objects with that tool. For example, the procedure to use the COMcomponents to connect to the Broker in a Visual Basic for Applications (VBA)program includes the following steps:

1 Install the bsrvitf.DLL file on your computer.

2 Run regsvr32 to register all COM objects implemented in bsrvitf.DLL in yoursystem registry.

3 Open a Microsoft Word document.

4 Press ALT+F11 to start the Visual Basic editor.

5 On the Tools menu, click References.

6 Select the appropriate type library or DLL file, for example, bsrvitf 1.0 TypeLibrary.

You can now use all the COM objects from that DLL in your VBA code. VBA'sobject browser shows you all the available COM objects with the objects�methods and parameters.

COM interfaces


Co-classesThe following co-classes (COM components) are implemented:

Class DescriptionBaan.IntegrationServer The starting point for obtaining a Baan.Connection

component. This is the only class for which the usercan use CoCreateInstance from a COM client todirectly create instances. You can create instancesof other classes, however, the instances will not doanything. You must create these instances throughproperties and methods on other, already-existinginstances.

Baan.Connection A connection to a server.Baan.Repository An object for operating on the BOW repository.Baan.Object A general BOW repository object.Baan.Attributes A set of object attributes.Baan.Folder A repository folder.Baan.Type A logical type: Row, Table, Array, or Enum.Baan.Value An instance of a logical type.Baan.CodeMap A connection to the central code (instance) mapping

service.Baan.Periodic A periodic process object.Baan.Profile A Profile object.

COM interfaces


The following interfaces are implemented:

Interface Description Implemented byIBaanIntegrationServer An interface to log on to

the repository serverBaan.IntegrationServer

IBaanConnection A control interface on aserver connection

Baan.Connection

IBaanRepository A request interface on arepository server

Baan.Repository

IBaanAttributes An attribute set for anobject

Baan.Attributes

IBaanObject An object retrieved froma repository

Baan.Object

IBaanFolder A request interface on arepository folder

Baan.Folder

IBaanType A logical type retrievedfrom a repository

Baan.Type

IBaanValue An instance of a logicaltype

Baan.Value

IBaanCodeMap A connection to theCodeMap object

Baan.CodeMap

IObjectSafety The IObjectSafetyinterface enables a clientto retrieve and set aCOM object's safetylevels. For example, aweb browser may callIObjectSafety::SetInterfaceSafetyOptions to makea control safe forinitialization or safe forscripting.

Baan.ServerBaan.ConnectionBaan.RepositoryBaan.TypeBaan.ValueBaan.Periodic

IBaanPeriodic A periodic process object Baan.PeriodicIBaanProfile A Profile object Baan.Profile

COM interfaces


InterfacesThe following table shows the implemented interfaces.

InterfacesInterface Description Implemented byIbaanIntegrationServer

An interface to log on to therepository server

Baan.IntegrationServer

IbaanConnection A control interface on a serverconnection

Baan.Connection

IbaanRepository A request interface on a repositoryserver

Baan.Repository

IbaanAttributes An attribute set for an object Baan.AttributesIbaanObject An object retrieved from a

repositoryBaan.Object

IbaanFolder A request interface on a repositoryfolder

Baan.Folder

IbaanType A logical type retrieved from arepository

Baan.Type

IBaanType2 IBaanType2 interface extends theIBaanType interface.

IbaanValue An instance of a logical type Baan.ValueIbaanCodeMap A connection to the CodeMap

objectBaan.CodeMap

IbaanPeriodic The interface enables externalclients to change the periodicprocesses settings

IbaanProfile The interface encapsulates a singleprofile object as represented on therepository server

IobjectSafety The IObjectSafety interfaceenables a client to retrieve and seta COM object's safety levels.For example, a web browser maycallIObjectSafety::SetInterfaceSafetyOptions to make a control safe forinitialization or safe for scripting.

Baan.IntegrationServerBaan.ConnectionBaan.RepositoryBaan.AttributesBaan.ObjectBaan.FolderBaan.TypeBaan.ValueBaan.CodeMap

COM interfaces


Overview exampleThe following example in VBA gives you a quick idea of how you can use theBroker's COM components to access the repository and the objects in therepository.

This section describes the details for each interface.

To connect to the repository

The following example shows how you can set up a connection with therepository.

‘ Create a new instance of the BaanIntegrationServer

‘ class:

Dim Server As New BaanIntegrationServer

‘ The IP address and port of the Repository server:

Server.Address = "10.2.59.235:7250"

‘ Create a BaanConnection object to represent

‘ a logon session and logon:

Dim Conn As BaanConnection

Set Conn = Server.LogonAsUser("UserName", "Password", "")

‘ Connect to the repository

Dim Rep As BaanRepository

Set Rep = Conn.Repository

Expressions

The following code fragment shows how you can evaluate an expression.

Dim strResult As String

strResult = Conn.Evaluate ("Time () . asString ()")

Repository objects

The following code fragment shows how you can access an object.

‘ Fetch an IBaanObject interface on an object

‘ stored in the repository:

Dim obj As BaanObject

Dim strName As String

strName = "\MyObject"

obj = Rep . Object (strName)

COM interfaces


Logical data types

The following example shows how you can work with types and values.

‘ Create a BaanType object:

Dim MyType As BaanType

Set MyType = Rep.Object ("\MyType")

‘ Create a new instance of this type:

Dim MyValue As BaanValue

Set MyValue = MyType.New ()

‘ Load the instance with code "010" from the

‘ "BAANERP" component:

Dim MyOtherValue As BaanValue

Set MyOtherValue = MyType.Load ("BAANERP", "010")

‘ Get the GUID code for this value:

Dim strGUID As String

strGUID = MyOtherValue.GUID

IBaanIntegrationServerThe Baan.IntegrationServer COM class implements the IBaanIntegrationServerinterface. Baan.IntegrationServer is the only COM class that can be createddirectly, and as a result is always the starting point when you use the COMinterfaces to access a repository server. The LogonAsUser method is the onlyway to obtain a usable Baan.Connection COM class.

The IBaanIntegrationServer interface has the following properties and methods.

IBaanIntegrationServer propertiesProperty Type DescriptionAddress BSTR (String) Sets/gets the IP address of the Repository

server. The IP address can be either a raw IPaddress (10.11.12.13) or a DNS name(bis.baan.com). The IP address can beoptionally suffixed by a colon and a portnumber. The default port number is 7250decimal.

COM interfaces


IBaanIntegrationServer methodsMethod DescriptionLogonAsUser Log on to the repository server.Logon Log on to the Repository server with a default user name and

password. You do not need to enter a user name andpassword).Note: This method will be implemented in a future release.

LogonDlg Log on to the Repository server using a dialog box to enteruser name and password.Note: This method will be implemented in a future release.

Properties and methods

1 Address (propget).

[out, retval] BSTR* pbstrAddress: Retrieves the IP address of the repositoryserver.

S_OK if successful, E_INVALIDARG if the pbstrAddress parameter is NULL.

Dim Server As New BaanIntegrationServer ‘ Create anew instance of the BaanIntegrationServer class.Dim Conn As BaanConnectionServer.Address = "10.2.59.235:7250" ‘ The IP address andport of the Repository server.Dim strAddress As StringstrAddress = Server.Address

2 Address (propput).

[in] BSTR bstrNewAddress: The IP address of the repository server.

S_OK if successful, E_INVALIDARG if the bstrNewAddress parameter isNULL.

Dim Server As New BaanIntegrationServer ‘ Create anew instance of the BaanIntegrationServer class.Dim Conn As BaanConnectionServer.Address = "10.2.59.235:7250" ‘ The IP address andport of the Repository server.

3 LogonAsUser.

� [in] BSTR bstrName: The user name

� [in] BSTR bstrPassword: The password

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

COM interfaces


� [in] BSTR bstrCompany: The company code, can be empty.

� [out, retval] IBaanConnection** ppConnection: Queries for anIBaanConnection interface.

S_OK if successful or custom error. Refer to Chapter 5, �Error Handling�.

Dim Server As New BaanIntegrationServer ‘ Create anew instance of the BaanIntegrationServer class.Dim Conn As BaanConnectionServer.Address = "10.2.59.235:7250" ‘ The IP address andport of the Repository server.Set Conn = Server.LogonAsUser(“UserName”, “Password”,“Company”)

4 Logon.

[out, retval] IBaanConnection** ppConnection: Queries for an IBaanConnectioninterface.

Return value: S_OK if successful or custom error. Refer to Chapter 5, �ErrorHandling.�

Dim Server As New BaanIntegrationServer ‘ Create anew instance of the BaanIntegrationServer class.Dim Conn As BaanConnectionServer.Address = "10.2.59.235:7250" ‘ The IP address andport of the Repository server.Set Conn = Server.Logon()

5 LogonDlg.

[out, retval] IBaanConnection** ppConnection: Queries for an IBaanConnectioninterface.

E_NOTIMPL.

IBaanConnectionThe IBaanConnection interface represents one session between a client and therepository server. The IBaanConnection interface is only available through theLogonAsUser method of the IBaanIntegrationServer interface, and the only wayto obtain the IBaanRepository interface is through the Repository property of thisinterface. The IBaanConnection interface implements the Evaluate method thatenables clients to evaluate a IS-expression on the repository server.

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


The IBaanConnection interface has the following properties and methods.

IBaanConnection propertiesProperty Type DescriptionRepository Reference to an

IBaanRepositoryobject

Retrieves the IbaanRepositoryinterface associated with thisconnection. Clients use theIBaanRepository interface to accessthe objects in the repository server.This is a read-only property.

CodeMap Reference to aIBaanCodeMapobject

Retrieves the CodeMap object, whichhas operations that you can use toadd, delete, modify, and lookup itemsin the code map table. This is a read-only property.

ErrorDescription BSTR (String) Obtain a description of the last error.ErrorType BSTR (String) Obtain the type of the last error.ExceptionType BSTR (String) Obtain the type of the last exceptionExceptionDescription BSTR (String) Obtain the description of the last

exception

IBaanConnection methodsMethod DescriptionEvaluate Evaluate a IS expression on the repository server.Close Close the connection and prevent any further operation on it.

Properties and Methods

1 Repository.

[out, retval] IBaanRepository** ppRepository: Receives the repository object.

S_OK if successful, E_FAIL otherwise.

Dim Server As New BaanIntegrationServer ‘ Create anew instance of the BaanIntegrationServer class.Dim Conn As BaanConnectionServer.Address = "10.2.59.235:7250" ‘ The IP address andport of the Repository server.Set Conn = Server.LogonAsUser(“UserName”, “Password”,“Company”)Dim rep As BaanRepositorySet rep = Conn.Repository

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


2 CodeMap

[out, retval] IBaanCodeMap** ppCodeMap: Receives the CodeMap object.


Dim CodeMap As BaanCodeMapSet CodeMap = Conn.CodeMap

3 ErrorDescription.

[out, retval] BSTR* pbstrDescription: Receives the last error description

S_OK.

See below.

4 ErrorType.

[out, retval] BSTR* pbstrErrType: Receives the last error type. The error typecan be one of the following:

� No error.� Syntax error.� Runtime error.� Undefined error.

S_OK.

See below.

5 ExceptionType

[out, retval] BSTR* pbstrExcType: Receives the last exception type. Theexception type can be one of the following; �No exception,� �User breakexception,� �Evaluation exception,� �User defined exception� or �Undefinedexception.�

S_OK.

See below.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


6 ExceptionDescription.

[out, retval] BSTR* pbstrExcDescr: Receives the last exception description.

S_OK.

Dim Conn As BaanConnectionSet Conn = Server.LogonAsUser(“UserName,” “Password”,“Company”)Dim strErrorDescripton As StringDim strErrorType As StringDim strExcType As StringDim strExcDescription As StringDim strResult As StringstrResult = Conn.Evaluate (“Time () . asString ()”)strErrorType = Conn.ErrorTypeIf (strErrorType <> “No error”) Then

‘ Check the errorMsgBox (“Error type: “ & strErrorType)strErrorDescription = Conn.ErrorDescriptionMsgBox (“Error description: “ & strErrorDescription)If (strErrorType = “Runtime error”) Then

strExcType = Conn.ExceptionTypestrExcDescription = Conn.ExceptionDescriptionMsgBox (“Exception type: “ & strExcType)MsgBox (“Exception description: “ &

strExcDescription)End If

End If

7 Evaluate.

� [in] BSTR bstrExpr: The IS expression.

� [out, retval] BSTR* pbstrRetVal: Receives the result of the IS expression.

S_OK if successful, E_FAIL if the BaanConnection object has not been obtainedthrough the LogonAsUser method of the IBaanIntegrationServer interface, if theconnection to the Repository server is unavailable, or if the expression is invalid.

Dim Server As New BaanIntegrationServer ‘ Create anew instance of the BaanIntegrationServer class.Dim Conn As BaanConnectionServer.Address = "10.2.59.235:7250" ‘ The IP address andport of the Repository server.Set Conn = Server.LogonAsUser(“UserName”, “Password”,“Company”)

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


Dim strResult As StringstrResult = Conn.Evaluate (“Time () . asString ()”)

8 Close.

This operation always returns S_OK.

IBaanRepositoryThe IBaanRepository interface models a repository server. Through thisinterface, a client can fetch objects by name and enumerate through repositoryfolders and perform other maintenance operations.

The IBaanRepository interface has the following properties and methods.

IBaanRepository propertiesProperty Type DescriptionCodeMap Reference to an

IBaanCodeMapinterface object

Retrieves the CodeMap object, which hasoperations that can be used to add,delete, modify, and lookup items in thecode map table. This is a read-onlyproperty.

IBaanRepository methodsMethod DescriptionObject Fetches an IBaanObject interface on an object stored in the

repository.Folder Query for an IBaanFolder interface in the repository by the name

of the folder.ResetCache Resets the internal object cache. This ensures that all objects are

fetched from the server the next time they are accessed and notfrom the internal object cache.


1 CodeMap.

[out, retval] IBaanCodeMap** ppCodeMap: Receives the CodeMap object.


Dim CodeMap As BaanCodeMapSet CodeMap = rep.CodeMap

RETURN VALUE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


2 Object.

� [in] BSTR bstrPath: Name and location (full path) of the object.

� [out, retval] IBaanObject** ppObject: Interface to the object.

S_OK if successful, E_INVALIDARG if either bstrPath or ppObject are NULL,E_FAIL if the connection to the repository server is unavailable orE_OUTOFMEMORY if there is not enough memory to create the object. Notethat this method returns S_OK, but sets the outgoing pointer to NULL if theobject is not found in the repository.

Dim obj As BaanObjectDim strName As StringstrName = “\MyObject”obj = rep . Object (strName)

‘ Test if the object exists in the repositoryIf (obj Is Nothing) Then

‘ The object was not found in the repositoryMsgBox (“The object “ & strName & “ does not exists”)

End If

3 Folder.

� [in] BSTR bstrPath: The folder name.

� [out, retval] IBaanFolder** ppFolder: Receives the IBaanFolder interface.

S_OK if successful, E_INVALIDARG if either bstrPath or ppFolder are NULL,E_FAIL if the connection to the repository server is unavailable orE_OUTOFMEMORY if not enough memory exists to create the folder. Note thatthis method returns S_OK but sets the outgoing pointer to NULL if the folder isnot found in the repository.

Dim folder As BaanFolderfolder = rep . Folder (“TheFolder”)

4 ResetCache.

This operation does not take any parameters.

S_OK.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


IBaanAttributesThe IBaanAttributes interface is used as a placeholder for information thatpertain to objects stored in the repository. The interface is obtained by queryingthe IBaanObject interface for the interface�s pointer to IBaanAttributes. With thisinterface, you can query for the object�s name, CLSID, time and date of creation,and so on.

The IBaanAttributes interface has the following properties.

IBaanAttributes propertiesProperty Type DescriptionName BSTR Returns the name of the object. This is a

read-only property.Description BSTR Returns a description of the object, provided

one has been entered; otherwise it returnsan empty string. This is a read-only property.

Path BSTR Returns the path to the object. This is aread-only property.

FullPath BSTR Returns the path and name of the object in astring. This is a read-only property.

GUID BSTR Returns the GUID of the object, in stringformat. This is a read-only property.

Version LONG Returns the current version number of theobject. This is a read only property.

DateCreated VARIANTARG Returns the time and date when the objectwas created in the repository. This is a read-only property. NOTE: this operation will beimplemented in a future release.

DateUpdated VARIANTARG Returns the time and date when the objectwas last updated in the repository. This is aread-only property. NOTE: this operation willbe implemented in a future release.

Creator BSTR Returns the name of the user who createdthe object in the repository. This is a read-only property. NOTE: this property will beimplemented in a future release.

Updater BSTR Returns the name of the user who lastmodified the object. This is a read-onlyproperty NOTE: this operation will beimplemented in a future release..

The IBaanAttributes interface has no methods.

COM interfaces


Properties

1 Name.

[out, retval] BSTR* bstrName: The name of the object.

S_OK if successful or E_POINTER if invalid destination.

Dim strName as StringstrName = attribs . Name

2 Description

[out, retval] BSTR* bstrDescription: The description, if the description wasentered, otherwise, an empty string.


Dim strDescription as StringstrDescription = attribs . Description

3 Path.

[out, retval] BSTR* bstrPath: Receives the path to the object.


Dim strPath as StringstrPath = attribs . Path

4 FullPath.

[out, retval] BSTR* bstrFullPath: Receives the path and name.


Dim strFullPath as StringstrFullPath = attribs . FullPath

5 GUID;

[out, retval] BSTR* pbstrGUID: Receives the globally unique identifier (GUID)of the object, in string format.


Dim strGUID as StringstrGUID = attribs . GUID

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


6 Version

[out, retval] LONG* plVersion: Pointer to a LONG that will hold the returnedversion number.


Dim lVersion as LonglVersion = attribs . Version

7 DateCreated.

[out, retval] VARIANTARG* varDate: The creation time and date.


Dim dCreated as DatedCreated = attribs . DateCreated

8 DateUpdated.

[out, retval] VARIANTARG* varDate: The time and date of last update.


Dim dUpdated as DatedUpdated = attribs . DateUpdated

9 CreatingUser.

[out, retval] BSTR* bstrCreator: Identifier of the user who created the object.


Dim strCreator As StringstrCreator = attribs . CreatingUser

10 UpdatingUser.

[out, retval] BSTR* bstrUpdater: Identifier of the user who last modified theobject.


Dim strUpdater As StringstrUpdater = attribs . UpdatingUser.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


IBaanObjectIBaanObject encapsulates a single repository object. In this release of the COMinterface, objects are read-only.

The IBaanObject interface has the following properties:

Property DescriptionRepository Retrieve the repository from which this object came.Attributes This method retrieves the IBaanAttributes interface, which is a

placeholder for information about the object. This is a read-onlyproperty.

Name Returns the name of the object. This is a read-only property.FullPath Returns the path and name of the object. This is a read-only

property.ObjectKind Returns the kind of the object. See the ObjectKind enumeration

for available kinds.

The IBaanObject interface has no methods. All the properties of the IBaanObjectinterface are read-only.

Properties

1 Repository

[out, retval] IBaanRepository** ppRep: Receives the IBaanRepository interface.

S_OK if successful or E_INVALIDARG if the parameter is NULL.

2 Attributes.

[out, retval] IBaanAttributes** ppAttributes: Receives the IBaanAttributesinterface.

Return value: S_OK if successful, E_INVALIDARG if the parameter is NULL.E_FAIL if unable to retrieve information for the object.

Dim attr As BaanAttributesattr = obj . Attributes

PARAMETERS

RETURN VALUE

PARAMETERS

EXAMPLE

COM interfaces


3 Name.

[out, retval] BSTR* pbstrName: Receives the object name.

S_OK if successful, E_INVALIDARG if the parameter is NULL. E_FAIL ifunable to retrieve information for the object.

Dim strName As StringstrName = obj . Name

4 FullPath.

[out, retval] BSTR* pbstrFullPath Receives the object path and name.

S_OK if successful, E_INVALIDARG if the parameter is NULL. E_FAIL ifunable to retrieve information for the object.

Dim strFullPath As StringstrFullPath = obj . FullPath

5 ObjectKind.

[out, retval] ObjectKind* pVal: Receives the object kind.

S_OK if successful, E_INVALIDARG if the parameter is NULL.

Dim enumObjKind As ObjectKindenumObjKind = obj . ObjectKindIf (enumObjKind = okForm) Then

MsgBox (“The object is a form”)Else

MsgBox (“The object is not a form”)End If

The table that lists all the possible values of ObjectKind is provided in thesection �Enumeration.�

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

OBJECTKINDVALUES

COM interfaces


IBaanFolderThe IBaanFolder enables clients to iterate through the contents of a folder in therepository. To obtain this interface, the client must query the repository for afolder by name. To iterate through an IbaanFolder, you can use standardenumeration interfaces. For instance, in VBA, the For Each construct is availableto iterate through the contained objects.

Example in VBA:

Dim contents As BaanFolder

Dim obj As Variant

‘ Rep is the name of a BaanRepository object.

contents = Rep . Folder ("\users")

For Each obj in contents

If (obj.ObjectKind = okType) Then

MsgBox "The object is a logical type"

End If

Next

The IBaanFolder interface has the following property:

IBaanFolder propertiesProperty Type DescriptionName BSTR This operation returns the name of the folder in a

string. This is a read-only property.

The IBaanFolder interface has no methods.

1 Name.

[out, retval] BSTR* bstrName: Receives the name of the folder.

S_OK if successful, E_INVALIDARG if the parameter is NULL.

Dim strName as String

strName = folder . Name

IBaanTypeIBaanType encapsulates a single logical type as represented on the repositoryserver. A logical type can have private and public user defined data members(attributes), as well as private and public user defined operations (methods).

If a client requests a logical type from a repository server, the server describesthe type in an XML document and submits the document to the client. The clientunpacks (parses) the XML document to read the type description.

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


A logical type can be a row, table, array or enumeration type. The types can benested and composed with each other, for example, a row can contain a table ofarrays, which again contain rows. The IBaanType interface is derived from theIBaanObject interface, in other words, all operations/properties from theIBaanObject interface are available on the IBaanType as well.

The IBaanType interface has the following additional properties and methods:

IBaanType propertiesProperty Type DescriptionXML BSTR Returns an XML description of the type.

IBaanType methodsMethod DescriptionNew This operation creates a new instance (value) of this type,

returning an IDispatch interface pointer.NewValue This operation creates a new instance (value) of this type,

returning an IBaanValue interface pointer.Load Load an instance of this type from multiple components. This

operation invokes the IS Component Integration Subsystem toretrieve a compound image of the object from all participatingcomponents.

Synchronize Synchronize a changed object across all participatingcomponents, using the IS Component Integration Subsystem.

Properties and methods

1 New.

[out, retval] IDispatch** ppInstance � Receives the IDispatch interface

S_OK if successful, E_INVALIDARG if the parameter is NULL,E_OUTOFMEMORY if there is not enough memory to create the instance orE_FAIL if the XML description is not available or if unable to create the instanceon the server.

Dim MyType As BaanTypeSet MyType = rep.Object (“\MyType”)Dim MyValue As BaanValueSet MyValue = MyType.New ()

PARAMETERS:

RETURN VALUE:

EXAMPLE

COM interfaces


2 NewValue.

[out, retval] IBaanValue** ppValue: Receives the IBaanValue interface.

S_OK if successful, E_INVALIDARG if the parameter is NULL,E_OUTOFMEMORY if there is not enough memory to create the instance orE_FAIL if the XML description is not available or if unable to create the instanceon the server.

Dim MyType As BaanTypeSet MyType = rep.Object (“\MyType”)Dim MyValue As BaanValueSet MyValue = MyType.NewValue ()

3 XML.

[out, retval] BSTR* pbstr: Receives the XML description of the type.

S_OK if successful or E_INVALIDARG if the parameter is NULL.

Dim strXML As StringstrXML = MyType.XML

4 Load.

� [in] BSTR bstrComponent: The component identifier.

� [in] BSTR bstrCode: The code of the value to load.

� [out, retval] IBaanValue** ppRetVal: Receives the IBaanValue interface.

S_OK if successful, E_INVALIDARG if the ppRetVal parameter is NULL orE_FAIL if an error occurred. Note that this method returns S_OK but sets theoutgoing pointer to NULL if the Load operation fails on the repository server.

Dim MyType As BaanTypeSet MyType = rep.Object (“\MyType”)Dim MyValue As BaanValueSet MyValue = MyType.Load (“BAANERP”, “010”)

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


5 Synchronize.

� [in] BSTR strComponent: The component identifier.

� [in] BSTR strCode: The code of the value to synchronize.

� [in] SyncFlag Flag: A flag indicating how the synchronization must beperformed.

� [out, retval] BOOL* pRetVal: Receives a Boolean value that describessuccess or failure.

� The SyncFlag is an enumeration flag whose valid values are:

− SYNC_DEFAULT: Default synchronization.− SYNC_STORE_ALL: Store all components, including the originating

one.− SYNC_ALWAYS_NEW: Store all components as new objects.− LOAD_SINGLE: Load from a single component/instance.

S_OK if successful, E_INVALIDARG if the pRetVal parameter is null orE_FAIL if an error occurred.

Dim MyType As BaanTypeSet MyType = rep.Object (�\MyType�)Dim fResult As BooleanfResult = MyType.Synchronize (�BAANERP�, �010�, 0)

IBaanType2IBaanType2 interface extends the IBaanType interface. All methods andproperties defined for the IBaanType interface are accessible using theIBaanType2 interface. The following methods are also defined for theIBaanType2 interface;

The IBaanType2 interface has the following methods:

Method DescriptionLoadEx Loads in instance of this type from multiple components and

sites.SynchronizeEx Synchronize a changed object across all participating

components and sites.Delete Deletes an instance from all components and sites.

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


Methods

1 LoadEx.


� [in] BSTR strCode: The code of the value to load.

� [in] BSTR strSite: The site identifier.

� [in] tagSyncFlag Flag: A flag that indicates how the load must be performed.

� [out, retval] IBaanValue** ppRetVal: Receives the IBaanValue interfacepointer.

S_OK if successful, E_INVALIDARG if the ppRetVal parameter is NULL orE_FAIL if an error occurred. Note that this method returns S_OK but sets theoutgoing pointer to NULL if the LoadEx operation fails on the server.

Dim MyType As BaanTypeSet MyType = rep.Object (“\MyType”)Dim MyValue As BaanValueSet MyValue = MyType.LoadEx (“BAANERP”, “010”, “London”,LOAD_SINGLE)

2 SynchronizeEx.


� [in] BSTR strCode: The code of the value to synchronize.

� [in] BSTR strSite: The site name.

� [in] SyncFlag Flag: A flag that indicates how the synchronization must beperformed.

� [out, retval] VARIANT_BOOL* pRetVal: Receives a VARIANT_BOOLvalue describing success (VARIANT_TRUE) or failure (VARIANT_FAIL).

S_OK if successful, E_INVALIDARG if the pRetVal parameter is NULL orE_FAIL if an error occurred.

Dim MyType As BaanTypeSet MyType = rep.Object (“\MyType”)Dim fOk As BooleanfOk = MyType.SynchronizeEx (“BAANERP”, “010”, “Amsterdam”,SYNC_STORE_ALL)

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


3 Delete.


� [in] BSTR strCode: The code of the value to delete.

� [in] BSTR strSite: The site identifier.

� [in] tagSyncFlag Flag: A flag that indicates how the delete operation must beperformed.

� [out, retval] VARIANT_BOOL* pRetVal: Receives a VARIANT_BOOLvalue describing success (VARIANT_TRUE) or failure (VARIANT_FAIL).

S_OK if successful, E_INVALIDARG if the pRetVal parameter is NULLor custom error message if the delete operation failed.Dim MyType As BaanTypeSet MyType = rep.Object (�\MyType�)Dim fOk As BooleanfOk = MyType.Delete (�BAANERP�, �010�, �Paris�, SYNC_DEFAULT)

IBaanValueIBaanValue represents a single instance of a logical type (IBaanType). A value iscreated using the IBaanType.NewValue method or the IBaanType.Load methoddescribed earlier. All user defined properties and methods defined for the logicaltype are accessible from the IBaanValue interface, as well as the properties andmethods described earlier. If a client makes a request for an instance of a logicaltype from a repository server, the server describes the instance in an XML fileand submits the file to the client. The client unpacks (parses) the XML file toread the instance values.

All user-defined properties and methods defined for the logical type areaccessible from the IBaanValue interface, as well as the properties and methodsdescribed in the following tables.

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


The IBaanValue interface has the following properties and methods:

IBaanValue propertiesProperty Type DescriptionType Reference to an

IBaanType interfaceRetrieves the IBaanType interfaceassociated with the instance. This is a read-only property.

Repository Reference to anIBaanRepositoryinterface

Retrieves the IBaanRepository interfaceassociated with the instance. This is a read-only property.

XML BSTR Retrieves the XML description of theinstance. This is a read-only property.

Clone VARIANTARG Create a copy of this instance. This is aread-only property.

GUID BSTR Obtain the GUID of the value

IBaanValue methodsMethod DescriptionField Retrieves the value of a field or subcomponent, identified by a

zero-based index.Assign Field-by-field assignment.Store Store (update) the value in multiple components.StoreNew Store a new value in multiple components.


1 Type.

[out, retval] IBaanType** ppType: Receives the IBaanType interface.

S_OK if successful, E_INVALIDARG if parameter is NULL or E_FAIL if notype is associated with the value.

Dim MyType As BaanTypeSet MyType = MyValue.Type

2 Repository.

[out, retval] IBaanRepository** ppRepository: Receives the IBaanRepositoryinterface.

S_OK if successful, E_INVALIDARG if parameter is NULL or E_FAIL if notype is associated with the value.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


Dim MyRep As BaanRepository

Set MyRep = MyValue.Repository

3 Field.

� [in] INT iIndex: A zero-based index of the field or subcomponent.

� [out, retval] VARIANTARG* pResult: Receives the value of the field orsubcomponent.

S_OK if successful, E_FAIL if no type is associated with the value orE_INVALIDARG if the iIndex parameter is out of range or if the pResultparameter is NULL.

Dim numVal As LongDim MyField As BaanValuenumVal = MyVal.Field (0)

4 Assign.

[in] VARIANTARG* pvar: The value to assign.

S_OK if successful, E_FAIL if no type is associated with the value orE_INVALIDARG if the pvar parameter is NULL.

Dim MyValue As BaanValueMyValue.Assign (MyOtherValue)MyValue = MyOtherValue ‘ This is the same

5 XML.

[out, retval] BSTR* pbstr: Receives the XML description of the type.

S_OK if successful, E_FAIL if no type is associated with the value orE_INVALIDARG if the parameter is NULL.

Dim MyType As BaanTypeSet MyType = rep.Object (“\MyRepType”)Dim MyValue As BaanValueSet MyValue = MyType.NewValue ()Dim strXML As StringstrXML = MyValue.XML

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


6 Clone.

[out, retval] VARIANTARG* pResult.

S_OK if successful, E_INVALIDARG if the presult parameter is NULL orE_FAIL if no type is associated with the value or if initialization of the clonedvalue failed.

Dim MyValue As BaanValueSet MyValue = MyOtherValue.Clone

7 Store.

[out, retval] BOOL* pRetVal: Boolean return value, TRUE if successful, FALSEotherwise.

S_OK if successful, E_FAIL if the connection to the server is unavailable or ifthe value is not correctly initialized.

Dim MyIntegratedType As BaanTypeSet MyIntegratedType = rep.Object (“\MyIntegratedType”)Dim MyIntegratedValue As BaanValue‘ Load the instance from multiple components.Set MyIntegratedValue = MyIntegratedType.Load (“BAANERP”,“010”)‘ Make the necessary changes to the MyIntegratedValue‘ Store the modified instanceDim fRetVal As BooleanfRetVal = MyIntegratedValue.Store ()

8 StoreNew.

[out, retval] BOOL* pRetVal: Boolean return value, TRUE if successful,otherwise FALSE.

S_OK if successful, E_FAIL if the connection to the server is unavailable or ifthe value is not correctly initialized.

Dim MyIntegratedType As BaanTypeSet MyIntegratedType = rep.Object (“\MyIntegratedType”)Dim MyIntegratedValue As BaanValueSet MyIntegratedValue = MyIntegratedType.NewValue ()‘ Make the necessary changes to the MyIntegratedValue‘ Store the modified instanceDim fRetVal As BooleanfRetVal = MyIntegratedValue.StoreNew ()

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


9 GUID.

[out, retval] BSTR* pVal: Receives the GUID of the value

S_OK.

Dim MyIntegratedType As BaanTypeSet MyIntegratedType = rep.Object (�\MyIntegratedType�)Dim MyIntegratedValue As BaanValue� Load the instance from multiple components.Set MyIntegratedValue = MyIntegratedType.Load (�BAANERP�, �010�)Dim strGUID As StringstrGUID = MyIntegratedValue.GUID

IBaanCodeMapIBaanCodeMap is a connection to the code map table. The code map table iscreated automatically, as long as a database connector object exists called\sys\codes\CodeMapData that specifies a valid ODBC source. The\predef\system contains two types, CodeMapRowType and CodeMapTableType,which specify the attributes of the code map table.

The code map table consists of the following four columns:

� Objguid.� Component.� Subsystem.� Code.

The following indexes are created on the table:

� A unique index on component, subsystem and code (primary index).� A unique index on objguid and component.� An index on objguid.

Be careful when you modify the code map. The operation of the componentintegration subsystem depends heavily on the integrity of the code map.

PARAMETERS

RETURN VALUE

EXAMPLE

NOTE

COM interfaces


The IBaanCodeMap interface has the following methods:

IBaanCodeMap methodsMethod DescriptionAdd Creates a new row in the code map table with the specified

parameters.Map Map the code of one component to another.MapGUID Map the code of one component to another.Modify Modifies the code of a component.Remove Remove a single row from the code map table.RemoveGUID Remove multiple rows from the code map table.


1 Add.

� [in] BSTR bstrGUID: The GUID.

� [in] BSTR bstrComponent: The component ID.

� [in] BSTR bstrSubSystem: The subsystem ID.

� [in] BSTR bstrCode: The unique code.

� [out, retval] BOOL* pRetVal: TRUE if the row in the code map table wassuccessfully created, otherwise FALSE.

S_OK if successful, E_POINTER if invalid destination or E_FAIL if connectionto the repository server is not available.

Dim CodeMap As BaanCodeMapSet CodeMap = Rep.CodeMap

Dim fRetVal As BooleanfRetVal = CodeMap.Add("{F5394620-0221-11D3-A249-00105A6B68E3}", "BAANERP",

"CUSTOMER", "010")

2 Map.

� [in] BSTR bstrComponent_1: The component ID of the first component.

� [in] BSTR bstrSubSystem_1: The subsystem ID of the first component.

� [in] BSTR bstrCode_1: The unique code of the first component.

� [in] BSTR bstrComponent_2: The component ID of the second component.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

COM interfaces


� [out, retval] BSTR* pCode: The code of the second component.



Dim strCode As StringstrCode = CodeMap.Map("BAANERP", "CUSTOMER", "010", "BFO")

3 MapGUID.

� [in] BSTR bstrGUID: The GUID of the first component.

� [in] BSTR bstrComponent: The component ID of the second component.

� [out, retval] BSTR* pCode: The code of the second component.



Dim strCode As StringstrCode = CodeMap.MapGUID("{F5394620-0221-11D3-A249-00105A6B68E3}",

"BAANERP")

4 Modify.



� [in] BSTR bstrNewCode: The new unique code.

� [out, retval] BOOL* pRetVal: TRUE if the code was modified successfully,otherwise FALSE.



Dim fRetVal As BooleanfRetVal = CodeMap.Modify("{F5394620-0221-11D3-A249-

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


00105A6B68E3}","BAANERP", "111")

5 Remove.


� [in] BSTR bstrSubSystem: The subsystem ID.

� [in] BSTR bstrCode: The unique code.

� [out, retval] BOOL* pRetVal: TRUE if the row was successfully removedfrom the code map table, otherwise FALSE.



Dim fRetVal As BooleanfRetVal = CodeMap.Remove("BAANERP", "CUSTOMER", "010")

6 RemoveGUID.


� [out, retval] BOOL* pRetVal: TRUE if the rows were successfully removedfrom the code map table, FALSE otherwise.



Dim fRetVal As BooleanfRetVal = CodeMap.RemoveGUID(�{F5394620-0221-11D3-A249-00105A6B68E3}�)

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


IBaanPeriodicThe IBaanPeriodic interface encapsulates a single periodic process as representedon the repository server. The interface enables external clients to change theperiodic processes settings, such as the interval at which the periodic process isrun. The IBaanPeriodic interface is derived from the IBaanObject interface andthus all properties and methods that are available on the IBaanObject interfaceare available on the IBaanPeriodic interface, as well.

The following enumerations are used when coding against the IBaanPeriodicinterface methods and properties:

� RecurrenceScheme.− SCHEME_INTERVAL: Fixed interval recurrence scheme.− SCHEME_MONTHLY: Monthly recurrence scheme.− SCHEME_YEARLY: Yearly recurrence scheme.− SCHEME_CODASOFTDATE: CODA softdate recurrence scheme.

� EndRange.− ENDRANGE_ENDNONE: No end date specified.− ENDRANGE_ENDBYNUMBER: End after fixed number of occurences.− ENDRANGE_ENDBYTIME: End after specific time.

� TimeUnit.− TIMEUNIT_SECONDS: Time unit in seconds, in other words, 5

seconds.− TIMEUNIT_MINUTES: Time unit in minutes, in other words, 3

minutes.− TIMEUNIT_HOURS: Time unit in hours, in other words, 2 hours.− TIMEUNIT_DAYS: Time unit in days, in other words, 8 days.− TIMEUNIT_WEEKS: Time unit in weeks, in other words, 3 weeks.

� Weekday.− WEEKDAY_MONDAY = 1 Monday.− WEEKDAY_TUESDAY = 2 Tuesday.− WEEKDAY_WEDNESDAY = 4 Wednesday.− WEEKDAY_THURSDAY = 8 Thursday.− WEEKDAY_FRIDAY = 16 Friday.− WEEKDAY_SATURDAY = 32 Saturday− WEEKDAY_SUNDAY = 64 Sunday

You can use the Weekday enumeration flag to define the periodic process to runon specific weekday by using the appropriate Weekday enumeration flag as wellas some combination of the weekdays, for example, to run the enumeration onevery Monday and Wednesday, the flag can be defined as 5 (1 + 4), orWEEKDAY_MONDAY | WEEKDAY_WEDNESDAY.

NOTE

COM interfaces


� SoftdateValue− OFTDATEVALUE_FIRST = 0 The first softdate.− OFTDATEVALUE_SECOND = 1 The second softdate.− OFTDATEVALUE_THIRD = 2 The third softdate.− OFTDATEVALUE_FOURTH = 3 The fourth softdate.− OFTDATEVALUE_LAST = 4 The last softdate.

The SoftdateValue enumerator is always combined with the SoftdateUnit

� SoftdateUnit.− SOFTDATEUNIT_DAY = 0.− SOFTDATEUNIT_WEEKDAY = 1.− SOFTDATEUNIT_WEEKENDDAY = 2.− SOFTDATEUNIT_MONDAY = 3.− SOFTDATEUNIT_TUESDAY = 4.− SOFTDATEUNIT_WEDNESDAY = 5.− SOFTDATEUNIT_THURSDAY = 6.− SOFTDATEUNIT_FRIDAY = 7.− SOFTDATEUNIT_SATURDAY = 8.− SOFTDATEUNIT_SUNDAY = 9.

To set the periodic process to run on the first Monday each month, you must setthe SoftdateValue enumeration flag as SOFTDATEVALUE_FIRST, and set theSoftdateUnit enumeration flag as SOFTDATEUNIT_MONDAY.

� MonthlyDayType.− MONTHLYDAYTYPE_DAY− MONTHLYDAYTYPE_SOFTDATE

� YearlyDayType.− EARLYDAYTYPE_DAYOFMONTH− EARLYDAYTYPE_SOFTDATE

COM interfaces


� Months.− MONTHS_JANUARY.− MONTHS_FEBRUARY.− MONTHS_MARCH.− MONTHS_APRIL.− MONTHS_MAY.− MONTHS_JUNE.− MONTHS_JULY.− MONTHS_AUGUST.− MONTHS_SEPTEMBER.− MONTHS_OCTOBER.− MONTHS_NOVEMBER.− MONTHS_DECEMBER.

The IBaanPeriodic interface has the following properties:

Property DescriptionStartTime Sets/gets the date and time of the periodic process

(Date value).Active Sets/gets the active state of the periodic process

(Boolean value)RecurrenceScheme Gets the recurrence scheme type of the periodic

process defined by the RecurrenceSchemeenumerator. Read-only property.

EndRangeType Gets the end range type of the periodic processdefined by the EndRange enumerator. Read-onlyproperty.

Weekday Gets/sets the weekday value of the periodic process.Only valid if the periodic process�s RecurrenceSchemetype is defined as SCHEME_INTERVALRecurrenceScheme type.

MonthlyKind Gets the monthly day type value of the periodicprocess. Only valid if the periodic process�sRecurrenceScheme type is defined asSCHEME_MONTLY RecurrenceScheme type. Read-only property.

MonthlyInterval Gets/sets the value of the day of the month theperiodic process must be run on. Only valid if theperiodic process�s RecurrenceScheme type is definedas SCHEME_MONTHLY RecurrenceScheme type andif the MonthlyKind type is defined asMONTHLYDAYTYPE_DAY.

COM interfaces


MonthlySoftdateValue Gets the value of the softdate of the month theperiodic process must be run on. Only valid if theperiodic process�s RecurrenceScheme type is definedas SCHEME_MONTHLY RecurrenceScheme type andif the MonthlyKind type is defined asMONTHLYDAYTYPE_SOFTDATE. Read-onlyproperty.

MontlySoftdateUnit Gets the unit of the softdate of the month the periodicprocess must be run on. Only valid if the periodicprocess�s RecurrenceScheme type is defined asSCHEME_MONTHLY RecurrenceScheme type and ifthe MonthlyKind type is defined asMONTHLYDAYTYPE_SOFTDATE. Read-onlyproperty.

MonthInterval Gets/sets the montly interval the periodic process mustbe run on. Only valid if the periodic process�sRecurrenceScheme type is defined asSCHEME_MONTHLY RecurrenceScheme type.

YearlyKind Gets the yearly day type value of the periodic process.Only valid if the periodic process�s RecurrenceSchemetype is defined as SCHEME_YEARLYRecurrenceScheme type. Read-only property.

The IBaanPeriodic interface has the following methods:

Method DescriptionSetEndNone Sets the EndRange as ENDRANGE_ENDNONE value.SetEndByNumber Sets the number of times the periodic process must

run. Sets the EndRange enumerator flag asENDRANGE_ENDBYNUMBER value.

SetEndByTime Sets the day and time when the periodic process muststop running. Sets the EndRange enumerator flag asENDRANGE_ENDBYTIME value.

GetEndByNumber Gets the value of how often the periodic process is tobe run. Only valid if the periodic process�s EndRangetype is defined as ENDRANGE_ENDBYNUMBEREndRange type.

GetEndByTime Gets the value of the end date and time. Only valid ifthe periodic process�s EndRange type is defined asENDRANGE_ENDBYTIME EndRange type.

COM interfaces


SetInterval Sets the interval value of the periodic process. Onlyvalid if the periodic process�s RecurrenceScheme typeis defined as SCHEME_INTERVALRecurrenceScheme type.

GetInterval Gets the interval value of the periodic process. Onlyvalid if the periodic process�s RecurrenceScheme typeis defined as SCHEME_INTERVALRecurrenceScheme type.

SetMonthlySoftdate Sets the montly softdate value (Softdate value andunit) of the periodic process must be run on. Only validif the periodic process�s RecurrenceScheme type isdefined as SCHEME_MONTHLY RecurrenceSchemetype and if the MonthlyKind type is defined asMONTHLYDAYTYPE_SOFTDATE.

GetYearlyDayOfMonth Gets the value of the day and month the periodicprocess must be run on. Only valid if the periodicprocess�s RecurrenceScheme type is defined asSCHEME_YEARLY and the YearlyKind type is definedas YEARLYDAYTYPE_DAYOFMONTH.

SetYearlyDayOfMonth Sets the value of the day and month the periodicprocess must be run on. Only valid if the periodicprocess�s RecurrenceScheme type is defined asSCHEME_YEARLY and the YearlyKind type is definedas YEARLYDAYTYPE_DAYOFMONTH.

GetYearlySoftdate Gets the value of the softdate the periodic processmust be run on. Only valid if the periodic process�sRecurrenceScheme type is defined asSCHEME_YEARLY and the YearlyKind type is definedas YEARLYDAYTYPE_YEARLYSOFTDATE.

SetYearlySoftdate Sets the value of the softdate the periodic processmust be run on. Only valid if the periodic process�sRecurrenceScheme type is defined asSCHEME_YEARLY and the YearlyKind type is definedas YEARLYDAYTYPE_YEARLYSOFTDATE.

Save Saves the periodic process�s changes to the repositoryserver. Note that after altering some of the Periodicprocess�s attributes this methods needs to be called inorder to update the process on the Repository server.

COM interfaces



1 StartTime (propget).

[out, retval] DATE *pdStartTime: Retrieves the start time of the periodicprocess.

S_OK if successful, E_INVALIDARG if the pdStartTime parameter is NULL.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim dStart As DatedStart = per.StartTime

2 StartTime (propput).

[in] DATE dStartTime: The new start time of the periodic process.

S_OK if successful, E_INVALIDARG if the dStartTime parameter is not a validdate value.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim dStart As DatedStart = #30/01/2000#per.StartTime = dStartper.Save ‘ Save the changes

3 Active (propget).

[out, retval] VARIANT_BOOL *pfActive: Retrieves the active status of theperiodic process.

S_OK if successful, E_INVALIDARG if the pfActive parameter is NULL.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim fActive As BooleanfActive = per.Active

4 Active (propput).

[in] VARIANT_BOOL fActive: The new active state of the periodic process,either TRUE or FALSE.

S_OK if successful, E_INVALIDARG if the fActive parameter is not a validBoolean value.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim fActive As BooleanfActive = TRUEper.Active = fActiveper.Save ‘ Save the changes

5 RecurrenceScheme (propget).

[out, retval] tagRecurrenceScheme *peRecurrenceScheme: Retrieves theRecurrenceScheme enumerator flag of the periodic process.

S_OK if successful, E_INVALIDARG if the peRecurrenceScheme parameter isNULL.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eRecurrenceScheme As RecurrenceSchemeeRecurrenceScheme = per.RecurrenceSchemeIf (eRecurrenceScheme = SCHEME_INTERVAL) Then

MsgBox “Interval recurrence scheme”End If

6 EndRangeType (propget).

[out, retval] tagEndRange *peEndRange: Retrieves the EndRange enumeratorflag of the periodic process.

S_OK if successful, E_INVALIDARG if the peEndRange parameter is NULL.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eEndRange As EndRangeeEndRange = per.EndRangeTypeIf (eEndRange = ENDRANGE_ENDNONE) Then

MsgBox “No end date”End If

7 Weekday (propget).

[out, retval] tagWeekday *peWeekday: Retrieves the weekday flag of theperiodic process that defines on what weekdays the periodic process must be runon.

S_OK if successful, E_INVALIDARG if the peWeekday parameter is NULL,error code 0x80047e92 if the periodic process recurrence scheme is notSCHEME_INTERVAL.

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eWeekday As WeekdayeWeekday = per.WeekdayIf (eWeekday = WEEKDAY_FRIDAY) Then

MsgBox (“This periodic process runs on Fridays”)End If

8 Weekday (propput).

[out, retval] tagWeekday *peWeekday: The weekdays that the periodic processmust run on. The weekday flags can by combined together using the �&�operator, such as �WEEKDAY_MONDAY & WEEKDAY_FRIDAY.�

S_OK if successful, E_INVALIDARG if the peWeekday parameter is not a validWeekday enumerator value.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eWeekday As Weekday’ Set the periodic process to run on every Monday andTuesdayeWeekday = WEEKDAY_MONDAY & WEEKDAY_TUESDAYper.Weekday = eWeekdayper.Save ‘ Save the changes

If you set this property, the periodic processes recurrence scheme is set asSHEME_INTERVAL.

9 MonthlyKind (propget).

[out, retval] tagMonthlyDayType *peMonthlyDayType: Retrieves the monthlyday type of the periodic process.

S_OK if successful, E_INVALIDARG if the peMonthlyDayType parameter isNULL, error code 0x80047e92 if the periodic process recurrence scheme is notSCHEME_MONTHLY.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eMonthlyDayType As MonthlyDayTypeeMonthlyDayType = Per.MonthlyKindIf (eMonthlyDayType = MONTHLYDAYTYPE_DAY) Then

MsgBox (“The periodic process monthly day type is day”)Else

MsgBox (“The periodic process monthly day type is

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


softdate”)End If

10 MonthlyDay (propget).

[out, retval] short *psDay: Retrieves the day of the month that the periodicprocess must run on.

S_OK if successful, E_INVALIDARG if the psDay parameter is not valid, errorcode 0x80047e92 if the periodic process recurrence scheme is notSCHEME_MONTHLY, error code 0x80047e94 if the periodic process monthlyday type is not MONTHLYDAYTYPE_DAY.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim iDayOfMonth As IntegeriDayOfMonth = Per.MonthlyDayMsgBox (“The periodic process is set to run on day “ &CStr(iDayOfMonth) & _

“ of the month”)

11 MonthlyDay (propput).

[in] short sDay: The day of the month the periodic process must run on.

S_OK if successful, E_INVALIDARG if the sDay parameter is not a validnumeric parameter.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim iDayOfMonth As IntegeriDayOfMonth = 5 ‘ Run the periodic process the 5’th of themonthper.MonthlyDay = iDayOfMonthper.Save ‘ Save the changes

If you set this property, the periodic processes recurrence scheme is set asSHEME_MONTHLY and the monthly day type is set asMONTHLYDAYTYPE_DAY.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

NOTE

COM interfaces


12 MonthlySoftdateValue (propget).

[out, retval] tagSoftdateValue *peSoftdateValue: Retrieves the value of softdateof the month that the periodic process must run on.

S_OK if successful, E_INVALIDARG if the peSoftdateValue parameter is notvalid, error code 0x80047e92 if the periodic process recurrence scheme is notSCHEME_MONTHLY, error code 0x80047e94 if the periodic process monthlyday type is not MONTHLYDAYTYPE_SOFTDATE.

Dim Per As BaanPeriodicSet Per = Rep.Object (“\MyPeriodicProcess”)Dim eSoftdateValue As SoftdateValueeSoftdateValue = Per.MonthlySoftdateValueIf (eSoftdateValue == SOFTDATEVALUE_FIRST) Then

MsgBox (“The softdate value is first”)Else

‘ Code omitted for briefetyEnd If

To set the monthly softdate value, use the SetMonthlySoftdate method.

13 MonthlySoftdateUnit (propget).

[out, retval] tagSoftdateUnit *peSoftdateUnit: Retrieves the unit of softdate ofthe month that the periodic process must run on.

S_OK if successful, E_INVALIDARG if the peSoftdateUnit parameter is notvalid, error code 0x80047e92 if the periodic process recurrence scheme is notSCHEME_MONTHLY, error code 0x80047e94 if the periodic process monthlyday type is not MONTHLYDAYTYPE_SOFTDATE.

Dim Per As BaanPeriodicSet Per = Rep.Object (“\MyPeriodicProcess”)Dim eSoftdateUnit As SoftdateUniteSoftdateUnit = Per.MonthlySoftdateUnitIf (eSoftdateUnit == SOFTDATEUNIT_WEEKDAY) Then

MsgBox (“The softdate unit is weekday”)Else

‘ Code omitted for briefetyEnd If

To set the monthly softdate unit, use the SetMonthlySoftdate method.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


14 MonthInterval (propget).

[out, retval] short *psInterval: Retrieves the monthly interval the periodic processruns on.

S_OK if successful, E_INVALIDARG if the psInterval parameter is not valid,error code 0x80047e92 if the periodic process recurrence scheme is notSCHEME_MONTHLY.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim iMonthInterval As IntegeriMonthInterval = per.MonthIntervalMsgBox (“The periodic process runs every “ &CStr(iMonthInterval) & _

“ month”)

15 MonthInterval (propput).

[in] short sInterval: The month interval the periodic process must run on.

S_OK if successful, E_INVALIDARG if the sInterval parameter is not valid.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim iMonthInterval As IntegeriMonthInterval = 2 ‘ Run every second monthper.MonthInterval = iMonthIntervalper.Save ‘ Save the changes

If you set this property, the periodic processes recurrence scheme is set asSHEME_MONTHLY.

16 YearlyKind (propget).

[out, retval] tagYearlyDayType *peYearlyDayType: Retrieves the yearly daytype of the periodic process.

S_OK if successful, E_INVALIDARG if the peYearlyDayType parameter isNULL, error code 0x80047e92 if the periodic process recurrence scheme is notSCHEME_YEARLY.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eYearlyDayType As YearlyDayTypeeYearlyDayType = per.YearlyKindIf (eYearlyDayType = YEARLYDAYTYPE_DAY) Then

MsgBox (“The periodic process yearly day type is day”)

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


ElseMsgBox (“The periodic process yearly day type is

softdate”)End If

17 SetEndNone.

N/A.

S_OK.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)per.SetEndNoneper.Save ‘ Save the changes

If you call this method, the method sets the periodic process�s EndRange asENDRANGE_ENDNONE.

18 SetEndByNumber.

[in] long lOccurrences: Specifies the number of times the periodic process mustrun.

S_OK if successful, E_INVALIDARG if the lOccurrences parameter is invalid.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)’ Set the periodic process to run 3 times.per.SetEndByNumber (3)per.Save ‘ Save the changes

If you call this method, the method sets the periodic process�s EndRange asENDRANGE_ENDBYNUMBER.

19 SetEndByTime.

[in] DATE dEndTime: Specifies the date (day and time) when the periodicprocess must stop running.

S_OK if successful, E_INVALIDARG if the dEndTime parameters is invalid.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)’ Set the periodic process to stop running on the December31 2000Dim dEndDate As DatedEndDate = #31/12/2000#

PARAMETERS

RETURN VALUE

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


per.SetEndByTime (dEndDate)per.Save ‘ Save the changes

If you call this method, the method sets the periodic process�s EndRange asENDRANGE_ENDBYTIME.

20 GetEndByNumber.

[out, retval] long* plOccurrences: The number of times the periodic process mustrun before stopping.

S_OK if successful, E_INVALIDARG if the plOccurrences parameter is NULL,error code 0x80047e93 if the periodic process�s EndRange is notENDRANGE_ENDBYNUMBER.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)’ Get the number of times the periodic process it to be runbefore stoppingDim lOccurrences As LonglOccurrences = per.GetEndByNumber

21 GetEndByTime.

[out, retval] DATE* pdEndTime: The date (day and time) the periodic process isscheduled to stop running.

S_OK if successful, E_INVALIDARG if the pdEndTime parameter is NULL,error code 0x80047e93 if the periodic process�s EndRange is notENDRANGE_ENDBYTIME.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)’ Get the day and time when the periodic process isscheduled to stop runningDim dEndTime As DatedEndTime = per.GetEndByTime

22 SetInterval.

� [in] long lIntervalValue: The value part of the interval the periodic process isrun on.

� [in] tagTimeUnit eTimeUnit: The time unit part of the interval the periodicprocess is run on, such as seconds, minutes, and so on.

S_OK if successful, E_INVALIDARG if either parameter is invalid, error code0x80047e90 if the parameters do not represent a valid interval.

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)’ Set the periodic process interval as 5 hoursDim eTimeUnit As TimeUniteTimeUnit = TIMEUNIT_HOURSper.SetInterval (5, eTimeUnit)per.Save ‘ Save the changes

If you call this method, the method sets the periodic process�s recurrence schemeas SCHEME_INTERVAL.

23 GetInterval.

� [out] long* plIntervalValue: The value part of the interval the periodicprocess is scheduled to run on.

� [out] tagTimeUnit* peTimeUnit: The time unit part of the interval theperiodic process is scheduled to run on, such as seconds, minutes, and so on.

S_OK if successful, E_INVALIDARG if either parameter is NULL, error code0x80047e92 if the periodic process�s recurrence scheme is notSCHEME_INTERVAL.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)’ Make sure that the periodic process’s recurrence scheme isSCHEME_INTERVALDim eRC As RecurrenceSchemeeRC = per.RecurrenceSchemeif (eRC = SCHEME_INTERVAL) Then

‘ OK, get the periodic process’s intervalDim eTimeUnit As TimeUnitDim lIntervalValue As Longper.GetInterval (lIntervalValue, eTimeUnit)

ElseMsgBox (“The recurrence scheme is not interval recurrence

scheme”)End If

24 SetMonthlySoftdate.

� [in] tagSoftdateValue eSoftdateValue: The softdate value of the month theperiodic process must run on.

� [in] tagSoftdateUnit eSoftdateUnit: The softdate unit of the month theperiodic process must run on.

S_OK if successful, E_INVALIDARG if either parameter is NULL.

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eSoftdateValue As SoftdateValueDim eSoftdateUnit As SoftdateUnit’ Set the periodic process to run on second Tuesday everymontheSoftdateValue = SOFTDATEVALUE_SECONDeSoftdateUnit = SOFTDATEUNIT_TUESDAYper.SetMonthlySoftdate eSoftdateValue, eSoftdateUnitper.Save ‘ Save the changes

If you call this method, the periodic processes recurrence scheme is set asSHEME_MONTHLY and the monthly day type is set asMONTHLYDAYTYPE_SOFTDATE.

25 GetYearlyDayOfMonth.

� [out] tagMonths* peMonth: Retrieves the month part of the day and monththat the periodic process runs on.

� [out] short* psDay: Retrieves the day part of the day and month that theperiodic process runs on.

S_OK if successful, E_INVALIDARG if either parameter is NULL, error code0x80047e95 if the periodic process�s yearly day type is notYEARLYDAYTYPE_DAY.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim iDay As IntegerDim eMonth As Monthsper.GetYearlyDayOfMonth eMonth, iDayMsgBox (“The periodic process runs on day “ & CStr(iDay) & _

“ of month “ & CStr(eMonth)

26 SetYearlyDayOfMonth.

� [in] tagMonths eMonth: The month part of the day and month the periodicprocess must run on.

� [in] short sDay: The day part of the day and month the periodic process mustrun on.

S_OK if successful, E_INVALIDARG if either parameter is invalid.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim iDay As Integer

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


Dim eMonth As Months’ Define the periodic process to run at March 3rd every year.iDay = 3eMonth = MONTHS_MARCHper.SetYearlyDayOfMonth eMonth, iDayper.Save ‘ Save the changes

If you call this method, the periodic processes recurrence scheme is set asSHEME_YEARLY and the yearly day type is set asYEARLYDAYTYPE_DAYOFMONTH.

27 GetYearlySoftdate.

� [out] tagSoftdateValue* peSoftdateValue: Retrieves the softdate value part ofthe yearly softdate that the periodic process runs on.

� [out] tagSoftdateUnit* peSoftdateUnit: Retrieves the softdate unit part of theyearly softdate that the periodic process runs on.

� [out] tagMonths* peMonth: Retrieves the month part of the yearly softdatethat the periodic process runs on.

S_OK if successful, E_INVALIDARG if one of the parameters is NULL, errorcode 0x80047e95 if the periodic process�s yearly day type is notYEARLYDAYTYPE_YEARLYSOFTDATE.

Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eSoftdateValue As SoftdateValueDim eSoftdateUnit As SoftdateUnitDim eMonth As Monthsper.GetYearlySoftdate eSoftdateValue, eSoftdateUnit, eMonthMsgBox (“The periodic process runs on softdate value “ & _

CStr(eSoftdateValue) & “, softdate unit “ &CStr(eSoftdateUnit) & _

“ of month “ & CStr(eMonth))

28 SetYearlySoftdate.

� [in] tagSoftdateValue eSoftdateValue: Retrieves the softdate value part of theyearly softdate that the periodic process runs on.

� [in] tagSoftdateUnit eSoftdateUnit: Retrieves the softdate unit part of theyearly softdate that the periodic process runs on.

� [in] tagMonths eMonth: Retrieves the month part of the yearly softdate thatthe periodic process runs on.

S_OK if successful, E_INVALIDARG if one of the parameters is invalid.

NOTE

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE

COM interfaces


Dim per As BaanPeriodicSet per = Rep.Object (“\MyPeriodicProcess”)Dim eSoftdateValue As SoftdateValueDim eSoftdateUnit As SoftdateUnitDim eMonth As Months’ Let the periodic process run at the third Tuesday everySeptember montheSoftdateValue = SOFTDATEVALUE_THIRDeSoftdateUnit = SOFTDATEUNIT_TUESDAYeMonth = MONTHS_SEPTEMBERper.SetYearlySoftdate eSoftdateValue, eSoftdateUnit, eMonthper.Save ‘ Save the changes

If you call this method, the periodic processes recurrence scheme is set asSHEME_YEARLY and the yearly day type is set asYEARLYDAYTYPE_YEARLYSOFTDATE.

IBaanProfileThe IBaanProfile interface encapsulates a single profile object as represented onthe repository server. A profile contains a list of tasks that are mainly used toperform predefined actions, such as data transfer, running a service or a script,and so on.

The IBaanProfile interface has the following method(s):

Method DescriptionStart Start the profile object on the server.

Methods

1 Start.

� [in] tagProfileStartOption eStartOption: A flag that indicates how to start theProfile must be started.

� [out, retval] VARIANT_BOOL* pfRetVal: Receives a Boolean value thatdescribes success (VARIANT_TRUE) or failure (VARIANT_FALSE). If theprofile could not be started, for example, if the profile was already running,the return value is VARIANT_FALSE.

E_POINTER if the pfRetVal is NULL, 0x80047d76 if the object was not found,S_OK if successful.

EXAMPLE

NOTE

PARAMETERS

RETURN VALUE

COM interfaces


Dim MyProfile As BaanProfileSet MyProfile = rep.Object(�\Profiles\SomeProfile�)Dim fResult As BooleanfResult = MyProfile.Start (PROFILE_DETAILS)

To handle errorsThe following COM components implement the ISupportErrorInfo interface:

� Baan.IntegrationServer.� Baan.Connection.� Baan.Repository.� Baan.Periodic.� Baan.Type.� Baan.Value.� Baan.Profile.

The ISupportErrorInfo interface enables COM clients to use a concept called�Error Objects� to get richer error information than the basic HRESULT. If anerror occurs in a COM component that supports the ISupportErrorInfo interface,the component can return a custom error description. A COM automation clientcan handle these custom errors automatically and display the error description tothe client user. A COM client not using automation, for example, a C++ clientwho uses vtable interfaces, can catch these errors and query for the description ofthe error.

The following table describes each custom error implemented:

Code(in hex) Description0x80047d8a The Address property of the Baan.IntegrationServer

component is not set.0x80047d8b The Address property does not specify a port number.0x80047d6f Failed to receive message from server.0x80047d74 Logon failed. Either the user name or password is incorrect.0x80047d65 Message from server is incorrect. The repository server was

unable to handle the request.0x80047d8c The IP address �xxx� and port �xxx� could not be resolved.0x80047d67 Failed to create a socket.0x80047e40 Attempt to connect timed out without establishing a

connection. Check the The IP address.0x80047e3b The attempt to connect failed. The repository server is

probably not running.

EXAMPLE

COM interfaces


0x80047d7d Invalid client IP address. The repository server has rejectedthe client IP address.

0x80047d6b Failed to get greetings from server.0x80047d7f Failed to get the IbaanConnectionProxy interface � error code

�xxx�0x80047d6d Object was not correctly created. The Baan.Connection

object was not correctly created or the connection has beenclosed.

0x80047d73 Failed to send/receive message to/from server.0x80047d76 The object was not found in the server repository.0x80047d77 Version mismatch. The version number of the object being

saved does not match the current version number in therepository.

0x80047dc8 Error loading file for CryptoAPI support.0x80047d8d The value contains a field of an unsupported data type.0x80047e90 The interval specified for the IbaanPeriodic interface method

is invalid.0x80047e91 Error parsing the object�s XML description.0x80047e92 Recurrence scheme mismatch. If a periodic process�s

recurrence scheme is f.x. defined as SHEME_INTERVAL,and the IbaanPeriodic interface is asked for its MonthlyKindproperty, this error is returned.

0x80047e93 End range type mismatch. This error occurs when, forinstance, calling the GetEndByNumber method on theIbaanPeriodic interface when the Periodic process instanceend range type is defined as ENDRANGE_ENDNONE rangetype.

0x80047e94 Monthly day type mismatch. This error occurs when, forinstance, retrieving the MonthlyDay property when theperiodic process monthly day type is defined asMONTHLYDAYTYPE_SOFTDATE.

0x80047e95 Yearly day type mismatch. This error occurs when, forinstance, calling the GetYearlyDayOfMonth method when theperiodic process yearly day type is defined asYEARLYDAYTYPE_SOFTDATE.

0x80047e96 Recurrence scheme not supported. The COM client does notsupport the CODASoftdate recurrence scheme.

COM interfaces


EnumerationsThe following enumeration values (constants) are defined in the IS type library.These enumeration values correspond to each object kind in the repository.

ObjectKindIdentifier DescriptionokType Logical type.OkVariable Timed variable.OkCodePage Code page.OkMsgQueue Message queue.OkMenu Repository menu.OkForm Repository form.okProcess Repository process.okQuery Repository query.OkUser Repository user.okFile External table proxy.OkSubdirectory Subdirectory.OkObjectSet Named object set.OkPeriodic Periodic process.OkUnknown Repository system object.OkEnvironment Environment.OkMsgSource Message source.OkPicture Repository picture.OkMsgHandler Message handler.OkUserGroup User group.OkReport Report.OkDll Dynamic link library proxy.OkStaticVar Global variable.OkMessage Repository message.OkWorkflow Workflow object.OkDocument Workflow document.OkResource Resource.

COM interfaces


OkTextTable Table of text strings.OkAlert Alerter.OkDBConn Database connector.okComObject An object capable of storing its data in a Compound

File System, that is, using IStream and IStorage.okInterface Interface.okComponent Software component.okIterator Data source iterator.okScript A script object.okTask A task object.okProfile A profile object (a group of tasks).okPoint2Point Point-2-point integration object.okMapper A mapper object.okMsgSink A message sink object.

Hidden and/or restricted interfacesThe following hidden and/or restricted interface methods are implemented. Arestricted interface (or interface member) is not accessible from a macroprogrammer. These interface methods are not visible/accessible from a COMclient who uses dispatch interfaces, for example, VBScript and VBA. Theseinterfaces are for internal use only. COM clients who use vtable interfaces canaccess and use these interface methods, however, this type of usage isunsupported and must not be attempted. Each interface methods and/orproperties is briefly described.

IBaanConnectionProxyThe IBaanConnectionProxy interface is used for communication between variousCOM components and the IS repository server.

The interface has the following method:

Method DescriptionRequestWait Send a request to the IS repository server

COM interfaces


Methods

1 RequestWait.

� [in, size_is (ulLenIn] BYTE* pbBufferIn: Byte buffer that contains theincoming message.

� [in] ULONG ulLenIn: The size of the incoming buffer.

� [out, size_is ( , *pulLenOut)] BYTE** ppbBufferOut: Byte buffer thatcontains the outgoing message.

� [out] ULONG* pulLenOut: The size of the outgoing message.

S_OK if successful, E_FAIL if the connection to the server is unavailable, or ifthe message cannot be handled.

IBaanRepositoryThe interface has the following restricted methods:

Method DescriptionRequestWait Send a request to the IS repository serverConstructServerInstance Ask the server to construct an instance of a given

BaanType and return its XML descriptionDestroyServerInstance Ask the server to destroy a given instance of

BaanTypeMakeZombie Set the object to zombie state. If the reference

count goes to zero for an object, the count is set toZombie state instead of being deleted. If the clientthen requests the object again, a round-trip to therepository server is not required.

Methods

1 RequestWait.





S_OK if successful, E_FAIL if the connection to the server is unavailable, or ifthe message cannot be handled.

PARAMETERS

RETURN VALUE

PARAMETERS

RETURN VALUE

COM interfaces


2 ConstructServerInstance.

� [in] BSTR bstrType: The full path of the type.

� [out, retval] BSTR* pbstrXML: The XML description of the created instance.

S_OK if successful, E_INVALIDARG if the pbstrXML parameter is NULL,E_FAIL if the connection to the repository server is unavailable.

3 DestroyServerInstance ([in] ULONG ulCookie).

[in] ULONG ulCookie: The memory address of the object on the repositoryserver.

S_OK if successful, E_FAIL if the connection to the repository server isunavailable.

4 MakeZombie.

[in] BSTR bstrFullPath: The full path of the object.

S_OK if successful, E_FAIL if the object is not found in the cache.

IBaanObjectThe interface has the following restricted methods:

Method DescriptionRequestWait Send a request to the IS repository server.DoDelete Delete the object.ClearRepository Set the repository object member to NULL.

Methods

1 RequestWait.





S_OK if successful, E_FAIL if the connection to the server is unavailable or ifthe message cannot be handled.

PARAMETERS

RETURN VALUE

PARAMETERS

RETURN VALUE

PARAMETERS

RETURN VALUE

PARAMETERS

RETURN VALUE

COM interfaces


2 DoDelete.

This method does not take any parameters.

S_OK.

3 ClearRepository.

This method does not take any parameters.

S_OK.

IBaanFolderThe interface has the following restricted property:

Property Description_NewEnum Enumerates through the contents of the folder. This is a

read-only property.

Properties

1 _NewEnum.

[out, retval] IEnumVARIANT** ppIEnum: Enumeration interface with thecontents of the folder.

S_OK if successful. S_FALSE if the folder is empty. E_FAIL if there is noconnection to the repository server. E_INVALIDARG if parameter is NULL:

Dim contents As BaanFoldercontents = repository . Folder (“\users”)Dim obj As VariantFor Each obj in contents

<do something>Next

PARAMETERS

RETURN VALUE:

PARAMETERS

RETURN VALUE

PARAMETERS

RETURN VALUE

EXAMPLE

COM interfaces


IBaanValueThe interface has the following restricted properties:

_NewEnum Enumerate subcomponents of this value. This is a read-only property.

Cookie Obtain the value's cookie.

Properties

1 _NewEnum.

[out, retval] IUnknown** ppUnknown: Receives the IUnknown interface.

S_OK if successful, E_INVALIDARG if the punk parameter is NULL, E_FAILif no type is associated with the value or E_NOTIMPL if the value is an enumvalue.

‘ Initialize the values.Dim MyRowType As BaanTypeSet MyRowType = rep.Object (“\MyRowType”) ‘ Logical type ofRow kindDim MyTableType As BaanTypeSet MyTableType = rep.Object (“\MyTableType”) ‘ Table of\MyRowType objectsDim MyRowValue As BaanValueSet MyRowValue = MyRowType.NewValue ()Dim MyTableValue As BaanValueSet MyTableValue = MyTableType.NewValue ()‘ Enumerate through the MyTableValueDim Count As IntegerCount = 0Dim strField As StringFor Each X In MyTableValue

Count = Count + 1MyRowValue = X ‘ Each X is an instance of a

\MyRowType logical typestrField = MyRowValue.Field1

Next X

2 Cookie.

[out, retval] BSTR* pVal � Receives the value�s cookie.

S_OK.

PARAMETERS

RETURN VALUE

EXAMPLE

PARAMETERS

RETURN VALUE


IntroductionThis chapter provides a description of each type of user-definable objects. Tocreate these objects, you can use the buttons in the object browser, or click Newon the Objects menu.

The primitive data types that can be used in the definition of logical data typesare described in the following chapter.

The following table lists the types of user-definable objects.

User-definable objectsObject type DescriptionAlerter An object that performs periodic boundary checks and

raises an alert if predefined conditions apply. Alerters area special type of periodic processes.

Component An object in the repository that describes externalapplications, such as BaanFrontOffice or CODA-Financials.

Databaseconnector

A connection to an Open Database Connectivity (ODBC)compliant data source. You can use this connection todirectly manipulate databases by executing SQLstatements.

DLL proxy A link between the Broker scripting language and adynamic-link library (DLL) on your client computer or onthe server.

Environment The environment controls the entire user interface,including the background queries and the menus that arevisible.

File A mapping between an external data source and a logicaldata type. The file object serves as a variable, whose typeis the associated table type. You can map to ODBC-compliant databases and to text files.

Form Broker forms are used to display information, to processdata keyed in by users, and to display messages.

20 Object type reference

Object type reference


User-definable objects (continued)Object type DescriptionGlobal variable Global variables store values of a primitive type or a

logical data type. You can change the value of the variablein expressions and scripts. The global variable is stored inthe object repository and can be accessed from any client.

Iterator Iterators are used for fast bulk synchronization of databetween a single originating component and multipledestination components.

Logical data type Logical data types describe the nature and structure ofdata. This logical data description is independent of thephysical form of the data being processed.

Menu A definition of drop-down menus on the menu bar. Youcan define menus to customize the user interface of theBroker.

Message handler Message handlers pick up messages of a particular typefrom a queue in the object repository and perform anoperation on them, such as starting a workflow.

Message queue Message queue objects enable the Broker to bufferincoming messages until a message handler is free to dealwith these messages.

Message source Message source objects define how to retrieve and handleincoming messages.

Object set An object set is an object that contains a list of otherobjects. You can use object sets to specify the collectionof objects that must be exported to a file.

Periodic process A periodic process is an automatic process or task thatcan start at a predefined time and run from that point intime at predefined intervals.

Picture Picture objects store a graphics file into the objectrepository.

Query A query object displays data of a certain type in a formdesigned for the purpose.

Resource Resource objects represent central resources of whichthere is a limited amount available, such as machines,people or other facilities. The workflow system usesresource objects to check if sufficient resources areavailable to execute a certain step.

Text table Text table objects are used to store the texts that youdisplay on forms, in messages, and so on. Text tablesenable you to store a text in multiple languages andlocales.



User-definable objects (continued)Object type DescriptionTimed variable A timed variable stores an expression and the last

calculated value of that expression. The last calculatedvalue is valid during a limited period. If the variable isqueried about its value before the end of this period, thevariable returns the last value, otherwise, the value isrecalculated.You can use a timed variable to reduce the number oftimes that an expression must be evaluated.

User A user object must exist in the object repository for eachperson who must log on to the Broker.

User group A group of users with common characteristics. Usergroups facilitate flexible management of users.

Workflow Workflow objects are blueprints or templates for documentrouting.

These object classes are derived from the NamedObject class. You cannot createan object of the NamedObject type, only of the derived types. The operations forthe NamedObject class are available for all named objects.

Operations

The following table lists the operations of named objects:

Named object operationsOperation Descriptionedit Invokes an object editor on the specified

object. The editor usually consists of adialog box or a wizard.

setDescription Changes the description text associated withthe object.

checkIn, checkOut, enableVCS,label, lock, showHistory,undoCheckOut, unlock

Executes operations in the version controlsystem (VCS). For more information, seeChapter 17, �Version control system.�

queryAttribute, queryDescription,queryFullPath, queryInfo,queryName, queryPath,queryTimeCreated,queryTimeImported,queryTimeModified

Returns various types of information aboutthe object.



For details about these operations, see the �NamedObject class� section in thedocument Scripting Language Reference (U7278D US).

AlerterPurpose

An alerter performs periodic checks on the value of a variable or the result of acalculation. If the value exceeds a predefined boundary, the alerter sends awarning to a user or performs another user-defined action.

Creation

To create an alerter, take the following steps:

1 Open the repository browser folder where you want to store the alerter object.2 Click the New Alerter toolbar button.

A wizard starts that leads you through the steps necessary to create an alerter. Inthe final step of the alerter wizard, the alerter is copied to the \sys\processesfolder of the current repository server machine and starts immediately.

Important

Use unique names for alerters and periodic processes. If the name of an alerter isidentical to an existing alerter or periodic process, you overwrite the existingprocess in the \sys\processes folder.

Used folders

The timed variables that are checked by an alerter must reside in the \vars systemfolder.

The result of the evaluation of a checked variable or expression is stored in the\sys\alertvalues system folder.

Internally, an alerter is treated as a periodic process. To start an alerter, you mustcopy the alerter to the \sys\processes folder. To stop an alerter, you must deletethe corresponding object from the \sys\processes folder. For more information,see Chapter 11, �Periodic processes.�



Properties

The following table lists the properties of alerters.

Alerter propertiesProperty DescriptionName The name of the alerter. The name must differ from the

names of all other alerters and periodic processes.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Interval The time interval that elapses between successive runs of

the alerter.Start date and time The date and time when the alerter is to run for the first

time.Enabled (checkbox)

If you clear this check box, the alerter does not run.

Catch up (checkbox)

If you select this check box, the alerter runs once for everyinstance it missed during the time the alerter was notrunning.

Timed variable The timed variable that is monitored by the alerter. Thetimed variable must be present in the \vars folder of theobject repository. Instead of a simple timed variable, youcan specify an expression.

Expression An alerter operates either on a timed variable or on anexpression. If an expression is specified, it is periodicallyexecuted by the alerter. The alerter checks the result ofthe expression. The expression must yield a numericresult.

Upper bound The alerter performs either a bounds check or a ratiocheck. In a bounds check, the alerter will execute someaction if the checked value is greater than the upperbound.

Lower bound The alerter will execute some action if the checked value isless than the lower bound.



Type of trigger The trigger type can be Once, Leaving, Transition, orOutside.If the trigger type is Once, an alert occurs once if a resultoutside bounds is encountered. After that, the alerterbecomes inactive. If you modify and save the alerter, it willwork again.If the trigger type is Leaving, an alert is triggered if theresult of the check is outside bounds and the previousresult was inside bounds.If the trigger type is Transition, an alert is triggered if thechecked variable leaves its bounds and if the checkedvariable returns inside its bounds.If the trigger type is Outside, an alert is always triggered ifthe variable is outside bounds, regardless of the previousvalue of the checked variable.

Ratio In a ratio check, the alerter will be triggered if the valuebeing monitored changes by more than a specifiedpercentage relative to its previous value. If the ratio-checkbutton is selected, the bounds-check fields are alldisabled. The ratio check can either check for an increaseor for a decrease. The specified deviation percentage canbe any number ranging from 0 to 9999.99.

Action to perform The action that is performed if the checked value is outsidebounds. The action can be defined with the action wizard.Example actions are: send an e-mail or an Brokermessage, or run a script. Note that you cannot use theprintf function to display a message box, because thescript is run on the server.For more information, see the �Action wizard� section inChapter 9, "Tools and assistants.�

ComponentPurpose

Components are objects in the repository that describe external applications, suchas BaanFrontOffice or CODA-Financials. You can use these components in typedefinitions to specify a type�s component-specific behavior. This enables you tocreate logical data types in which multiple applications participate. Each of theseapplications (components) contributes to the behavior of the logical data type.

For more information, see Chapter 7, �Component integration.�

The connection with a component, which is the period between log on and logoff, is called a session. A component can have multiple sessions runningsimultaneously.



Creation

To create a component, take the following steps:

1 Open the repository browser folder where you want to store the componentobject.

2 Click the New Component toolbar button.

A wizard starts that leads you through the steps necessary to create a component.

Properties

The following table lists the properties of components.

Component propertiesProperty DescriptionName The name of the component.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Session type The logical data type to be used for the session

information. A row type is most convenient to use for thispurpose. Typically, a session type will contain handles,pointers to COM interfaces, or other information that isnecessary to interact with the component.A session is represented as an instance of thecomponent's session type.

Time to keep aliveafter last use

The time that the session will be kept open after thesession�s last use. This time will be used to keep thesession available for reuse without a logging on again.

Unique code The unique code that identifies the component. The uniquecode is used, amongst others, in code mapping tables.The code is preferably simple, for example, a single wordin uppercase letters.

Disabled (checkbox)

If you select this check box, the session is prevented fromrunning.

Login script The script used to log on to the component, in other words,to establish a session.The session information is accessible through the Sessionvariable. The login script has full read and write access tothe data in this variable.



Logout script The script used to log off of the component, in other words,to close a session.

Logging properties These properties determine which actions are logged inthe logging system. For more information, see Chapter 18,�Logging system.�

Logon, logout

The following coding example shows what a login script can look like. Thisexample assumes that you defined a row type to serve as session type. Thissession type has an Interface field that can store a pointer to a COM interface.

{

// Hypothetical logon to BaanFrontOffice through COM

OleObject sess ("BaanFrontOffice.Session.1");

sess.Login ("USER", "PASSWORD");

// Store our pointer to the BFO COM interface

// in the session object provided by Broker

Session.Interface = sess;

}

For information about the OleObject class, refer to the document ScriptingLanguage Reference (U7278D US).

The following example is of a logout script:

{

// A pointer to a COM interface was stored in the

// Session object's Interface field at login.

Session.Interface.Logout ();

Session.Interface = OleObject ();

}



Database connectorPurpose

A database connector represents a connection to an Open Database Connectivity(ODBC) compliant data source. You can use this connection to manipulatedatabases directly by running SQL statements.

The Broker also uses database connectors for the following internal services:

� The logging system. For more information, refer to Chapter 18, �Loggingsystem.�

� The code map. For more information, refer to Chapter 7, �Componentintegration.�

You can make connections to the user data sources defined in the ODBC sectionof the Control Panel of your computer.

You can use two methods to connect to an ODBC-compliant data source:

� Use a file object. For more information, refer to �File� in this chapter.� Use a database connector, which is described in this section.

File objects provide the most simple method to map a logical data type of typeTable with a table in a database. However, in some cases, a database connector ismore effective than a file object, for example:

� If you want to manipulate a database directly by executing SQL statementsthat can otherwise not be executed by using the scripting language.

� You want to improve the performance of database operations. Tableoperations on file objects are more memory intensive and slower than whenthe data source is asked to perform the operation. If your table has more thanseveral hundred rows, you are recommended to use database connectors.

Creation

To create a database connector, take the following steps:

1 Open the repository browser folder where you want to store the databaseconnector object.

2 Click the New Database Connector toolbar button.

A wizard starts that leads you through the steps necessary to create a databaseconnector.

NOTE



Use

The following example illustrates the use of a database connector.

You use an SQL database, for example, Microsoft SQL Server, to store customerinformation. You defined the table CUST to store the customer information. This tablehas a String column Country and a Number column Value. Suppose that the SQLServerdatabase connector is connected to this data source.The following script is executed.{ StringNumberTable t;

t = SQLServer . executeSQL ("select Country, sum (Value) from CUST group byCountry", StringNumberTable);t . view ();

}The data source executes the command and the Broker only reads the few rows that thedatabase returns.

Properties

The following table lists the properties of database connectors.

Database connector propertiesProperty DescriptionName The name of the database connector.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Data source The data source, selected from the ODBC Data Source

Administrator, which is available from your computer'scontrol panel. An ODBC data source stores informationabout how to connect to the indicated data provider.

Username The user identifier that can be required to access theselected data source.

Password The password that can be required to access the selecteddata source.

Login script The script that is executed just before a connection ismade to the database.

Logout script The script that is executed just before the databaseconnector is removed from the Broker memory.

Connection options Several options describe the expected behavior of the datasource and the performance-enhancing features. Theseoptions are described in the Connection options table inthe section on File objects, later in this chapter.



Operations

Database connectors have the following operation, which is available through thescripting language:

Table DatabaseConnector::executeSQL ( String strSQL,

TableType type )

The parameters are:

� The SQL expression that must be executed.� A definition of the result set in the form of a reference to a Broker table type.

The operation returns a table value of the given table type.

Define a database connector object (dbTestData) linked to a Microsoft SQLServer which stores a database called TESTdata. Use the following script tocreate a new table in the database:

{

// The new table in the TESTdata database is

// called NewTable. The new table has three

// columns (varchar, smallint, smallint).

String strSQL = "create table NewTable (

code varchar(12) not null ,

year smallint not null ,

period smallint not null )";

// We do not expect to get any result set,

// but the operation requires a valid table type.

ResultTable rt = dbTestData . executeSQL (

strSQL, ResultTable);

}

EXAMPLE



DLL proxyPurpose

A DLL proxy enables you to link between the Broker scripting language and anydynamic-link library (DLL) on your client PC. This link enables you, forexample, to start Windows applications and call operations in the Windowsoperating system. The DLL can be a standard part of the Windows operatingsystem, supplied by a third party, or created by the user.

Creation

Refer to the documentation of a DLL for details about the functionality, returntypes, parameter settings, and so on.

To create a DLL proxy object, take the following steps:

1 Open the repository browser folder where you want to store the DLL proxyobject.

2 Click the New DLL Proxy toolbar button.

3 Enter the name and description of the DLL proxy.

4 Enter the path of the DLL or EXE file. If you specify a file name without apath, the system will find the DLL for you.

5 Click the Operations tab to start adding operations that you want to haveavailable in the scripting language.

To add an operation, take the following steps:

1 Click View DLL to obtain a list of all the exported functions of the DLL.

2 Select the function you want to use.

3 Click Use with Name or Use with Ordinal.If you click Use with Name, you can invoke the function by the function�sname. This method is easiest to use. Sometimes, this method does not work,because the operation name can contain characters which are illegal in thescripting language. In that case, you can click Use with Ordinal.

4 Specify the return type and calling convention.

5 Specify the parameters. The parameters must be of the correct type and in thecorrect order. Click Add to add new parameters to the list, and click Removeto delete them. Click the arrow buttons to move the selected parameter up ordown the list.



If you do not specify the return type, calling convention, or parameters correctly,the system can crash if you attempt to use the function.

Use

After you create the DLL proxy and specified the proxy�s functions, you can usethe functions as methods of the DLL proxy object.

The DLL with file name USER32.DLL contains a function to display message boxes,called MessageBoxA.Create a DLL proxy with the following properties in the \example folder:� Name: DLLProxyUser32� Description: Example with MessageBoxA� DLL/EXE file: USER32.DLLAdd MessageBoxA operation (return type: INT; calling convention: stdcall; parameters:HWND, LPCSTR, LPCSTR, and UINT respectively).Now you can use call this function in a script, as follows:

\example\DLLProxyUser32.MessageBoxA(0, "Message text", "Title", 1)

Properties

The following table lists the properties of DLL proxies.

DLL proxy propertiesProperty DescriptionName The name of the DLL proxy.Description Language-dependent description. For more information, see

Chapter 15, �Language support.�DLL/EXE file The path and filename of the DLL or executable file to which

the DLL proxy is linked.Operations The operations describe the functions in the DLL that you

make available for use in the scripting language.

EXAMPLE



EnvironmentPurpose

The environment controls the entire user interface, including the backgroundqueries and menus that are visible. A user�s environment is set up whenever theuser logs on.

Creation

To create an environment, take the following steps:

1 Open the repository browser folder where you want to store the environmentobject.

2 Click the New Environment toolbar button.

A dialog box appears in which you can specify the environment's properties.

Use

Each user object has an environment property. Multiple users can share a singleenvironment.

Inheritance

The inheritance mechanism provides an efficient way to maintain environments.First, create a general environment for all users. This environment contains themenu with the options that must be available for everybody. Next, createadditional environments for users with specific roles. Specify that these specialenvironments inherit the features of the general environment. The menus of thesespecific environments will be displayed next to the basic menus of the generalenvironment. In the same way, the specific background queries are combinedwith the background queries of the general environment. The specific logonscript runs after the logon script of the general environment.



Properties

The following table lists the properties of environments:

Environment propertiesProperty DescriptionName The name of the environment.Description Language-dependent description. For more information, see

Chapter 15, �Language support.�Menu The full path of the menu that is used in this environment.Language The environment's language area or locale. Where locale

strings or text tables have been used, they will appear in thelanguage selected here. The environment language can beoverridden by the language specified for the user. For moreinformation, see Chapter 15, �Language support.�

Logon script The script that will be executed if a user with this environmentlogs on.

Tabs The position of background query tabs.Inherited: This option enables you to preserve the tabcharacteristics of the environment, if any, from which thisenvironment inherits characteristics.Top: This option presents the tabbed form query tabs at the topof the screen view.Bottom: This option presents the tabbed form query tabs at thebottom of the screen view.

Inherits The environment from which this environment will inherit itsattributes. If a user with this environment logs on, the menus ofthe inherited environment are set up first. Then the menus of thecurrent environment are added to the inherited menus. Thesame goes for scripts, queries, and so on.

Queries The queries that are displayed as tabbed forms on the screenfor users with this environment. You can specify any number ofqueries.



FilePurpose

File objects enable you to map an external data source to a logical data type.

The file object serves as a variable, whose type is the associated table type. Youcan use the file object in expressions where a table type is required.

You can map to two different types of external files:

� Text files.Each record is stored as a line of text in an ASCII data file.

� ODBC Database Queries.File object maps to a single table in an ODBC-compliant database.

You can make connections to the user data sources defined in the ODBC sectionof the Control Panel of your computer.

You can use the following two methods to connect to an ODBC-compliant datasource:

� Use a file object: This method is described in this section.� Use a database connector object: For more information, refer to the

�Database connector� section of this chapter.

File objects provide the most simple method to map a logical data type of typeTable with a table in a database. However, in some cases, a database connector ismore effective than a file object, for example:

� You want to manipulate a database directly by executing SQL statements thatcan otherwise not be executed by using the scripting language.

� You want to improve the performance of database operations. Tableoperations on file objects are more memory intensive and slower thanoperations run on the data source itself. If your table has more than severalhundred rows, for best results, you must use database connectors. Anexample is presented at the end of this section.

Creation

To create database connectors, take the following steps:

1 Open the repository browser folder where you want to store the file object.

2 Click the New File toolbar button.

A wizard starts that leads you through the steps necessary to create a file object.

NOTE



On the second page of the wizard, you must specify the type of external file tomap to:

� If you select Text file, you can subsequently enter the properties, which arespecific for text files.

� If you select ODBC database query, you can subsequently enter theproperties, which are specific for ODBC database queries.

SQL expressions

If you define an ODBC database query, you can enter a SQL expression to limitor sort the data from the database table.

A SQL expression has the following syntax:

SELECT columnlist

FROM tablename

WHERE whereclause

ORDER BY orderbyclause

Where:

� Columnlist is a comma-separated list of columns that must be placed into theresult set. If all columns in the table must be selected you can enter SELECT* FROM tablename.

� Tablename is a name of a table in the database.

� Whereclause is a criterion for accepting rows in the result set.

� Orderbyclause contains a list of columns to be used as sort criteria for theresult set. The ORDER BY clause must be the last part of the SELECTstatement. The default sorts rows in ascending order. To sort rows indescending order add the postfix DESC to a column name.

SELECT ID, NAME, JOB, COMM, YEARS

FROM STAFF

WHERE (JOB='Sales' AND COMM > 1000) OR YEARS > 10

ORDER BY YEARS DESC, ID

Example of an SQL expression with a compound column:

SELECT ID, NAME, SALARY+COMM

FROM STAFF

WHERE COMM IS NOT NULL

ORDER BY 3 DESC, NAME

EXAMPLE



In this example the three (3) in the ORDER BY line refers to the third column,which is a compound column comprised of the SALARY and COMM columns.

Use

The following example illustrates the use of a file object.

The CustomersTable file object contains information about customers. TheCustomersTable file object is connected to a table stored on an SQL database such as theMicrosoft SQL Server. This table has a String column Country and a Number columnValue. The following script runs:{CustomerTable . group (Country, sum (Value)) . view ();}

When the Broker executes this script, the Broker reads every row of the table into memoryand performs the group and sum operations in memory. In the process, all rows are readinto memory.For example, if the SQLServer database connector is connected to the same ODBC datasource, you can send the following command to the SQL database:select Country, sum (Value) from CUST group by CountryIn this case, the data source executes the command and the Broker only reads those fewrows that SQL Server returns.

Properties

File objects have many properties that you can maintain. For convenience, theseproperties have been described in a number of tables:

� General file object properties.� File object properties for text files.� File object properties for ODBC database queries.� Connection options.



The connection options table is followed by recommended settings for varioustypes of databases.

General file object propertiesProperty DescriptionName The name of the file object.Description Language-dependent description. For more information, see

Chapter 15, �Language support.�Table kind The type of external file to map to.

Text file specifies a connection to a text file. Each line in theexternal file must represent a single row. Fields can beseparated by commas (,) or semicolons (;).ODBC database query specifies a connection to a single tablein an ODBC compliant database. The database query cancontain customized select statements.You cannot modify the Table type property after the file object issaved.The properties for each type of external file are listed in the nexttwo tables.

File object properties for text filesProperty DescriptionTable type The logical data type to which the external file is mapped.File name The path and the name of the source file. If no path is given, the

file is assumed to be in the working directory of the Broker.If the text file already contains data, you must make sure thatthis data matches the file object's table type.Click the magnifying glass button to open the standard fileselector.

Separator The delimiting character that has been used to separate thefields in the text file. The available options are comma (,) andsemicolon (;).



File object properties for ODBC database queriesProperty DescriptionData source The data source selected from the ODBC Data Source

Administrator, which is available from your computer'scontrol panel. An ODBC data source stores informationabout how to connect to the indicated data provider.

Username The user identifier that can be required to access theselected data source.

Password The password that can be required to access the selecteddata source.

Table The table in the ODBC data source that is mapped to thelogical data type.

SQL expression The SQL expression that you can use to limit or sort thedata from the database table.The wizard for creating file objects has special controls toenable you easy entering of simple SQL expressions. If youwant to have full control over the result set, you can enter afree-form SQL expression.For more information about SQL expressions in file objects,see �Creation,� earlier in this section.

Table type The logical data type to which the external file is mapped.If you create a new ODBC database query, you cangenerate a table type and a row type based on the columnsin the external database table. The new table types gets thename of the ODBC table with the _table postfix. The newrow type gets the name of the ODBC table with the _rowpostfix.

Mapping ofexternal columnsand internal fields

The links between the external columns and internal fields.External columns not used in the mapping are notdisplayed, and internal fields without mapping to an externalfield contain default data if displayed.If the table type and row type were generated based on thecolumns in the external database, the wizard automaticallyconnects the external columns with the internal fields. Youcan modify these connections in the wizard.If you use an existing table type and row type, you mustdrag the columns to fields to manually create the links.

Connectionoptions

Several options describe the expected behavior of the datasource and the performance-enhancing features. Theseoptions are described in the following table.



The following table lists the connection options for file objects and databaseconnectors. Recommended settings for the Microsoft SQL Server, MicrosoftAccess, and Oracle databases are listed immediately after this table.

Connection optionsProperty DescriptionUse cursor library If you activate this option, the ODBC Cursor Library DLL

will be loaded. The cursor library masks some of theunderlying functionality of the ODBC driver and effectivelyprevents the use of dynasets. If you turn this option on, theonly cursors supported are static snapshots and forward-only.Select this check box when you connect to a desktopdatabase that needs the cursor library to make full use ofthe ODBC support in Microsoft Windows. Most advanceddatabase systems do not need to use the cursor library.

Recordset openmode

Dynaset specifies the use of a recordset with bidirectionalscrolling. The membership and ordering of the records aredetermined when the recordset is opened. Changes madeto the data values by other users are displayed after afetch operation. Dynasets are also known as key-drivenrecordsets.Snapshot specifies the use of a static recordset with bi-directional scrolling. The membership and ordering of therecords are determined when the recordset is opened. Thedata values are determined when the records are fetched.Changes made to the data values by other users are notdisplayed until the recordset is closed and then reopened.ForwardOnly specifies the use of a read-only recordsetwith only forward scrolling.Dynamic specifies the use of a recordset with bi-directionalscrolling. Changes made to the membership, ordering anddata values of the records by other users are displayedafter a fetch operation. Many ODBC drivers do not supportthis type of recordset.

Recordset optionsnone (check box)

Specifies that no option is turned on. This check box ismutually exclusive with all the other recordset options

appendOnly If you select this option, records can be appended to therecordset but records cannot be edited or deleted.

readOnly If you select this option, the recordset will be opened inread-only mode.



Connection options (Continued)Property DescriptionoptimizeBulkAdd This option is currently not implemented.

If you select this option, a prepared SQL statement isused to optimize the addition of many records at one time.The first update determines which fields are marked dirty.This option is mutually exclusive with theuseMultiRowFetch option.

useMultiRowFetch This option is currently not implemented.If this option is turned on, bulk row fetching isimplemented to enable multiple rows to be retrieved in asingle fetch operation. This is an advanced featuredesigned to improve performance. This option is mutuallyexclusive with the optimizeBulkAdd option.If the user specifies useMultiRowFetch:� The noDirtyFieldCheck option will be turned on

automatically, and double buffering will not be available.� The useExtendedFetch option will be turned on

automatically on forward-only recordsets.

skipDeletedRecords If you select this option, all deleted records are ignoredwhen you navigate through the recordset. This degradesthe performance of some relative fetches. If you useforward-only recordsets, you cannot select this check box.The action of skipDeletedRecords is similar to that ofdriver packing, which removes deleted rows from therecordset. However, if your ODBC driver packs records,the ODBC driver removes only those records that youhave deleted; it does not remove records deleted by otherusers while the recordset was open. skipDeletedRecordsskips rows deleted by other users.

useBookmarks If you select this option, bookmarks will be used on therecordset, as long as bookmarks are supported.Bookmarks slow the rate of data retrieval but improve theperformance of data navigation. This option is notavailable for forward-only recordsets.

noDirtyFieldCheck If you select this option, the automatic dirty field checking(double-buffering) is also turned off. If you select thischeck box, you can improve performance.

executeDirect If ou selct this option, no prepared SQL statements areused.



useExtendedFetch If you select this option, the SQLExtendedFetchcommand is used in place of SQLFetch. This option isdesigned to implement bulk row fetching on forward-onlyrecordsets. If you set the useMultiRowFetch check boxon a forward-only recordset, this check box is setautomatically.

userAllocMultiRowBuffer

This option is currently not implemented.

Microsoft Access

To connect to desktop databases like Microsoft Access, use the following cursorand connection options for best results:

� Select the Use cursor library check box.� Select the Snapshot option button.

Microsoft SQL Server

To connect to Microsoft SQL Server databases, use the following cursor andconnection options for best results:

� Clear the Use cursor library check box.� Select Dynaset.� Select the skipDeletedRecords check box.� Select the useExtendedFetch check box.� Clear all other check boxes.

Microsoft DAC

However, an exception to these recommendations for the Microsoft SQL Serverdatabases exists. If a combination of the following situations occurs, you mustselect Dynamic rather than Dynaset, otherwise, you cannot change data in thedatabase:

� You have installed Microsoft DAC version 2.0 or later.� You are connecting a file object to a Microsoft SQL Server database.

For database connectors, you can select either Dynamic or Dynaset.



Oracle

To connect to Oracle databases using file objects or database connector objects,use the following cursor and connection options to achieve best results:

� Select the Use cursor library check box.� Select Dynamic.� Select the useExtendedFetch check box.� Clear all other check boxes.

Operations

A file object has an operation view, which opens a grid viewer on the file. Toopen this viewer, take the following steps:

1 Right-click the file object in the repository browser.

2 Click View.

A file object represents a value of the file object's logical data type. This logicaldata type is a table type. As a result, the following two types of operations areavailable on file objects:

� The user-defined operations of the logical data type.� The operations of the Table class, such as avg, sum, select, and sort.



The following table lists the operations of the Table class. For details about theseoperations, refer to the document Scripting Language Reference (U7278D US).

Table operationsOperation DescriptionView Displays the table in a standard table viewing window.Edit Creates a table editing window that shows the table in a grid. The

user can add, modify, and delete rows.insert Attempts to insert a row in the table.find Returns the first row in the table that matches a given selection

condition.first Returns the first row in the table. If a numeric argument N is

specified, the first N rows are returned as a table.last Returns the last row in the table. If a numeric argument N is

specified, the last N rows are returned as a table.select Selects rows from the table based on a condition.exists Tests whether the table contains one or more rows that meet a

certain condition. Returns FALSE if the table contains no suchrow.For example, Customers . exists (Amount_owed == 0) returnsTRUE if there is a customer who owes nothing.

sort Returns the table sorted according to the argument expressions.group Returns the table grouped by a group expression and

summarized by a result-column expression. For example, a tableof names and addresses can be grouped by city.

merge Merges two tables that have the same row type.project Returns a new table that has the same number of rows as the

operand table but where each row has been transformed(projected) according to the list of column expressions given asarguments.

avg Returns the average of the values of an argument expressionover the rows of the operand table.

count Returns the number of rows in the operand table.max Returns the maximum value of the argument expression over the

rows of the table.min Returns the minimum value of the argument expression over the

rows of the table.



sum Returns the sum of the values of the argument expression overthe rows of the operand table.

product Multiplies the values of the argument expression over the rows ofthe operand table and returns the numerical result.For example, Statistics . product (Probability) will return theproduct of the probability column over the entire Statistics table.

total Returns the totals of the argument table. The totals are returnedin a row value that has an anonymous type.

clear Clears the content of the external table.disconnect Disconnects the table object in question from the external data

table.toClipboard Places the table on the Windows clipboard for further processing

by other programs.asHTML Formats the data in the table along with column names and

returns the data as an HTML document.

FormIntroduction

Purpose

The Broker forms are used to display information, to process data keyed in byusers, and to display messages. Forms can be tabbed, and they can be configuredto only show those controls at run-time that are appropriate to the current user.

A form is always linked to a particular logical data type. The form only displaysvalues of that type. A single form can be used to display the results from multiplequeries, as long as the results are of the same logical data type.

If you want to have a uniform style for your forms, you must create a base formwith the background color and pictures that must appear on every form. Thisbase form must have type Void. The other forms can inherit the backgroundproperties of this base form. You can also create a form with certain standardcommand buttons that can be inherited by other forms.



Creation

To create a form, take the following steps:

1 Open the repository browser folder where you want to store the form object.

2 Click the New Form toolbar button.

A dialog box appears in which you can specify the form's properties. After youclick OK, the form editor starts. The form editor is a visual editor that enablesyou to insert controls and fields on forms using the mouse. For instructions onhow to use the form editor to create a form, refer to �Forms, creating� in theonline Help.

Use

To display a form, you can use the form's run operation in a script.

You can also use a form as part of a query object. For more information, refer to�Query,� later in this chapter.

You can drag a form from the repository browser and drop the form on theBroker window in the same way as query objects. You can use this, for example,to add buttons to the user interface. For more information, refer to �Query� laterin this chapter.

You can also use a form to send messages to users. For more information, referto Chapter 8, �Messages.�



General form properties

Properties

The following table lists the properties of forms:

General form propertiesProperty DescriptionName The name of the form.Description The description that is shown in the title bar of the form. You

can enter the description in multiple languages. For moreinformation, see Chapter 15, �Language support.�

Inherit from The form from which your form will inherit attributes, forexample, background colors and pictures.

Type The logical data type of the form. The form�s type determineswhat kind of values the form can display.

Help file The file name of your custom help file for this form.Help topic The decimal context ID number of the topic in the help file that

will display the help for this form. This number is used toprovide context-sensitive help from the file specified in theHelp file field.

Form size To specify the form size:1 Drag the corner of the window in the form editor to the

desired form size.2 On the Objects menu, click Set Window Sizes.3 Select Current Size.4 Click OK.

If you select Default and click OK the form returns to thedefault size for forms.

Other form properties are:

� A list of pages.

� The controls on each page, which includes fields, buttons, texts, and so on.

� The order of input fields and buttons. This order is followed if a user pressesthe TAB key to move from field to field.



Buttons on dialog boxes

The form behavior specifies the buttons that appear if the form is run as a dialogbox. Note that these buttons do not appear if the form is displayed as an MDIwindow.

Form behavior properties (buttons)Property DescriptionOK/close (checkbox)

Specifies that the form will have an OK or Close button.The OK button appears on a form where the user can editdata and changes must be confirmed.The Close button appears on a form that is for viewingdata only and where the user cannot make changes.

Cancel Specifies that the form will have a Cancel button, whichenables the user to cancel any changes made to the data.

Print Specifies that the form will have a Print button, whichenables the user to print the form.

Insert Specifies that the form will have a Insert button, whichenables the user to insert a record into the data. Thisapplies only if the form enables data to be edited.

Delete Specifies that the form will have a Delete button, whichenables the user to delete the selected record from thedata. This applies only if the form enables data to beedited.

First, Previous,Next, and Last

Specifies that the form will have a First, Previous, Next,and/or Last buttons, which enables the user to move tothe first, previous, next, or last record of the data. Thisapplies only if the form enables data to be edited orviewed.

Emulate dialog boxwhen displaying inMDI window

Specifies that the form will look like a dialog box eventhough the form is, in fact, an MDI window and behaveslike one. For example, the form appears on the Windowmenu of the main window.



Form background

If you want to have a uniform style for many forms, you must specify thebackground color and pictures in a base form with type Void. The other formscan inherit the background properties of this base form.

Form background propertiesProperty DescriptionPicture The picture object that you want to display on the background

of the form.If the picture is Read from repository, you can specify a pictureobject from within the repository.If the picture is Read from file, you can specify the path of thepicture file on your client system.

Display mode(option button)

Stretch specifies that the picture will be stretched to fill thespace available. This can distort the aspect ratio of the picture.Tile specifies that the picture will be tiled, which means, shownin its original size as many times as required to cover theentire background area of the form. The central tile is alwaysat the center of the form.

Color The background color of the form.

Form contentYou can place the following controls anywhere on a form:

� Expression fields:Contain statements to be evaluated, of which the results are displayed.

� Input fields:Used to control how data is displayed on the form and how the data can beedited.

� Command buttons:Used to enable the user to execute some action, for example, to run a script.

� Static text:Used for field labels and headings.

� Picture:Used to make a form visually attractive and easily recognizable, or to addlogos and symbols to the form.

� Static box:Used to group fields and other form controls together visually, for example,in a rectangular line.



The form editor has a button for each of these controls. To place a control on aform:

1 Click the button for that control.

2 Point to the top-left corner of the control's position.

3 Drag to the bottom-right corner of the control's position. A rectangular frameappears.

If you release the mouse button, a dialog box appears in which you can enter thecontrol's properties. The properties of these controls are described later in thissection. For more information about adding form controls, see the online help.

Tool dock

The tool dock has several tools that you can use to design a form:

� A field tool:Used to place fields on the form.

� A text tool:Used to configure fonts and font styles.

� A color tool:Used to apply colors, and to mix and store new colors.

For information about the tool dock�s text tool and the color tool, see Chapter 9,�Tools and assistants.�



The following figure (see Figure 13) shows the field tool of the tool dock. Thistool enables you to easily add fields from a row type to a form. To add fieldsfrom a row type to a form, take the following steps:

1 Open the tool dock. You might have to minimize or close the form editorbefore you can find the Open Tool Dock command on the object browser'sObjects menu.

2 Open a form that has a row type.

3 Drag fields from the tool dock onto the form.

Figure 13 Field tool

You have the following options:

� To make an expression field (expression fields are read-only), drag the fieldto the form.

� To make an input field, hold down SHIFT and drag the field to the form.

� To add the field description as a static text field next to the expression field orthe input field, hold down CTRL, and optionally SHIFT, and drag the field tothe form.



Control positions

To change the size or position of a control, you must first select the control.

The following table explains how you can position the controls:

Positioning of controlsIf you want this Do thisTo select a control Click the control in the form editor. A frame appears

around selected controls.To select multiple controls Hold down SHIFT and click on a number of controls

one by one.

If you turned the select tool on, you can drag arectangle around several controls to select all ofthem. Click the Select Tool button to turn the selecttool on.

To change the size of acontrol

Select the control and drag the edges or thecorners of the control's frame.

To move controls Select the controls and drag them to a newposition.

To display a grid on theform area

Click Grid on the View menu.

To alter the grid size Click Grid Sizes on the Options menu.To ensure that any controlyou move is aligned withthe grid

Click Snap to grid on the Options menu.

To align controls with eachother

Select the controls and click Align on the Objectmenu.

Cut-and-paste

To move or copy controls to other form pages or other forms, you can use thestandard Windows cut-and-paste functions. After you click Paste on the Editmenu, you can specify the location where the contents of the clipboard must beplaced.

Overlap of controls

If controls of the form can overlap, you can determine which of the controls is ontop, and which control is partially hidden by the other controls.



Control properties

To change the properties of existing controls, double-click the control. If youselected the Link form to actual data option, you must select the control anddouble-click the outside edge of the control.

Runtime hiding of controls

You can link a condition expression to each control that determines whether thecontrol will be visible. In this way, you can configure the runtime appearance ofthe form.

Tab order

You can specify the tab order for input fields and push buttons. If the end userpresses TAB, the focus moves from one control to another according to this taborder.

Form pages

Forms can have more than one page. If the form appears as a dialog box, thepages are shown as tabs. You can also switch from one page to another by usingthe operations of the View runtime object in a script. You can link this action to abutton on the form or to other events.

Use the PAGE UP and PAGE DOWN keys to move between pages in the formeditor.

Form events

You can define scripts that are triggered by specific form events. For example,Before insert record or After insert record.

Link to data

To test the form, you can link the form to actual data. The controls are thenactive and display the data to which they are linked. Buttons, for example, areactive, and if you click a button, the button�s process runs.

To turn this option on or off, click the Link button.



Expression fieldsExpression fields contain statements to be evaluated of which the results aredisplayed.

To use special field types to display data, such as a pie chart, or a bar chart, youcan use input fields instead of expression fields. Select the read-only attribute ofthe input field.

The following table lists the properties of expression fields:

Expression field propertiesProperty DescriptionExpression The expression whose result appears if the form is linked

to data.Condition The expression that determines whether the expression

field is visible.If this expression evaluates to a number other than zero,the expression field will be visible. Zero denotes False,non-zero denotes True.

Format fornumbers

The formatting string that defines the number format forthe result of the expression.Zero (0) indicates a required digit and the number sign (#)indicates an optional digit.For example, suppose the number 20123.147 must bedisplayed.Format #0.0000 displays 20123.1470Format #0.00 displays 20123.15Format #,##0 displays 20,123Format $#,##0 displays $20,123

Font, Alignment,and Shadowproperties

The font, alignment, and shadow properties determine howthe result of the expression appears. These properties aredescribed in detail later, in the table of text properties.

NOTE



Input fieldsInput fields enable you to control how data appears on the form and how theform can be edited.

Input field propertiesProperty DescriptionExpression The expression whose result appears if the form is linked

to data.This expression must be a left-hand expression, that is, anexpression to which a value can be assigned, for example,a field from a row type or a global variable.

Type The type of input field, for example, text box, check box,combo box. The input field's expression determines theenabled types. For example, a Grid Table option will onlybe available to you if your expression returns a table.A full list of input field types is listed in the next table.

Update underlyingdata

If you select this check box, the underlying data isupdated.If you clear this check box, you can still enter the data inthe input field, however, you cannot save that data. Thefield will be effectively read-only.

Condition The expression that determines whether the input field isvisible.If this expression evaluates to a number other than zero,the input field will be visible. Zero denotes False, non-zerodenotes True.

Description The text that appears as the label of the input field if thefield type is Checkbox. The description of other fieldsappears as a tool tip if you keep the mouse pointer overthe field.You can enter a text in multiple languages. For moreinformation, see Chapter 15, �Language support.�

Identifier A text string that acts as an alias for the object in the form.An identifier enables you to refer to the identified object ina script or expression.

Help topic The number of the help topic associated with the inputfield. Used to provide context-sensitive help.



The following table lists the available types of input fields. Each type of inputfield has its specific properties which are described in the online help.

Input field typesData type Field type DescriptionNumber Number The usual input field for numbers.

Check box An input field linked to a number. If you selectthe check box, the value is 1, if you clear thecheck box, the value is 0.

Amount An input field for money.Colored number A field that changes color if the number exceeds

a certain range of values.Coloredpercentage

A field that shows the change from the field�sprevious value with color coding. For example,the field can appear in red if the value dropsmore than 20% from its previous value.

Gauge A field that displays numbers graphically on agauge meter.

Ratio A field to display numbers as hundredths of agiven number.

String Text A regular input field for text.Expression An input field where you can open the

expression assistant by double-clicking in thefield or pressing the F4 key.

Multiline A text input field for more than one line.Combo edit A drop-down list accompanying the given text.Process A multi-line input field where you can open the

script assistant.Table list field A drop-down list, from which the end user can

select a text. The entries in the list areassembled from tables.

Object browserfield

A browser, from which the user can select anobject. The result of this selection is the pathand name of the object. For example, you canuse this browser to select a user object.

File path An input field that is used to enter a file's pathand name.

File shortcut An input field used to select a file by browsingthrough a folder tree.



Input field types (continued)Data type Field type DescriptionEnumeration List A list box that shows all the values for the

enumeration logical data type. The end usercan choose an entry by clicking.

Combo box A field that displays the currently selected entry,combined with a drop-down list to select fromthe available options.

Radio button A set of round buttons used to select one of agroup of mutually exclusive options.

Date Date A field to enter dates. The field has specialbuttons to select the date, month, and year.

Tableexpression

Grid viewer A regular table field that displays the rows of thetable. The table expression can refer directly toa table name or can process the contents of atable before the table appears.

Grid editor A table field that enables the user to edit thecontent.You can provide a grid editor with eventhandlers for the following events: Entering arow, Leaving a row, Deleting a row, andInserting a fresh row.

Table combobox

An input field that displays only one row of atable. If you click on a button next to the inputfield, a table grid opens, which displays all therows in the table.

Graph A field for displaying an OLE2 graph based on atable that contains rows with two number fields.

Void HTML Viewer A field which can display HTML pages. You canuse this field to create a web browser.

Ole object A Microsoft COM Automation objects,sometimes also named OLE or ActiveXcontrols.You must specify the CLSID or PROGIDidentifier for the COM class that implements thecontrol.

Mailbox field A field that displays the mailbox of the currentuser.



Push buttonsYou can use buttons on a form to enable the user to execute an action, forexample, to run a script. You can specify the following properties for buttons.

Push button propertiesProperty DescriptionType Specifies what will appear on the button.

Text specifies that a fixed text is shown.Expression specifies that the result of an expression isshown on the button.Picture specifies that a picture is shown on the button.

Text The text on the button.You can configure fonts and font styles in the tool dock'stext tool. You can drag these font styles from the tool dock,and drop them on a text.

Expression The expression whose result appears on the button.Picture The picture to appear on the button. You can select a

picture object from the object repository.Description The description which appears in the popup help when the

user's mouse rests over the button.Condition The expression that determines whether the text is visible.

If this expression equates to a number other than zero, thetext will be visible. Zero denotes False, non-zero denotesTrue.

Identifier A text string that acts as an alias for the object within theform. An identifier enables you to refer to the identifiedobject in a script or expression.

Help topic The number of the help topic associated with thepushbutton field. Used to provide context-sensitive help.

Show frame Specifies that a box frame is drawn around the button.However, this function is only for picture buttons.

Default Specifies that this is the default button, and that pressingENTER is equivalent to clicking on it.

Action to perform The action that is performed when the user clicks thebutton. The action can be defined with the action wizard.Example actions are: send an e-mail or an Brokermessage, or run a script.For more information, see the Action wizard section inChapter 9, �Tools and assistants.�



Static textStatic text on a form can be used for field labels and headings. You can configurefonts and font styles in the tool dock�s text tool. You can drag these font stylesfrom the tool dock and drop them on a text.

You can specify the following properties for texts:

Text propertiesProperty DescriptionText The text that appears on the form. You can enter a text in

multiple languages. For more information, see Chapter 15,�Language support.�

Condition The expression that determines whether the text is visible.If this expression evaluates to a number other than zero,the text will be visible. Zero denotes False, non-zerodenotes True.

Font The font in which the text appears. You can select the fontfrom a list of all installed TrueType fonts.

Style The style in which the text is appears, such as regular,bold, italic, and so on.

Size The font size. You can select a size in the range from eightto 72 points.

Strikeout If you select this option, a horizontal line is drawn throughthe text.

Underline If you select this option, the text is underlined.Fit If you select this option, the text will be stretched or

condensed to fit the boundary of the text object. This effectoverrides and disables the setting in the Size field.

Foreground color The color of the text.Background color The background color of the text object, in the the

rectangular field area.Alignment The text can be aligned horizontally, left, center, or right,

and vertically, top, center, or bottom, in the field area.Shadow placement You can specify a text shadow positioned to the top-left,

top-right, bottom-right, or bottom-left side of the text.Shadow size The distance of the shadow from the original text.Shadow color The color of the text's shadow.



PictureA picture is used to make a form visually attractive and easily recognized, or toadd logos and symbols to the form. You can place the picture anywhere on theform. If you want to show the same picture in many forms, you can place thepicture in a separate form that is inherited by other forms. You can also specify abackground picture for a form in the form properties.



Picture propertiesProperty DescriptionPicture The picture object that you want to display somewhere on

the form.If the picture is Read from repository, you can specify apicture object from in the object repository.If the picture is read from file, you can specify the path ofthe picture file on your client system.

Mode The way the picture is positioned in the allotted space.� Fit in specifies that the picture is reduced in size if

necessary, to make the picture fit in the available areaof the picture control. The proportions remainunchanged, therefore the picture is not distorted. If thepicture is smaller than the available area, the picturewill not be enlarged.

� Center specifies that the picture is centered in theavailable area of the picture control. If the picture islarger than the control, the picture is masked so thatthe parts beyond the edges of the control are notvisible.

� Stretch specifies that the picture is stretched to fill theavailable area of the picture control. This can distortthe aspect ratio of the picture.

� Tile specifies that the picture is tiled. The picture isshown in original size as many times as required tocover the available area. The central tile is always atthe center of the picture control.

� Zoom Specifies that the picture is enlarged in size ifnecessary, to make the picture fit in the available areaof the picture control. The proportions remainunchanged, so the picture is not distorted. If the pictureis larger than the available area, the picture will not bereduced in size.

Allowed to bleedoutside form (checkbox)

Usually, a window is automatically sized at run-time toenclose all fields. This check box, if selected, excludes thispicture field from consideration in this automatic sizing.This enables you to design features that bleed off the edgeof the form.

Condition The expression that determines whether the picture isvisible.If this expression evaluates to a number other than zero,the picture will be visible. Zero denotes False, non-zerodenotes True.



Static boxA static box, or group box, is used to group fields and other form controlstogether visually, for example, in a rectangular line.

Box propertiesProperty DescriptionColor (fill) The color with which the box is filled.Shadow color The color of the shadow of the box.Show sides (top,bottom, left, right)

Specifies exactly which sides are visible. If you selectrounded corners or a frame with a three-dimensional lookfrom the Type list, all sides are visible.

Color of frame The color of the box frame. This option does not affectboxes with a three-dimensional type.

Type The style of the box frame, for example, continuous line,dotted line, or line with three-dimensional effect.

Thickness The thickness of the box frame.Rounded corners If this option is turned on, the box frame has rounded

corners.Condition The expression that determines whether the box is visible.

If this expression equates to a number other than zero, thebox will be visible. Zero denotes False, non-zero denotesTrue.



OperationsThe form object has operations to print and to display the form.

The following table lists the operations of the form object.

Form operationsOperation Descriptionprint Prints the form. You can specify the page numbers that must be

printed as well as several print options.run Brings up a window showing an instance of the form.

You can specify the value to display, for example, a file object ora text string.By default, the form appears as an MDI window. The form canbe appears as an MDI window, a modeless dialog box or as amodal dialog box. The default is an MDI window.

runModal Brings up a modal dialog box showing an instance of the formthat displays a certain value.The operation returns if the dialog box is closed.

runModeless Brings up a modal dialog box showing an instance of the formdisplaying a certain value.The runModeless operation returns immediately after the dialogbox appears. The dialog box will remain visible until explicitlyclosed by the user or by a View.close operation run in the forminstance.

For details about these operations, refer to the document Scripting LanguageReference (U7278D US).



Value, State, Page

In the expressions in a form, you can use the variables Page, State, and Value.These variables are visible in the form itself, but not to other objects. You canuse the variables can be used in expressions and processes inside forms. Thefollowing table shows the function of these variables.

Variables of form instancesVariable FunctionPage The Page variable stores a number that indicates which page of

the form is being viewed.State The State variable stores a value of the StateType enum type,

which indicates whether the form is connected to data for viewingor for inserting or is designed in the form editor. For moreinformation, refer to the �State variable� section in the ScriptingLanguage Reference [U7278D US]).

Value The Value variable stores the form's current underlying value.The type of this value is the same as the type of the form, which isset in the Form Properties dialog box.For example, if the form's logical data type has a PrintMe()operation, you can invoke this operation by writingValue.PrintMe() in a script.

View object

Every run-time instance of a form in the Broker system has an associated Viewobject. The operations of the View object can only be used in expressions andprocesses inside the associated form.

The following table lists the operations of the View object. These operations aredescribed in detail in the Scripting Language Reference (U7278D US).

Operations such as insert, update, delete, goFirstRow, and isNew, are onlyapplicable if the form instance displays a row from an underlying table. For moreinformation, refer to the �isTable operation.�

NOTE



View operationsOperation Descriptionclose Closes this form instance.copy Saves the current table row and creates a fresh row to be

inserted in the table, and initializes the row with a copy ofthe data in the current row.

insert Saves the current table row and creates a fresh row to beinserted in the table, and initializes the row with the defaultvalue of the row type.

lock Rereads the currently viewed row from the underlying tablewith an update lock, and displays the row for modification.Usually, locking occurs automatically.

update Saves the changes that have been made to the current rowin the underlying table.

delete Removes the currently displayed row from the underlyingtable.

field Looks up and returns a form field (control), identified by theform field�s identifier, as an object.

goFirstPage,goLastPage,goNextPage,goPrevPage,goPage

Go to the indicated form page.

queryNumPages Returns the number of pages in the current form.goFirstRow,goLastRow,goNextRow,goPrevRow

Attempts to update the current row in the underlying table. Ifsuccessful, the first, last, next, or previous row in the tableappears.

isModified Returns TRUE (1) if the currently displayed row has beenmodified but not updated in the database.

isNew Returns TRUE (1) if the current table row is a new (fresh)row that has not yet been written to the database.

isTable Returns TRUE (1) if the viewer displays a row from anunderlying table.

print Prints the form instancerecalc If the form instance displays a query result, recalc () forces

the system to re-evaluate the query expression and todisplay its new value in the form instance. This can be usedto force updates of query results from real time data.

refresh,refreshNow

Ensures that all controls and fields in the form displayupdated values.



setZoom Sets the zoom factor (in percentage) used to display thecurrent form instance.

queryInvokedBy Returns a string that contains the full path and name of theobject that invoked the form instance in question. Forexample, the message object behind a form.

Global variablePurpose

Global variables store values of a primitive type or a logical data type. You canchange the value of the variable in expressions and scripts.

The values of global variables are stored in the central object repository. Thismeans that they can be set from one client and read from another clientimmediately thereafter.

Creation

To create a global variable, take the following steps:

1 Open the repository browser folder where you want to store the globalvariable object.

2 Click the New Global Variable toolbar button.

A dialog box appears in which you can specify the global variable's properties.

Click Assign Now to assign the initial value to the global variable.

Use

Global variables must be written as a whole, using the set operation. Assigning toindividual fields or subcomponents of global variables is not supported.

The following example shows a script that is applied if some button on abackground form is clicked. The script starts the editor for the SalesReport query,and uses the LastEdited variable to register when the query was last changed inthis way. The LastEdited variable is initialized with the expression Time().

if (SalesReport . edit ())

LastEdited.set ( Time () ); // Time stamp

LastEdited can only be assigned a value of the logical data type Time.



Properties

The following table lists the properties of global variable objects.

Global variable propertiesProperty DescriptionName The name of the global variable.Description Language-dependent description. For more information, see

Chapter 15, �Language support.�Type The type of values that the variable can store.

The variable�s logical data type is determined by the valueused to initialize the variable, or by the value first assigned tothe variable.

Value The value that is currently stored in the variable.Initial valueexpression

The expression that provides the initial value of the globalvariable. This property is optional.

Operations

The following table lists the operations of the global variable object:

Global variable operationsOperation Descriptionget Returns the current value of the global variable.

Example:CustomerType cus = \Vars\MyVar . get;The variable content can also be read directly, as in:CustomerType cus = \Vars\MyVar ;

set Sets the value of a global variable. The value must be of thesame type as the variable itself.Examples:\Vars\MyVar . set (cus);\Top10Customers . set (Customers . calculateTop10 ());

For details about these operations, refer to the Scripting Language Reference(U7278D US).



IteratorPurpose

Iterators are used for fast bulk synchronization of data between a singleoriginating component and multiple destination components. Iterators are usuallyapplied in batch processes that are executed at regular intervals in order tosynchronize the data between applications (components).

An iterator has two main phases, an initialization phase and an iteration phase.For example, an iterator can use the initialization phase to connect to an externaldata source and get a table of new records and use the iteration phase to iterateover the rows in the table, storing them into the destination components.

The synchronize operation on a logical data type will execute load and storeoperations on a record-by-record basis. The synchronize operation of an iteratorgives you more flexibility and potentially a better performance.

The originating component is specified in the iterator object. The destinationcomponents are specified in the iterator's result type. Destination components canbe added, removed or their data mapping modified without affecting theoriginating component or the iterator object.

For more details on Iterators, refer to Chapter 21 �Iterators.�

Creation

To create iterators, take the following steps:

1 Open the repository browser folder in which you want to store the iteratorobject.

2 Click the New Iterator toolbar button.

A dialog box appears in which you can define the iterator's properties.



Properties

The following table lists the properties of iterators.

Iterator propertiesProperty DescriptionName The name of the iterator.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Type of iteratorparameter(optional)

Type of the optional parameter that can be passed to therun or synchronize operation of the iterator. Thisparameter can be a primitive type, such as String, or auser-defined type, such as a row type.If you do not need parameters, you can specify the type asVoid.

Type of iteratorstate

The logical data type of the iterator state.The iterator state contains the information that is passedfrom the initialization phase to the iteration phase.For example, suppose that the initialization phasepopulates a table that is accessed during the iterationphase. You can create a row type of which one of thefields is the table that is passed from initialization toiteration. The iterator state can also contain a counter field.

Type of iteratorresult

The logical data type that is used to hold the result of eachiteration. In other words, the data type whose Store andStoreNew primitives are called for each result record,which is usually a Row type.

Originatingcomponent

The originating component that is used to check whetheror not the results are already known to the Broker. If theresults are known, a Store cycle is initiated, otherwise aStoreNew cycle is initiated.

Reconstruct resultvalue for eachiteration

If you select this check box, the iterator will reset eachmember of the result type to its default value, and call theConstruct primitives for each participating component atthe start of each iteration.If this check box is cleared, the Broker will not modify thefields of the result type between iterations. This can resultin a better performance, but values will carry over from theprevious iteration. You must, if necessary, ensure that theiteration script sets or clears members of the result type.



Assume all rowsare new

If this check box is selected, all result rows are considerednew. This means that the StoreNew primitive is alwayscalled.If this check box is cleared, the system first checks thecode mapping table to see if the object already exists,unless the SYNC_ALWAYS_NEW flag was specified inthe synchronize operation call. For more information, seethe description of the synchronize operation below.

Initialization script The script that performs any necessary initialization.Typically, the initialization script accesses the originatingcomponent to determine what objects must besynchronized. In BaanERP you can use a NetListoperation of the Business Object Interface (BOI) to obtaina table of all modified rows.The optional parameter that is passed with the iterator'srun or synchronize operation is available in a variablecalled Parameter.The iterator state is accessible through a variable namedthis.

Iteration script The script that is executed during each iteration.The iterator state is accessible through a variable namedthis.The iteration script has the following responsibilities:� The script must access the next record to process, for

example, by using a Table::next operation on a table,or by performing a Next operation on a COM object.

� The script must set the fields of the iterator result. Theiterator result is accessible through a variable namedResult. After each iteration, the iterator result's store orstoreNew operations are called.

� If the iteration phase is completed, the script mustreturn the number 0. In that case the iteration stops. Ifthe iterations must proceed, the script must return thenumber 1.

Logging properties These properties determine which actions are logged inthe logging system. For more information, see Chapter 18,�Logging system.�



Operations

The following table lists the operations of the iterator object.

Iterator operationsOperation Descriptionrun Returns a table where each row is of the iterator result

type. This operation is used to test the iterator. No datastorage is performed.The operation has one optional parameter. The type of thisparameter is specified in the Type of Iterator Parameterfield. If the iterator parameter is of type Void, theparameter can be omitted.Example: \MyIterator.run("Testing").viewThis example runs the iterator and displays a table of theiteration phase result rows.

synchronize Executes the iterator, that is, performs the synchronization.For example:\MyIterator.synchronize ("Testing", SYNC_STORE_ALL +SYNC_ALWAYS_NEW).



The synchronize operation has the following parameters:

Parameters of the synchronize operationParameter DescriptionIterator parameter A parameter that is passed to the initialization phase in the

Parameter variable. The type of this parameter is specifiedin the Type of Iterator Parameter field. If the iteratorparameter is of type Void, this parameter can be omitted.

Flag parameter The flag parameter can be a combination of the constantsSYNC_STORE_ALL and SYNC_ALWAYS_NEW. (Both ofthese are defined in the \predef\system folder).If the SYNC_STORE_ALL flag is specified, the Brokerstores each result object in all participating components,including the originating component. In this case, theBroker ends the store cycle by calling the Store primitive inthe originating component (and PrepareStore andRollbackStore, as applicable).If you are sure that the originating component already hasan up-to-date version of all result objects, you do not needto specify this flag.If the SYNC_ALWAYS_NEW flag is specified, the Brokerassumes that the object in the originating component isalways a new, fresh object. This speeds upsynchronization by saving a lookup in the code map tableto check whether the object already exists. Use this flagonly if you know that the object is in fact not alreadypresent in the system.If the Assume all Rows are New check box of the iteratorhas been selected, specifying the SYNC_ALWAYS_NEWflag makes no difference.

Example scripts

The iterator is connected with an external application through an OleObject. Thisis a COM object that knows about new customers in the originating component.The OleObject is stored as one of the fields of the iterator state. The initializationscript sets the OleObject in the iterator state.

{

this.objCustomer =

OleObject("MyCustomers.NewCustomers");

// 'this' represents the iterator state

}



The iteration script iterates over the new customers by using the Next operationon the COM object. In this example, the COM object is assumed to return aboolean value.

{

if (Number(this.objCustomer.Next())) {

Result = obj;

// Map between the result type attributes

// and the COM object attributes

return 1;

}

else

return 0;

}

As long as there are new customers, the Next operation returns TRUE, in whichcase the iteration script must return a 1. If no new customers exist, the iterationscript must return a 0 to indicate to the Broker that the iterator has completed itslast iteration.

ITK MergeThis section defines the changes required to merge the existing ITK integrationsolution that BaanSCS developed with Baan OpenWorld Broker. OpenWorldBroker will use some of the technology that is already designed for the otherintegration solutions. Examples are the ITK Library designed by BaanSCS andthe Enterprise connector designed by Baan.

Three new types of named objects that are required for point-to-point integrationare defined in this section. The role of each object is specified, as well itsposition in the existing parts of the OpenWorld Broker. This section providesinformation on where and when the existing tools, such as ITK Library, B3 bus,and the BOIs are used.

Design Overview

The following three new object types must added:

�� Scripts: Objects that only store scripts.

�� Tasks: Definitions of actions where the action wizard is used.

� Profile: Object that stores a list of tasks that are executed when the profile isexecuted.



These new integration types require changes in existing objects, such asComponents and Iterators. The OpenWorld Broker will be further enhanced byadding or modifying the following:

� Logging System. A new logging system for the new integration type detailedin the document. The logging system stores one-to many relations; that is, ajob can have many tasks and each task can have many transactions.

� Configuration utility is a modified object repository browser with a few newfeatures. For example, the user cannot select in which folder the objects arecreated. This utility only displays named objects that are in the \itk folder.

� Field mapping object is a user interface that enables you to set mappingbetween two tables. The definition of the field mapping object is in anotherspecification.

� Point2Point is defined in another specification.

The action wizard is changed so you can run iterator, adapter service and runscript.

Design Approach

The ITK merge subsystem has the following design principles:

� The structure/interface of the tree/objects that are displayed to the user mustbe similar to this in the ITK Configurator.

� If you provide a new object browser that controls the structure of the storedobjects in the repository, you can more easily use the system when youdesign an integration solution. The user will not get lost in the forest of thecurrent object repository tree.

� The Adapters provided by BaanSCS will be used in the new integration.

The existing scripts that are developed in ITK Configurator are used in the newintegration subsystem, and few modifications will be made on these scripts.

Configuration UtilityThis part of the design is postponed.



Scripts

Description

For the task object, and therefore for the profile objects, the repository willcontain new named objects, which are pure script (IActive script). To be able tocreate such scripts, which only enable the user to enter necessary information tostore script in the repository. A name, description and information needed for theIActive support, and the script itself are the only things that will be stored.

Behavior

You can only run these scripts where the action wizard is used.

Therefore, a script can be run as a part of a task and as part of a profile. Tasksand Profiles are described later in this document.

Attributes

With the script object, a name and a description, like in any other named object,and the attribute for the IActive script

You can set parameters/variables in the action wizard. In other words, you canuse a variable that is not defined in the script. When a task that runs a script iscreated, then you can set up these parameters, and when the script is run, thenthese parameters are set in the context of the script.



User Interface

Adapter - Service

Description

Service is a set of operations that are available for each component. To display alist of predefined operations for a component, you can ask the ITKAdapterManager for the list. For each of these predefined operations that is usedin a profile, two events have a predefined name and context. These events areOnStartService and OnTerminateService.

Attributes� Adapter

If a component is created in the Broker, you can assign an adapter to thecomponent. The user can select available adapters from a list. This list will beread from the Adapter Manager, which lists all adapters that are installed onthe specific machine. The adapter lists all available services.



� Connection StringIf necessary, you can enter a string in a predefined format to connect toanother server, use another database, or logon as a different user. In mostcases, the connection string can be left empty and then, if the adapters arecorrectly set up, the connection string will connect to a default server anddatabase (application setup).

� Component InstancesIf you use the component and one or more instances are defined, then theconnection string from the component instance is used to connect. Theseconnection strings do overwrite the connection string entered in theConnection String field on the first tab of the component.

� ServicesFor each selected service,e you can enter a script for two events, namelyOnStartService and OnTerminateService.

� OnStartServiceThis is a script that you can run before each component service is carried out.You can perform any initialization in this script, for example, preloading datainto the dictionary.

� OnTerminateServiceAfter the service is run, this event is carried out. All necessary clean up isperformed in this event.

Behavior

Depending on what adapter the user selected on the first page of the componentdialog, a list of services from that adapter is generated and listed on a separatetab. For each service, the user can enter optional events.

Calling a Service can be part of a Task, and therefore part of a Profile.



User Interface

Tasks

Description

A new named object type is created, called Task, in the Broker. A task is a partof the profile definition. The task is only a name, description, and action of theaction wizard.

This document lists the three new action kinds.

Attributes

To create a task, a wizard is used. The first page will list the name, description,and kind:

� Name.The name of the object to identify the object in the repository.

� Description. Short description of the object.

NOTE



� Type. What type of task is this?

� See the specification of the Action Wizard for the preexisting types in theaction wizard

� Start an iterator.An instance of an Iterator object is selected. An expression for a parameter isalso entered.

� Script.A script is selected. The user can select from all available scripts.

� Service.To select a service, the user first selects a component. Depending of thecomponent selection, a list of services for this component appears. This list isgenerated with the ITKAdapterManager class.

Start an iterator.

To start an iterator, take the following steps:

1 Select an Interator that must be run.

2 Enter an expression that returns a value of the same type as the parametertype in the selected iterator. This field can be empty, as a default value is thenused.

3 Use flags when the iterator runs. Synchronized is run on the iterator.

Run an adapter service

To run an adapter service, take the following steps:

1 Select a component that has an adapter selected. When the component isselected, the services are listed in the Available services list.

2 Select which service you want to run.

3 Click Next to continue with the wizard. If you selected a new service, thenthe system generates a list of parameters for selected service. Enter anexpression for each parameter that returns a value of the same type as theparameter.



Run an IActive script

To run IActive script you, take the following steps:

1 Select a script to run.

2 Click Next to continue with the wizard.

3 Enter some parameters/variables that are used in the script. These parametersare set in the context of the script before it is run

The Enabled check box indicates whether a task is enabled or not. If a task isdisabled and is a part of a profile, this particular task is skipped when the profileis carried out.

Behavior

This Task Object contains enough information for you to perform a completedata transfer between two components. In other words, to map the data betweentwo objects and run all appropriate script so the data transfer will be performedproperly. The task object can also only run a script that is selected from theobject repository. These scripts are the script objects that are mentionedpreviously in this document.

User Interface



Profiles

Description

A new type of named object is created in the Broker to store information requiredfor profiles. A profile is a list of actions that must be performed to complete adata synchronization between two components.

Attributes� Name.

The name of the profile identifies the object in the repository.

� Description.Short description of the object.

� LogLevel.The detail of logging is determined.

� Run in MTA.The profile can be run either in Multithreaded Apartment (MTA) orapartment threaded.

� Available tasks and profiles.A list of all tasks and profiles in the repository is provided and the user canselect one or more tasks for this profile. You can also select another profile asone of the tasks. The system will check for recursion, that is, a profile cannotcontain itself or another profile that contains the current profile. The user canalso change the order of the tasks, that is, in what order the tasks are carriedout. The selected task will not run in parallel, that is, a task will not start thenext task before has finished.

You can disable one ore more selected tasks/profiles in the current profile.Double-click on the selected item to toggle the Enable status.

Behavior

A profile is a collection of tasks that must be carried out. If a profile is carriedout, all tasks that are enable and selected as part of the current profile and arecarried out if they are disabled. These tasks can be of various kinds; data transfer(that is a point-to-point Iterator), run a script, or perform a component service.These types of tasks are explained in the section on tasks.



User Interface

Logical data typePurpose

Logical data types describe the nature and structure of data. This logical datadescription is independent of the physical form of the data being processed.

For a general introduction on logical data types, see Chapter 5, �Logical datatypes.�



The following table describes the four different variants of user-defined logicaldata types:

Logical data typesData type DescriptionRow A collection of data fields, each of which can have a different

logical data type. You can use a row type to define the structureof records. For example, Employee number (Number), Name(String), Date of birth (Time), Department (String).

Table A collection of elements of an identical type. The number ofelements in a table can grow or shrink as required. For example,you can store a list of customers in a table.

Array A collection of elements of an identical type. Arrays have a fixednumber of elements. For example, you can use an array ofstrings with twelve elements to store the names of the months.

Enumeration An enumeration type is a logical data type describing the statusof an object or event. Each possible status is represented by aname. For example, a StudentLevel enumeration type couldconsist of the names: Novice, Intermediate, Advanced.

Creation

To create a logical data type, take the following steps:

1 Open the repository browser folder where you want to store the logical datatype object.

2 Click the New Logical Data Type toolbar button.

A dialog box appears, in which you can select the data type, such as Row, Table,Array, or Enumeration, of the logical data type and enter the name anddescription. If you click OK, the type editor appears, in which you can add therelevant elements to the logical data type. For details about the type editor, seethe �Logical data type, creating� section in the online Help.

If the type editor�s autoparse feature is turned on, each script in the logical datatype is immediately checked for errors, such as nonexistent objects. Click theToggle autoparse button to turn autoparse on or off.

Properties

Each of the types of logical data type (Row, Array, Table, and Enumeration), hasa set of properties that you can maintain. First the properties that are common toall user-defined logical data types are described, in particular the propertiesrelated to components and operations. Later, the properties that are specific tocertain types of logical data types (for example, Row) will be listed.



The properties are explained in the following tables:

� General properties of logical data types.� Properties of a logical data type's components.� Transaction control properties for components.� Properties of a logical data type's operations.� Properties of the fields of a Row type.� Properties of Table types.� Properties of Array types.� Properties of the elements of an Enumeration type.

General properties of logical data typesProperty DescriptionName The name of the logical data type.Description Language-dependent description. For more information, see

Chapter 15, �Language support.�Data-type Specifies the type of data that can be stored in values of these

logical data types (Row, Table, Array, or Enumeration). Afteryou define the logical data type, you cannot change the data-type anymore.

Components(optional)

A component represents an external application, such asBaanFrontOffice or CODA-Financials. If you define acomponent for a logical data type, you can load data from andstore data in the external application.

Operations(optional)

You create operations that can be executed with the logicaldata type. These operations can be started through shortcutmenus or the scripting language.For example, if you have a CustomerTable logical data type,you can create a RankBySalesVolume operation.



Component properties

For each component of a logical data type, you must specify how the componentparticipates in the type. In other words, you must specify how data is receivedfrom and sent to the component, which you can do by maintaining the followingproperties:

Properties of a logical data type's componentsProperty DescriptionParticipatingcomponent

A component object that represents the application thatparticipates in the logical data type.

Component code The unique code that identifies the session. This code isused because one component can have multiple sessionsrunning simultaneously. In that case, the component objectrepresents a specific session of the component.The component code is copied from the Unique code fieldof the component object.

Subsystem code The subsystem code that is required by the code map toidentify the data in the application.For example, a value of the CustomerRow logical datatype represents a customer. In one component, customersare stored in the Business_Partners subsystem andinventory items are stored in the Item_Master subsystem.In another component, customers are stored in theCUS001 subsystem and items are stored in the ITM010subsystem.If you want to avoid the code mapping overhead, you mustleave this field blank. In that case, the Broker does notmaintain a code mapping relation for that particular typeand component combination.

Implementationsfor primitiveoperations

You must supply an implementation (a script) for thefollowing primitive operations:Construct, Load, Store, StoreNew, and DeleteThese operations can be invoked by the componentintegration subsystem. For more information, see Chapter7, "Component integration.�



If you define multiple components, you must specify the following transactioncontrol options.

Transaction control properties for componentsProperty DescriptionLoad data intimestamp order(check box)

Specifies that the Load primitives for the components mustbe loaded in date and time order. The oldest data isloaded first.

Store data using atwo-phase protocol

Specifies that the PrepareStore, PrepareStoreNew, andPrepareDelete primitives will be called before the Store,StoreNew, and Delete primitives.The PrepareStore, PrepareStoreNew, and PrepareDeleteprimitives prepare for the update, insertion, or deletion ofthe instance and do an error check. If an error is found anexception will be thrown.

Invoke rollback iferrors occur whenstoring data

Specifies that the RollbackStore, RollbackStoreNew, andRollbackDelete primitives will be called if an exception isthrown. This undoes any changes made in the Store,StoreNew, or Delete primitives that caused the error.



Operation properties

For each user-defined operation of a logical data type, you must specify theparameters and implementation, which you can do by maintaining the followingproperties:

Properties of a logical data type's operationsProperty DescriptionName The name of the operation.Description An extended language-dependent description of the

operation. For more information, see Chapter 15,�Language support.�

Short name fordisplay purposes

The description that appears in the user interface, forexample, in the shortcut menu.

Visibility Specifies the visibility of this operation to other objectclasses.Private specifies that the operation is unavailable to anyclasses but this one and the classes derived from it.Public specifies that the operation is generally available.

Show in contextmenus (check box)

If you select this check box, forms and workflows that usethis data type show the operation in the shortcut menu.You can usually get the shortcut menu through right-clicking. The operation can then be run from the shortcutmenu.

Parameters The parameters that you can pass to the operation if youinvoke the operation. You must specify each parameter'sname, description, and type.The mode of the parameter determines whether the valuecan be changed by the operation. If you want to use aparameter for output, you must set the mode of theparameter to in out. In other words, the parameter ispassed by reference. If you set the mode of the parameterto in, the value of the parameter is cannot be changed bythe operation. (The parameter is passed by value).

Implementation The program script that is executed if the operation isinvoked.



Row types

The following table describes the properties that you can define for logical datatypes of the Row data-type. A row type can have components and user-definedoperations. These features are described in the previous sections.

In general a row consists of a number of fields. These fields have the followingproperties:

Properties of the fields of a Row typeProperty DescriptionName The name of the field.Type The type of the field. You can choose a built-in type, such

as a String, Number, or Time object. You can also choosea logical data type here.

Description An extended language-dependent description of the field.For more information, see Chapter 15, �Languagesupport.�

Short name fordisplay purposes

The description that appears in the user interface, forexample as a label on a form.

Default value The default value for the selected field, which must be ofthe same data type as the field itself.You can enter an expression that evaluates to the defaultvalue.

Visibility Specifies the visibility of this field to other object classes.Private specifies that the field is not available to anyclasses but this one and the classes derived from it.Public specifies that the field is generally available.

If a value is created of this type, the fields get a default value. If you did notspecify a default value in the definition of the row type, the following defaultsapply:

� Number fields: The default is zero.� String fields: The default is an empty string.� Time fields: The default is the system time at the moment that a value of the

logical data type is created.



Table type

The following table describes the properties that you can define for logical datatypes of the Table data-type. A Table type can have components and user-defined operations. These features are described in previous sections.

Properties of Table typesProperty DescriptionElement The data type of the table elements. This data type is

usually a Row type.

Many operations are available for Table types, including sorting, selection,grouping, and projection. Many statistical and summary operations are available.For details about these operations, refer to the Scripting Language Reference(U7278D US).

Array type

The following table describes the properties that you can define for logical datatypes of the Array data-type. An Array type can have components and user-defined operations. These features are described in earlier sections.

Properties of Array typesProperty DescriptionNumber ofelements

The number of elements in the array type.

Element type The data type of the array elements. This data type can beany primitive or composite type.

The elements of arrays can be accessed in the scripting language as shown in thefollowing example:

Number n = MyArray [5]

This expression assigns the sixth element of MyArray to the variable n. Theelements are numbered from zero.

A number of operations are available for Array types, such as, max, min, avg(average). For details about these operations, refer to the Scripting LanguageReference (U7278D US).



Enumeration type

The following table describes the properties that you can define for logical datatypes of the Enumeration data-type. You can also define the components anduser-defined operations of enum types. These features are described in previoussections.

In general, an enumeration consists of a number of elements that represent thepossible values. These elements have the following properties.

Properties of the elements of an Enumeration typeProperty DescriptionElement The name of this value.Description A language-dependent description of the element. For

more information, see Chapter 15, �Language support.�

The following example shows how enum values can be used.

The \params\BasicColor object is an enumeration type that stores the entries{Red, Green, Blue}. You can use this in a script as follows:

{

\params\BasicColor colorVar = \params\BasicColor::Red;

if (colorVar == \params\BasicColor::Blue)

printf ("The color is blue.");

}

The elements of an enumeration type can also be identified by an integer number.For example, the BasicColors definition stores the entries {Red, Green, Blue}.The numerical equivalents of these entries are: Red = 0, Green = 1, Blue = 2.



Operations

The following table lists the operations of the logical data type object.

Logical data type operationsOperation DescriptionAsXML Returns a description of the type in an Extensible Markup

Language (XML) formatted string.Map Maps a code (primary key) of an object instance from one

component to another.New Returns a freshly created object of the type.Load This operation instructs the Broker to load a particular object

instance.synchronize This operation tells the Broker that a particular object instance

has been added or modified. The Broker will perform asynchronization cycle across the participating components toensure that they are all up to date.

delete This operation tells the Broker that an object instance specifiedby component and code has been deleted.

The use of these operations is explained in Chapter 7, �Component integration.�

MappingThe mapping object is created to support the definition, and run-time executionof field mappings between two data types. Currently, such mappings areperformed with the OpenWorld Broker scripting language, and the objective ofthis project is to provide a more user friendly and maintainable method to defineand carry out these mappings.

The mapping object contains two main entities:

� A mapping editor that handles the user interface for defining field mappingsbetween two data types. For more information, refer to the section �Mappingeditor.�

� A transformer that performs the run-time transformation from a source typeinstance to a target type instance, refer to the section �Transformer.�

The mapping object requires an addition to the OpenWorld Broker scriptinglanguage to support invocation of the map operation. For more information, referto the section �Scripting language.�



Design ApproachDesign principles for the mapping object are as follows:

� If you use the mapping object instead of scripting, this does not reduceperformance.

� The mapping object is flexible in terms of operations that can be appliedwhen mapping a source field to a target field. All operations on OW Brokerdata types can be used for this purpose. However, if a complex mapping isspecified, this mapping is not guaranteed to be supported in external tools,such as external data migration engines.

The mapping object is independent from the physical representation of the sourceand target types, and is not concerned with the persistence of the target instance.

Mapping editorThis section describes the functionality and interface of the mapping editor. Inthe section �Description� the two main responsibilities of the mapping editor aredistinguished:

� To implement the user interface that enables you to enable define fieldmappings between the types associated with the mapping object.

� To save and restore the mapping information associated with the mappingobject.

The user interface for the mapping editor is shown in section named �UserInterface.�

Description

The mapping editor enables the user to perform mappings between source andtarget fields in the data types defined for the mapping object. These types aredisplayed in the editor with a tree structure, refer to the figure in section �Userinterface,� and you can perform the mapping in three ways. Firstly, you can use adrag and drop operation to connect the source and target fields. These fields mustbe compatible, in other words, either both are of the same type or a predefinedconversion is available. Conversion is defined between the string, number, andtime types. For example, dropping the number field CustomerID onto a stringtarget field will result in the expression CustomerID.asString being assigned tothe target field.

A mapping between a source and target field can also be defined by directlyediting the mapping expression associated with a particular target field.



You can carry out this process with an expression editor to create an expressionthat defines the transformation from the source to the target. The mapping editorchecks the validity of each mapping expression, and a mapping object can onlybe saved if all expressions are valid. A valid mapping expression must have areturn type that matches the target field.

Finally, the mapping editor can provide automatic mapping between source andtarget fields. Automatic mapping is applied to fields that have the same name andare compatible with respect to their types.

The mapping editor supports composite data types, that is, data types that containother data types. Such composite types can be matched in whole with the dragand drop mechanism. As a result, and if possible, each fields contained in thecomposite type will automatically be mapped onto a corresponding field in thetarget type.

The mapping editor is responsible for storing information on the data typesassociated with the mapping object, and how the fields in these data types areconnected. In addition, each field mapping object stores scripts that are carriedout during the transformation between the two types. For more information, seethe section �Transformer.� This information is stored in the repository with themapping object as shown in the following table.

Name DescriptionHeader Information on size, creation date, and so forth.Type 1 A reference to a logical data type stored in the repository.Type 2 A reference to a logical data type stored in the repository.MapToType2 A list of string/expression pairs that define field mappings from

Type 1 to Type 2. Each pair contains one left-expression andone regular expression, such asType1Field.NestedField[1].AnotherField.

MapToType1 A list of string/expression pairs that define field mappings fromType 2 to Type 1. Each pair contains one left-expression andone regular expression such asType2Field.NestedField[1].AnotherField.

ScriptToType2 A script associated with the mapping from Type 1 to Type 2.ScriptToType1 A script associated with the mapping from Type 2 to Type 1.InstrToType1 A list of mapping instructions that define how to carry out the

mapping expressions defined in MapToType1.InstrToType2 A list of mapping instructions that define how to carry out the

mapping expressions defined in MapToType2.



The layout presented in the previous table entails that each mapping object storesinformation on mappings in both directions, from Type 1 to Type 2 and viceversa. The alternative is a separate mapping object for each direction. However,if you use two separate mapping objects, this makes it more difficult to assertthat updates to one object are reflected in the other, for example, when a newfield is added that uses the same field mapping in both mapping objects.

The mapping editor can also restore the information on the participating datatypes and field mappings. This erstoration is carried out each time a previouslystored field mapping object is invoked.

User Interface

This section describes the user interface for creating and maintaining a mappingobject.

To create a new mapping object

A new mapping object is created by pointing to New on the Objects menu, andthen clicking Mapper or by clicking the button on the toolbar. This willbring up the dialog shown in figure above.

To successfully create a new mapping object, the Name, Type 1, and Type 2fields must be set. By default, Type 1 is set as the current source type when themapping editor is invoked for the first time. As discussed in the followingsection, this can be changed from within the mapping editor.



To use the mapping editor

Invocation of a mapping object will bring up the mapping editor as shown infigure below. The editor has two modes, visual mapping and scripting. Bydefault, the editor shows the visual mapping interface.

The fields contained within the source and target types are shown in the mappingeditor with a tree structure. Each node in this tree is either a simple or acomposite type. In addition, the editor shows operations on the source type. Onlyoperations with in-parameters and a non-void return type are allowed. Further,only the public members of a type are shown in the tree. The editor is dividedinto three windows, the source tree, the target tree, and the expression window.The size of the expression window can be adjusted by dragging the splitterbetween it and the target tree window. As discussed in the section�Description�(at the beginning of this chapter), you can make a mapping from asource field to a target field in three different ways. The source field can bedropped onto the desired target field. Automatic mapping also be applied, andfinally, the target expression can be edited. These different methods areillustrated in the following screenshots.



The functionality of the mapping editor is available from the toolbar and anObject menu. The layout is shown in the following figure.

Save Automap Clear

Swap Properties

Figure 14 Toolbar and menu for mapping object

Figure 15 Automatic mapping of fields with the same name and type.



Figure 16 An example of a complete mapping from ERPCustomer to BFOCustomer.

To map the remaining fields, you can use the drag and drop mechanism, or editthe target expression. The mapping editor only enables you to drop source fieldsinto target fields with a compatible type. This also applies to operations, in otherwords, the return type of operations must match the target field type. An exampleof the resulting mapping is shown in Figure 16. After a mapping is defined, toremove the mapping, you can clear the target expression. To clear the mappingsfor the active direction, click the Clear button on the toolbar.



The types defined for a mapping object always act as either a source or a target.If you click the Swap button, the two types are swapped with respect to thesource and target roles. The following figure (see Figure 17) shows the result ofswapping the types in the ERPtoBFOCustomerMapper, and specifying themapping from BFOCustomer to ERPCustomer.

Figure 17 An example of a BFOCustomer to ERPCustomer mapping.

In addition to the visual mapping, the mapping editor enables you to edit scriptsthat are carried out during the mapping process. If you select the Script tab, thescript editor starts, and displays the script associated with the current mappingdirection. This enables you to define one script for each mapping direction, forexample, from ERPCustomer to BFOCustomer, and vice versa. By default, thescript editor for native scripts starts (see Figure 18). To enable the IActiveScriptsupport, you must click the Enable IActiveScripting button (see Figure 19). Asshown in Figure 8, the IActiveScript requires you to select a script engine to use,for example, VBScript or JScript. You can also connect a mapping script to anexternal file. For both the native and IActiveScripting, the target and sourcefields are referred to with the Target and Source keyword respectively. You can,however, omit the Target keyword and directly refer to the target fields.



Figure 18 Native mapping script.

Figure 19 IActiveScripting.



The mapping scripts are intended for specifying mappings that are not easilyspecified with the visual editor. The visual usually carries out the two mappingsshown in the script in Figure 17.

To display the properties of the mapping object, click Properties on the Objectsmenu, or click the Properties button on the toolbar. The Properties dialog boxis shown in Figure 20. Only the description associated with the mapping objectcan be changed.

Figure 20 Mapper properties.

To define a mapping for a table or array

Table and array mappings are performed differently from row type or simplefield mappings. The main difference is that each target table or array mustexplicitly be connected to a source table or array, which you can do by droppingthe source table onto the target table. The result is a connection from the sourcetable or array to the target table or array. In addition, fields that have the samename and type are automatically mapped. A target table or array that is notconnected to a source table or array cannot be expanded in the editor tree.



Several restrictions apply on the functionality of the table and array mappings.First, a restriction exists on how you can nest tables and arrays in other types. Atable or array type can only have one complex type as a parent. For example, youcannot map fields from the table OrdersLines if the table is contained in the rowtype Orders, which is contained with the row type ERPCustomer. This rule isenforced in the mapping object by only showing table and arrays types that haveonly one parent. Another restriction is that you cannot map fields from multiplesource tables to a single target table. This also implies that you cannot map anontable field to a table field.

TransformerThe functionality of the transformer is described in this section. A shortdescription of its main responsibilities is given in following section.

Description

The transformer is responsible for transforming an instance of the specifiedsource type into an instance of the specified target type. This transformation isperformed according to the mapping expressions associated with the mappingobject. The transformer carries out the set of mapping expressions, and assignsthe result of each expression to the appropriate field in the target instance. Inaddition, the transformer carries out scripts that are associated with the mappingobject.

During design time, the transformer attempt to optimize each transformation.This involves transforming the mapping information, specified with the mappingeditor, into an instruction set that is used during invocation of the map operation.The basic mapping instructions are:

� A direct mapping instruction.� An expression mapping instruction.

A direct mapping instruction does not require invocation of the expressionparser. Instead, a direct mapping instruction specifies how a source value can bedirectly fetched, which is more efficient than evaluating an expression. Incontrast, the expression parser must evaluate each expression mappinginstruction. In addition to these instructions, instructions also exist for handlingtable and array types.

Complex mapping instructions are based on the direct and expressioninstructions. Currently, two types of complex mapping instructions, table andarray instructions exist.



The script associated with each mapping direction is carried out when all themapping instructions have been performed. This implies that any overlappingbetween the script and mapping instructions will overwrite the work carried outby the mapping instructions.

The functionality of the transformer is made available from the scriptinglanguage with the map function. For more information, refer to the section�Scripting language.�

Scripting language

Description

The transformer functionality of the mapping object is available through thescripting language. A mapping object has a map operation. The return value ofthis operation is an instance of the specified target type that is transformed withthe mapping expressions and script associated with the mapping object. Thesource and target types are instances of the data types defined in the mappingobject. The following example illustrates how you can access the map functionfrom the scripting language.

Example 1ERPCustomer ERPCust;

BFOCustomer BFOCust;

BFOCust = ERPBFOMapper . map (ERPCust);

ERPCust = ERPBFOMapper . map (BFOCust);

MenuPurpose

You can define menus to customize the user interface of the Broker. One menuobject can define one or more drop-down menus on the menu bar. You canspecify which menus are presented to a user by means of an environment objectlinked to the user.

Menus can link directly to operations and processes in the Broker applications. Inaddition, commands can be created to call other programs to which the user hasaccess, such as word processing and spreadsheet programs.

Menus can inherit commands from other menus. In this case, the Broker systemsets up the parent menu first and then adds each new menu and menu item to theright of the parent menu.



Creation

To create a menu, take the following steps:

1 Open the repository browser folder where you want to store the menu object.

2 Click the New Menu toolbar button.

A dialog box appears in which you can specify the menu's properties.

If you select the Select Action option button, you can click Action to start theAction wizard. For more information, see the Action wizard section in Chapter 9,�Tools and assistants.�

Use

To make a menu available to users you must:

1 Define the menu object.

2 Define an environment object, and specify the menu object as a property ofthe environment.

3 Edit the user object and specify the relevant environment.

Properties

The following table lists the properties of menus.

Menu propertiesProperty DescriptionName The name of the menu.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Menu structure The structure of top-level menus, submenus, menu

separators, and commands.You can edit the menu structure in the form of a list ofmenu items. A menu item is a command on the menu, or aseparator or a top-level menu or submenu. The next tablelists the properties of menu items.

Inherit from A menu object from which your menu inherits its structureand attributes. The menu items you define are placed indrop-down menus next to the inherited menus.



For each of the menu items, the following properties are specified.

Menu item propertiesProperty DescriptionName The name of your menu or component, as it appears if the

menu is displayed.An ampersand (&) before a letter specifies the access keyfor keyboard input (Alt + letter). You can enter the name inmultiple languages. For more information, see Chapter 15,�Language support.�

Description The language-dependent description of your menu orcomponent. This will appear in the status bar when themouse pointer is over the item.

Item type The type of the menu item.Separator specifies that this menu item will be a menuseparator: a rule between menu items.Action specifies that this menu item will perform an action.Menu specifies that the menu item is a drop-down menu ora submenu.

Condition The expression that determines whether the menu item isavailable.If this expression evaluates to a number other than zero(true), the menu item can be used.If the expression evaluates to zero (false), the menu itemis not available to the user.An example of a condition is: System.isSuperUser

On false condition,show item (optionbuttons)

Determines what happens if a menu item is unavailablebecause of the condition.Disabled specifies that, if the condition is not fulfilled, thecorresponding menu item appears dimmed.Hidden specifies that, if the condition is not fulfilled, thecorresponding menu item will be hidden.

Script or action You can specify a script that is executed if the user clicksthe command.You can also use the Action wizard to specify an action.Example actions are: send an e-mail or an Brokermessage, display a form, or run a script.For more information, see the Action wizard section inChapter 9, �Tools and assistants.�



Default menus

The following menus are predefined:

Default menusPurpose MenuGeneral menu of the Brokerclient

\sys\system\defaults\StartupMenu

Repository browser \sys\system\abrowse\AbrowseMenu

Message handlerPurpose

Message handlers pick up messages of a particular type from a queue in theobject repository and perform an operation on them, such as starting a workflow.

Message handler objects are associated with a particular message queue and alogical data type. If polled, these objects read messages from the queue, andselect only messages that have the correct type. If you specified the type Void,the handler will act upon all messages, regardless of type.

The message handler can act upon the selected messages in a variety of ways asdefined in the message handler object. The argument sent into the message actionalways has the type of the message handler. The value contained in the messageis available in the action in the This variable.

If a message handler has a Void type, the message action cannot peek inside themessage or use the contents in its actions.

After being handled, messages are deleted from the incoming queue.

Creation

To create a message handler, take the following steps:

1 Open the repository browser folder where you want to store the messagehandler object.

2 Click the New Message Handler toolbar button.

A wizard starts that leads you through the steps necessary to create a messagehandler object.



Use

A message handler checks for incoming messages if the message handler�s polloperation is invoked. Usually, a periodic process is used to call the polloperations of message handlers.

Example action script

The message handler can run the following script for notifications that some datamust be synchronized over multiple applications. The component identifier isstored in the first six characters of the string. The local code is stored in the nexteight characters.

{

String str = this;

String strComponent = str [0:6];

String strLocalCode = str [7:8];

\types\ItemRow.synchronize(strComponent,strLocalCode,0);

}



Properties

The following table lists the properties of message handlers:

Message handler propertiesProperty DescriptionName The name of the message handler.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Queue to scan formessages

The message queue object from which the messages arepicked up.

Base type ofmessages tohandle

The logical data type of the messages that you want themessage handler to act upon.If you enter the Void type in this field, the handler will actupon all messages, regardless of type.

Ordering of queuescan

First in, first out (FIFO) specifies that the oldest messagesare processed first.Last in, first out (LIFO) specifies that the youngestmessages are processed first.

Action to perform The action that is performed for each message that thehandler picks up. The action can be defined with the actionwizard. Example actions are: send an e-mail or a Brokermessage, or run a script.For more information, see the �Action wizard� section inChapter 9, �Tools and assistants.�

Operations

The following table lists the operations of the message handler object.

Message handler operationsOperation Descriptionpoll Tells the message handler to look for messages in the

associated queue. If the message handler picks up amessage, the message is removed from the queue. To behandled, a message must have the correct type accordingto the definition of the message handler.You can specify the maximum number of messages thatthe poll operation will fetch.

For details about this operation, refer to �MessageHandler� in the ScriptingLanguage Reference (U7278D US).



Message queuePurpose

Message queue objects enable the Broker to buffer incoming messages until amessage handler is free to deal with the messages. Queued messages are stored ina folder in the object repository. A queue can contain messages of multiple types.Message handlers can pick up messages of particular types from message queuesand act on them in various ways.

Incoming messages are added to the queue by a message source object. You canalso add messages by means of the message queue's put operation.

Message handlers can pick up messages of particular types from message queuesand act on them in a variety of ways.

Creation

To create a message queue, take the following steps:

1 Open the repository browser folder where you want to store the messagequeue object.

2 Click the New Message Queue toolbar button.

A dialog box appears in which you can specify the message queue's properties.

Properties

The following table lists the properties of message queues:

Message queue propertiesProperty DescriptionName The name of the message queue.Description Language-dependent description. For more information, see

Chapter 15, �Language support.�Folder The object repository path of the folder where messages in this

queue will be stored.



Operations

The following table lists the operations of the message queue object.

Message queue operationsOperation Descriptionput Create a new message object in the message queue�s folder,

containing the indicated value. A message object created in thisway contains no recipient or description.

count Returns the number of messages in the queue.

For details about these operations, refer to �MessageQueue� in the ScriptingLanguage Reference (U7278D US).

Message sourcePurpose

Message source objects define how to retrieve and handle incoming messages.

A message source receives messages through one of the following transportlayers:

Available message transportsMessage transport DescriptionPOP3/MIME Internet e-mail Mail message fetched from an Internet mail

server using Post Office Protocol version 3. Themessage is assumed to be encoded using MIME.

Operating system file Files in a network folder.Microsoft Message Queue Message fetched from a Microsoft Message

Queue Server queue.AMI message Message fetched from an AMI-compliant queue,

for example, IBM MQ Series. AMI stands forApplication Messaging Interface.

User-defined transport usingCOM

Message fetched from a custom message source,which is assumed to implement Baan MessagingCOM interfaces.

The message source puts each incoming message through a message translator.The message translator parses the incoming message stream and creates ameaningfully typed Broker value. The value is packaged inside a message objectand stored in a message queue in the object repository.



A message sources uses one of the following types of message translator:

Available message translatorsMessage translator DescriptionText string Creates messages of type string. The message

contents is passed on as a string without furthertranslation.

User-defined translatorusing COM

Custom message translator, which implementsBaan Messaging COM interfaces.

Extensible MarkupLanguage (XML)

Electronic document in Extensible MarkupLanguage (XML) format.

BizTalk framework Electronic document encoded in a BizTalkFramework envelope.

Creation

To create a message source, take the following steps:

1 Open the repository browser folder where you want to store the messagesource object.

2 Click the New Message Source toolbar button..

A wizard starts that leads you through the steps necessary to create a messagesource object.

Use

A message source checks for incoming messages if the message source�s polloperation is invoked. Typically, a periodic process is used to call the polloperations of message sources.



Properties

This section describes the general properties of message sources and theproperties of specific message transports and message translators.

The following table lists the general properties of message sources:

General message source propertiesProperty DescriptionName The name of the message source.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Message queue The message queue object that points to the folder where

the messaging source writes the incoming messages.

The following tables list the properties that you can specify for various messagetransports.

POP3/MIME Internet e-mail propertiesProperty DescriptionIP address or DNSname of POP3server

The IP address or the DNS name of the POP3 server tobe polled for e-mail messages.

POP3 user account The user account name to be used if logging on to thePOP3 server.

POP3 password The password to be used if logging on to the POP3server.

Messages toprocess

Only previously unread messages specifies that theBroker reads only previously unread messages on thePOP3 server.All messages found on server specifies that the Brokerreads all messages on the POP3 server.

Delete message onserver afterprocessing (checkbox)

If this check box is selected, the Broker deletes themessages on the POP3 server after they have been read.

POP3/MIME E-MAIL



Operating system files

Operating system file propertiesProperty DescriptionFolder to scan for files The path and name of the folder that must be

watched for message files.In a server/client setting, you must select a localfolder on your server. You cannot select a networkfolder, because NT services cannot access networkfolders. In a server/client setting, you can browse forthe folder on the network, but you must make surethat the path only contains references to local driveson the server. Do not use UNC names in the path.

Action after processingeach file

Delete it specifies that the Broker deletes the filesafter processing.Move it to another folder specifies that the Brokermoves the message files to another folder after themessage files are processed.

Folder The path and name of the folder to which themessage files are moved after they have beenprocessed if you specified Move it to another folder.

MSMQ

Microsoft Message Queue propertiesProperty DescriptionMessage queue The path and name of the queue that must be

watched for message files.

AMI messages

AMI message propertiesProperty DescriptionPolicy name The name of the AMI policy you want to use.Service point The name of the AMI service point you want to use.

The contents of the Policy name and Service point fields depend on your localAMI setup. If you have not already done so, use the AMI setup utility to createand configure a policy name and a service point.



User-defined transport using COM

Properties for user-defined transport using COMProperty DescriptionCLSID or PROGID ofCOM class to use fortransport

The CLSID or PROGID identifier for the user-definedCOM class that acts as the message transport.CLSIDs must be enclosed within braces. Example:{F85C2EE0-B4FE-11D1-95B9-00805FA3AA240}

The custom transport facility enables a user-defined COM class to act as themessage transport. You must enter a COM CLSID or PROGID identifier. TheBroker passes this identifier to a CoCreateInstance call. The CoCreateInstanceoperation creates a fresh instance of the transport object.

The object is assumed to implement the Broker messaging transport interface,IBaanMsgTransport, which is defined in an interface definition file (IDL).

The following tables list the properties that you can specify for various messagetranslators.

Text string

You do not need to define properties for Text string translators.

User-defined translators using COM

Properties for user-defined translators using COMProperty DescriptionCLSID or PROGID ofCOM class to use fortranslation

The CLSID or PROGID identifier for the user-definedCOM class that acts as the message translator.CLSIDs must be enclosed within braces. Example:{F85C2EE0-B4FE-11D1-95B9-00805FA3AA240}

The custom translator facility enables a user-defined COM class to act as themessage translator. You must enter a COM CLSID or PROGID identifier. TheBroker passes this identifier to a CoCreateInstance call. The CoCreateInstanceoperation creates a fresh instance of the translator object.

The object is assumed to implement the Broker messaging translator interface,IBaanMsgTranslator, which is defined in an interface definition file (IDL).



XML documents

XML translator propertiesProperty DescriptionAssociated logical datatype

You must store a logical data type for the XMLtranslator in the \sys\xml repository folder.

You can use a combination of logical data types. For example, the fields of a rowtype can contain other row types or table types. You must store all of these typesin \sys\xml.

The names of the logical data types must be equal to the element names in theXML document. These names are case-sensitive.

The following example illustrates how an XML document can be matched with alogical data type. Suppose a message source picks up the following XMLdocument:

<?XML version="1.0"?>

<PRICELIST>

<APPROVEDBY DATE="Sept. 3">Ms. Jones</APPROVEDBY>

<ITEM>

<CODE>20932</CODE>

<DESCRIPTION>Towel</DESCRIPTION>

<PRICE>12.95</PRICE>

</ITEM>

<ITEM>

<CODE>20868</CODE>

<DESCRIPTION>Bar of soap</DESCRIPTION>

<PRICE>8.25</PRICE>

</ITEM>

</PRICELIST>



To process such an XML document, take the following steps:

1 Define a logical data type ITEM that corresponds with the ITEM elementtype.ITEM is a row type with the following fields:− CODE (Number).− DESCRIPTION (String).− PRICE (Number).

2 Define a table type based on the ITEM row type, for example ITEMTABLE.

3 Define a logical data type PRICELIST.PRICELIST is a row type with the following fields:− APPROVEDBY (String).− APPROVEDBY_DATE (String).− ITEM (table of type ITEMTABLE).

The APPROVEDBY_DATE string field stores the DATE attribute of theAPPROVEDBY element.

BizTalk framework

BizTalk translator propertiesProperty DescriptionAssociated logical datatype

You must store a logical data type for the BizTalktranslator in the \sys\biztalk repository folder. Thisworks in the same way as the XML translator.

The BizTalk translator works almost exactly like the XML translator. The onlydifference is that a BizTalk document is enclosed in a BizTalk wrapper(envelope). The Broker removes this wrapper before further processing.

Operations

The following table lists the operations of the message source object.

Message source operationsOperation DescriptionPoll Checks for incoming messages.

If any messages are found, the messages are received fromthe message transport, put through the message translatorand written to the message queue.

For details about this operation, refer to �MessageSource class� in the ScriptingLanguage Reference (U7278D US).



Object setPurpose

An object set is an object that contains a list of other objects. You can use objectsets to specify the collection of objects that must be exported to a file, which isespecially useful if you must often export the same collection of objects.

For more information, see Chapter 16, �Exporting and importing of objects.�

Relative path

If objects are marked as absolute, they are imported in the same path as theywere in originally. If objects are marked as relative, their import location isdetermined relative to a specified base location.

Creation

You can create object sets in the following two ways:

� Directly in the repository browser.� By using the Export Objects to File dialog box.

The Export Objects to File dialog box provides the easiest way to select theobjects to be included in the object set.

To create an object set directly in the object browser, take the following steps:

1 Open the repository browser folder where you want to store the object setobject.

2 Click the New Object Set toolbar button. A dialog box appears in which youcan define the properties of the object set.

3 Click New to add an object to the set. A new object appears in the list with adefault name.

4 Change the default name to the path and name of the object you want to add.You do not need to add the path if the object resides in the same folder as theobject set.

To create an object set using the Export Objects to File dialog box, take thefollowing steps:

1 On the File menu, click Repository Browser to open the repository browser.


3 In the Repository list, select the objects you wish to export.



4 Click Absolute or Relative to copy the selected objects into the Objects toexport list.

5 Click Write Set to create an object set, which stores information about theobjects that you have chosen to export.

6 Enter a name for the object set in the Set of Named Objects dialog box.

The object set is created in the root folder of the object repository.

If you also entered a path and name for the export file, you can now proceed toexport the objects in the object set.

Use

You can use object sets in the Export Objects to File dialog box, to fill theObjects to Export list, as follows:

1 On the File menu, click Repository Browser to open the repository browser.


3 Click Read Set to retrieve a previously created object set.

4 Select an object set.

5 Click OK to read the set. The objects referred to in the named object set aretransferred to the Objects to Export list, replacing any objects already in thelist.

The object set does not contain other objects, but instead contains information onwhere the objects are located. Therefore, you cannot create an object set, addobjects from the repository, and then delete the objects in the repository in anattempt to gain disk space.

Periodic processes

You can also use object sets in the Periodic Processes dialog box. In this dialogbox, you can use an object set to define the set of periodic processes that youwant to activate or deactivate. For more information, refer to �Periodicprocesses,� later in this chapter.

NOTE



Properties

The following table lists the properties of object sets.

Object set propertiesProperty DescriptionName The name of the object set.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�List of objects A list of the objects that are currently included in the object

set.

Periodic processPurpose

A periodic process is an automatic process or task that can start at a predefinedtime and run from that point in time at predefined intervals. Periodic processescan run any script written in the scripting language. The processes, for example,could be used to collect a history of certain financial indicators for a company orto update data at regular intervals.

For details on recurrence schemes, refer to Chapter 22, �Recurrence Schemes.�

Creation

To create a periodic process, take the following steps:

1 Open the repository browser folder where you want to store the periodicprocess object.

2 Click the New Periodic Process toolbar button.

A wizard starts that leads you through the steps necessary to create a periodicprocess.

You must use unique names for alerters and periodic processes. If the name of anperiodic process is identical to an existing periodic process or alerter, youoverwrite the existing process in the \sys\processes folder.

NOTE



To start and stop

If you select the Activate check box in the final step of the periodic processwizard, the periodic process starts immediately.

The Periodic processes dialog box provides a convenient way to start and stopperiodic processes. To open the Periodic processes dialog box, point to Settingson the Baan OpenWorld Broker menu and then click Active PeriodicProcesses.

This Baan OpenWorld Broker menu is contained in the Broker's default menu.This menu is not visible if the repository browser is open. The menu commandcalls the scripting language operation System.runPeriodicCtrl () .

A periodic process is active if a copy of the periodic process object is stored inthe \sys\processes folder of the object repository. The server regularly scans the\sys\processes folder. You can control the list of active processes directly bycopying periodic processes to this folder and by deleting periodic processes fromthis folder. Changes in the \sys\processes folder take effect the next time thefolder is scanned.

Action wizard

You can also start periodic processes by an object that uses the action wizard todefine an action to perform, for example, a message handler.

Configure

The server, not the client, runs all periodic processes. A periodic process cancontinue running on the server after you quit the client program. In the Brokerconfiguration utility you can specify the frequency by which the server scans the\sys\processes folder:





5 On the Basics tab, enter the interval between scans.

To prevent all periodic processes from being started, select the Disable PeriodicProcesses check box on the Basics tab in the server configuration utility.Running processes will not stop, but no processes will start anymore.

NOTE



Properties

The following table lists the properties of periodic processes.

Properties of periodic processesProperty DescriptionName The name of the periodic process. The name must differ

from the names of all other alerters and periodicprocesses.

Description Language-dependent description. For more information,see Chapter 15, �Language support.�

Script The script that will be executed at fixed intervals.Note that you cannot use the printf function to display amessage box, because the script is run on the server.

Interval The time interval that elapses between successive runs ofthe periodic process.

Start date and time The date and time when the periodic process is to run forthe first time.

Catch up (checkbox)

If you select this check box, the periodic process runsonce for every instance it has missed during the time theperiodic process was not running.

PicturePurpose

Picture objects store a graphics file into the object repository. Picture objects areused in forms in the following ways, as a:

� Background picture.� Picture anywhere on the form.� Button.

For more information, see the �Form� section, earlier in this chapter.

Creation

To create a picture, take the following steps:

1 Open the repository browser folder where you want to store the pictureobject.

2 Click the New Picture toolbar button.

A dialog box appears in which you can specify the picture's properties.



Properties

The following table lists the properties of picture objects.

Picture propertiesProperty DescriptionName The name of the picture.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Input file The path and file name of the picture that you want to

import into your picture object. You are limited to BMP,WMF, GIF, and TBM (Transparent Bitmap) files.

Transparent (checkbox)

If you select the Transparent check box, the backgroundof the image will be transparent. The color that is madetransparent is that of the pixel in the top left-hand corner ofthe image. All pixels of the same color are also madetransparent. This is only advisable for very simple images.

Point2PointThis section describes new features that will be added to the Baan OpenWorldBroker to support Baan SCS data synchronization scripts used to transfer databetween BaanERP and the SCS products Planner and Scheduler. BaanOpenWorld Broker 2.0 replaces the ITK 2.0.

Design Overview

Performance is a major factor for SCS-ERP integration because of the highvolume of data that must be moved between BaanERP and the SCS productbefore and after planning/scheduling.

Baan OpenWorld Broker uses a common data model that is a key component inthe hub-and-spoke design of Broker. Incoming data is mapped to an instance ofthe corresponding BESOM type, for example, sales order, inventory item, and soon, before being mapped again and transferred to the destination. This is possiblya performance bottleneck in high volume point-to-point data transfers.

To be better prepared to handle these situations, as well as to respond to therising demand for a data migration and replication utility/product inside Baan,the Iceland team will add an option to Broker to bypass the central data model.

This point-to-point integration scheme will be added as a new object type.



Design Approach

The current implementation contains the following steps:

1 Periodic Processn.

2 Iterator Objectn.

3 Init Script obtains data from the source component.

4 Iterate Script.

5 Fetches each source object, mapping it to a BESOM object, and calls theBESOM object�s Store/StoreNew for each participating target component.

6 Finish Script.

Periodic Process objects run their associated job at a predefined interval,invoking an Iterator object. This Iterator object loads data from the sourcecomponent in the Init script. In the Iterate script, it performs mapping from thesource object to a BESOM object, and then calls either Store or StoreNew for theparticipating target components. All mapping is performed in scripts.

Because of the pressure from SCS to reuse the VBScripts as much as possible, itwas deceded to skip the central datamodel totally and create a new object type,which basically is just a data-pump that feeds the VBScript mapping scripts withthe correct objects.

Because of time restrictions, this point-to-point object must be developed inphases. In the first phase, the following limitations apply:

� The new mapping object will not be used.

� This object can only be used for BaanSCS mapping scripts.

� In future releases, this point-to-point object must be an integrated part of theIterator object, and users must be able to enable the point-to-point datatransfer. The mapping object must be used and the mapping object must beable to work directly on source and destination data.

To reuse the existing VBScripts in Baan OpenWorld Broker, you must use theITK Adapters to connect to BaanERP and the BaanSCS products. ITK Adaptersare generic and have a well-defined COM interface. In the C++ source code, thisCOM interface is used to communicate with the scripts.

Another option is to use the C library also provided by BaanSCS, but thisrequires additional internal knowledge about the library, the included header filesand the third party libraries used to implement the ITK library.



Point-to-point object

Description

This point-to-point object only works with Components that have access to ITKAdapters, such as B3, Planner, or OleDB. This object is usually used as a Task ina Profile. For a detailed description of the new object types that are added in theITK Merge, refer to the ITK Merge New Objects.doc document

User Interface

The editor for the point-to-point object is a wizard-like utility. On the first page,you must to enter a name and a description.

On the next page, the user must enter a mapping script. The mapping scriptsmust have the same user that is the current ITK user exists. Scripts can be storedwith the object or read in from a external file. If the scripts are stored in externalfile, the file will be updated if changes have been made to the script in the point-to-point editor.



If both the source and the destination component has multiple sites configured(component instances) the following page provides the user option to createcomponent couples. Otherwise, this page is not shown.



On the next screen, users are asked to select those global scripts that are used bythe mapping script. Global scripts are always an instance of the new Scriptobject.

On the next page, users are asked to enter a mapping script. These mappingscripts must have the same user exists as the current ITK user exists. Scripts canbe stored with the object or read in from an external file. If the scripts are storedin an external file, the file is updated if changes are made to the script in thepoint-to-point editor.



Users can double-click in the edit field and open a bigger source editor that canbe resized and moved around the screen.

The final page shows run-time options that the user can enter.

This screen has the same run-time options as used by ITK 2.0. The unavailableoptions are options that are not implemented in ITK 2.0.



The transfer type contains a resync option, which means that the destinationdatabase is deleted before performing a data transfer, or net change, which meansthat only changed/updated source objects are transferred to the destination.

Match mode can be No Match, which means that the destination database is notlooked up for a corresponding destination object, or Manual Match, whichmeans that the mapping script is used to find a corresponding destination object.

Delete mode contains a No Delete option, which means that the destinationobjects are not deleted, and a Delete All option, which means that all the objectsin the destination are deleted. The Delete Unreferenced option is notimplemented in the first version of this object, due to a limitation in the COMlibrary provided by BaanSCS. When SCS releases Corelli SP4, this object willbe updated and the Delete Unreferenced option will be implemented.

The batch size determines how many objects are read at a time from the sourceor the destination.

The user can provide destination filters, however, these are usually a part of themapping script.

QueryPurpose

A query object displays data of a certain type in a form designed for the purpose.The data is generally table rows, but can also be simpler, for example, numbers,or text. The form of a query can also contain pictures, buttons, and so on.

Creation

To create a query, take the following steps:

1 Open the repository browser folder where you want to store the query object.

2 Click the New Query toolbar button.

A dialog box appears, in which you can specify the query's properties.



Use

A query can appear as a window by invoking the window�s run operation.

A query can also appear in the background of an Broker application for aparticular user or particular users. Simply drag a query object from the repositorybrowser and drop the object onto the background. You can have multiplebackground queries between which you can switch clicking on the appropriatetab.

Environment

You can specify background queries in an environment object. These queriesappear automatically if a user that is linked to that environment logs on.

The query can be removed with the scripting language commandsEnvironment.removeQuery or Environment.removeAllQueries. Formore information, refer to �Environment� in the Scripting Language Reference(U7278D US).

Properties

The following table lists the properties of query objects:

Query propertiesProperty DescriptionName The name of the query.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Expression The expression that your query will evaluate if the query

runs.The expression is usually very simple, and usually consistsmostly of the full path of a Table variable that links to thedatabase table that must be queried.

Form The form to display the result of the expression.Refresh interval The interval between successive evaluations of the query.Center on screen If you select this check box, the query results appear in a

centered window on the screen.Show as dialog box If you select this check box, the query results appear in a

modal dialog box.



Operations

The following table lists the operations of the Query object.

Query operationsOperation DescriptionQueryValue Returns the query�s value, obtained by evaluating the

query�s expression.run Calculates the query�s value and brings up a form window

that shows the value. While the query is being shown onthe screen, the value is automatically recalculated andupdated at the rate specified in the Refresh intervalproperty of the query object.

send, sendTo Sends the query to a user as a message. The resultingmessage is placed in the \sys\mailboxes\USERNAMEfolder in the repository. For more information, see Chapter8, �Messages.�

The Environment object offers you the following operations to managebackground queries, such as addQuery, selectQuery, removeQuery, andremoveAllQueries. For details about these operations, refer to the ScriptingLanguage Reference (U7278D US).

ResourcePurpose

Resource objects represent central resources of which a limited amount isavailable. Resources can be, for example, rooms, machines, people, or otherfacilities. The workflow system uses resource objects to check if sufficientresources are available to perform a certain step. You can use this as follows:

� A workflow step that requires resources must be preceded by a resource stepthat allocates resources to the workflow instance. If the available quantity of aresource is insufficient, the resource step waits.

� A second resource step follows after the workflow step that uses the resource.This resource step releases the used resources.

A single resource object manages multiple resources. For example, a trainingresource can be used to manage the availability of training rooms and overheadprojectors. The resource object has a counter for each type of resource to recordthe available number of units.



Creation

To create a resource, take the following steps:

1 Open the repository browser folder where you want to store the resourceobject.

2 Click the New Resource toolbar button.

A dialog box appears in which you can specify the resource's properties.

Properties

The following table lists the properties of resources:

Resource propertiesProperty DescriptionName The name of the resource.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Number ofresource counters

The number of resource types that this resource objectcan allocate or release. The first counter in the list isalways Counter 0.

Value of eachcounter

The number of units of a type of resource that areavailable for allocation.

Operations

The following table lists the operations of the resource object:

Resource operationsOperation Descriptionallocate Attempts to allocate a specified amount of resource units

from one of the resource counters. If the requestedamount of the resource is not available, the resourcecounter is not modified.

queryCount Returns the available amount of a resource.release Releases a specified amount of resource units.

For details about these operations, refer to �Resource� in the Scripting LanguageReference (U7278D US).



Text tablePurpose

Text table objects are used to store the texts that you display on forms, inmessages, and so on. Text tables enable you to store a text in multiple languagesand locales. The system automatically extracts the correct string for the currentuser�s locale and language at run-time.

In most places where a string is required by the system, you can use a text-tablereference instead.

Creation

You can enter the texts in a text table in many languages and locales. To create atext table, take the following steps:

1 Open the repository browser folder where you want to store the text tableobject.

2 Click the New Language-Independent Text Table toolbar button.

A dialog box appears, in which you can specify the text table 's properties andenter the texts.

For more information, refer to Chapter 15, �Language support.�

Properties

The following table lists the properties of text tables:

Text table propertiesProperty DescriptionName The name of the text table.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�List of text records A collection of multilanguage texts, identified by a number.

In the text table, you can enter a series of texts in multiple languages. Each text isidentified by a numerical ID.



The following table lists the properties of the individual texts.

Text propertiesProperty DescriptionID The numerical identifier of the currently selected text-table

record.Description An optional short description of the currently selected text-

table record. You can use this property to describe wherethis text will be used for.

Value The text that appears if you refer to this text on a form, in amessage, or in another user-interface element.The text can have multiple lines. You can use multilinetexts in messages, but not in expression fields in forms.You can enter equivalent text in multiple languages.

The text-table dialog box displays the value of the texts in your current language,as well as in the Default language.

Operations

The Get operation returns a string from a text table object based on the numericalID parameter, as illustrated in the following example:

You define the \txt\MyTextTable text table object. This text table has a messagetext with identification number 50. You can now use the following expression ina script to display the text in a message box:

printf (\txt\MyTextTable . get (50) );

In the form editor, you can enter the following expression in an expression field:

\txt\MyTextTable.get(50)

For details about the get operation, refer to �TextTable class� in the ScriptingLanguage Reference (U7278D US).

EXAMPLE



Timed variablePurpose

Timed variables store an expression that is calculated and whose value isreturned if an expression or script refers to the variable name. You can define atime period that determines how long variables retain their last value. If avariable is queried regarding its value before the end of the period, the variablereturns the last value. Otherwise, the value is recalculated, and the time period isreset.

Timed variables are particularly useful to store data that:

� Is expensive to calculate, either because of time-consuming calculations orbecause of extensive database operations to retrieve the data.

� Changes relatively slowly.

For example, if you want to perform analyses on the total sales volume in thecurrent year, you can store the total sales volume in a timed variable that has alifetime of 12 hours.

Alerters can also use timed variable.

In between recalculations, the value of the variable is stored in the central objectrepository and is available to all clients.

Creation

To create a timed variable, take the following steps:

1 Open the repository browser folder where you want to store the timedvariable object.

2 Click the New Timed Variable toolbar button.

A wizard starts that leads you through the steps necessary to create a timedvariable object.



Properties

The following table lists the properties of timed variables:

Timed variable propertiesProperty DescriptionName The name of the timed variable.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Last evaluated The date and time when the timed variable was last

evaluated.Lifetime The period for which an evaluation of the timed variable

remains valid.If the variable is asked for its value, the variable will returnthe result of the last evaluation if the evaluation is stillwithin the variable�s lifetime. If the lifetime has expired, thevariable is recalculated. The lifetime is expressed in theunits of the Time unit field.

Expression The expression that is evaluated to determine the value ofthe timed variable. This expression is evaluated on theserver.

Operations

The following table lists the operations of the timed variable object:

Timed variable operationsOperation Descriptionevaluate Returns the value of the timed variable. If the lifetime has

been exceeded, the timed variable is recalculated first.Otherwise, the last calculated value is used.

invalidate Invalidates the remaining lifetime of the timed variable,thus making sure that when the variable is next evaluated,its value will be recalculated.

lastEvaluated Returns the time when the timed variable was lastrecalculated.




UserPurpose

A user object must exist in the object repository for each person who logs on tothe Broker. You can link users to an environment to define the menus,background queries, and so on, that are presented to these users if they log on.

Users are able to receive messages in their mailbox. A message has an associatedform object that is used to display the value of the message.

Creation

1 Open the repository browser folder where you want to store the user object.The \users folder is recommended. In situations where you can choose usersto perform some action on, the system usually displays a list of users and usergroups in the \users folder to choose from. To log on to the Broker, the userobject must be stored in the \users folder of the repository browser.

2 Click the New User toolbar button.

A dialog box appears in which you can specify the user's properties.

The user's mailbox folder is automatically created if the user receives messages.The mailbox folder is \sys\mailboxes\USERNAME, where USERNAME is theidentifier of the user, the name of the user object.

You cannot create a user with a superuser status or who has access to the versioncontrol system unless you also have the superuser status.

Use

If you want your Broker user identifier to be the same as your logon name inWindows NT, you must select the Enable Trusted Logon check box in theclient configuration utility. As a result, you do not need to enter a user name andpassword when you log on. To log on as a different user, you must clear theEnable Trusted Logon check box in the client configuration utility, which youcan do using the following steps:



3 Right-click the Client icon.


NOTE



5 On the Basics tab, clear the Enable Trusted Logon check box.

After you start the Broker client, a logon window appears in which you can entera user name and password.

Properties

The following table lists the properties of the user.

User propertiesProperty DescriptionIdentifier The name or identification code used to log on to the

Broker. This field is case-sensitive.Name The full name of the user.Superuser (checkbox)

If this check box is selected, the user has the superuserstatus. Superusers can change security permissions, openthe object repository browser window, and modify objects.

VCS (check box) If this check box is selected, the user has access to theVersion Control System. This implies that this user isallowed to edit version-controlled objects. For moreinformation, see Chapter 15, �Version control system.�

Password The user's password used to log on to the Broker. Thepassword must be the same as the password to log on toWindows NT. The password is case-sensitive.

Path The object repository paths of the system elements towhich this user has access, such as menus and pictureobjects. Separate each path statement with a semicolon;for example:sys\system\fed; sys\system\default;Usually, you can leave this field blank.

Email address The user's e-mail address.Environment The environment in which the user operates.Language The user's language area or locale. If locale strings or text

tables have been used, the user will see the text in thelanguage specified here. If you set the language toDefault, the language of the environment is used.

Use encryption(Local)

If you select this check box, local transactions areencrypted.

Use encryption(Remote)

If you select this check box, remote transactions areencrypted.

Script to executeafter logon

The script that is run immediately after the user logs on.



Operations

The following table lists the operations of the User object.

User operationsOperation DescriptionqueryEMailAddress Returns the user�s electronic mail address.sendMessage Usesa form object to send a message to the user's

mailbox.queryIsSuperUser Returns a number that indicates whether the user has

superuser status or not.


User groupPurpose

User groups are used to group users with common characteristics, which enableflexible management of users and a logical approach to setting up user divisionsin a company. A user group can contain both users and other user groups. In thisway, you can set up a hierarchical structure of user groups.

User groups are mainly used to send messages to groups of users. This feature isparticularly useful in workflow applications.

Creation

To create a user group, take the following steps:

1 Open the repository browser folder where you want to store the user groupobject. The \users folder is recommended. In situations where you can chooseusers to perform some action on, the system usually displays a list of usersand user groups in the \users folder to choose from.

2 Click the New User Group toolbar button.

A dialog box appears, in which you can specify the user group�s properties.

A user group can be part of another user group. In this way, you can create ahierarchy of user groups. However, you cannot create a cyclic hierarchy. That is,for example, you cannot make user group C a member of user group A, and thenmake user group A a member of user group C.

NOTE



Properties

The following table lists the properties of user groups:

User group propertiesProperty DescriptionName The name of the user group.Description Language-dependent description. For more information,

see Chapter 15, �Language support.�Members A list of all the users and user groups who are members of

this group.

Operations

The following table lists the operations of the user group object.

User group operationsOperation DescriptionQueryUserList Returns a table that contains all the users that are

members of the user group, including all the members ofall its subgroups.

For details about this operation, refer to the Scripting Language Reference(U7278D US).

WorkflowPurpose

Workflow objects are blueprints or templates for document routing. Theseonjects specify the data to be routed, the steps involved, decisions to be madebetween steps as to which step must be taken next, and the handlers to respond tovarious events. Instances of specific workflows are called workflow documentsor simply documents.

The workflow system is not covered by the current version of this guide. Formore information about workflow, refer to the online Help.


Design overviewBOW Iterators are designed for bulk synchronization of data between a singleoriginating component and 1.n destination components. No tight coupling existsbetween the originating component and the destination components. Destinationcomponents can be added, removed, or their data mapping modified withoutaffecting the originating component or the iterator object.

An iterator has the following three main phases:

� Initialization phase.� Iteration phase.� Finish phase.

An iterator can, for example, connect to an external data source and get a table ofnew records in the initialization phase, use the iteration phase to iterate (loop)over the rows in the table, store them into the destination components and, duringthe finish phase, close any connections to external data sources.

Iterator objects have a close relationship with component objects, and require anoriginating component to be specified as well as a result type (giving the formatof the result of each iteration and supplying the storage semantics).

Design ApproachThe main purpose of iterators is to speed bulk synchronization of data. BOInetlist operations, for example, return a table of all modified rows. With therecord-at-a-time component, primitives in row types require BOW to effectivelyload the data twice from the server, once in the BOI netlist call, and again in theload primitive that is implicitly performed as part of the Type::synchronizeoperation.

If you use iterators, the second load can effectively be done away with, as theinitialization phase performs the �netlist� operation, and stores the BOI COMinterface to the result.

21 Iterators

Iterators


The iterator phase iterates over the table, with operations on the COM interface,which was returned from the netlist operation, and loads the data that is required.BOW automatically calls the store or storeNew primitives, depending on whetherthe code for the component/subsystem pair is found in the code mapping table.Iteration continues while the iterator script returns a nonnull value. In otherwords, the first half of the synchronization operation, the load phase, isperformed in the iterator script, but the second half, the store phase, is performedwith the usual store logic of Type::synchronize.

Design entitiesDescription

To create a new iterator object, point to New on the Object menu, and clickIterator, or click the button on the toolbar.

To verify or test an iteratorIf the iterator parameter is of type Void, then this parameter can be omitted.

The operation returns a table where each row is of the iterator result type.

Example: \MyIterator.run(�Testing�).view.

This example runs the iterator and displays a table of the iteration phase resultrows. No data storage is performed.

To run an iteratorAn iterator can be run by calling the �synchronize� operation on the iterator. Theoperation has two optional parameters, the iterator parameter and a flagparameter. The flag parameter can be a combination of SYNC_STORE_ALLand SYNC_ALWAYS_NEW, both of which are defined in \predef\system.

\MyIterator.synchronize (�Testing,� SYNC_STORE_ALL +SYNC_ALWAYS_NEW). These check boxes are explained here.

SYNC_STORE_ALL: BOW stores each result object in all participatingcomponents, including the originating component. If you do not select this checkbox, the originating component is left out, because the component is assumed tohave an up-to-date version of the object. If you select the flag, BOW ends thestore cycle by calling the Store primitive in the originating component.PrepareStore and RollbackStore are called, as applicable, in the same way as forother components.

EXAMPLE

Iterators


SYNC_ALWAYS_NEW: BOW assumes that the object in the originatingcomponent is always a new, fresh object. This speeds up synchronization bysaving a lookup in the code map table to check whether the object already exists.Only select this check box if you know that the object is in fact not alreadypresent in the system.

Iterator properties

Attributes tab

On this tab, the attributes of the iterator are specified. The following fieldsrequire further explanation:

� Type of iterator parameter.This is an optional parameter that the user can leave to the Run orSynchronize operation of the iterator. This can be any BOW type, bothprimitive and user-defined. The parameter is available in the initializationscript in a variable called Parameter.

Iterators


� Type of iterator state.The state of the iterator. The state is carried between the initialization, theiteration, and the final phases. The Initialization phase can, for example,populate a table that is a member of the iterator state type, which is thenaccessible in the Iteration phase and the Final phase. In all phases, an instanceof this type is accessible through a variable called This.

� Type of iterator result.This is the type of the result of each iteration. In other words, this is the typewhose store and storeNew primitives are called for each result record. Theiteration script can set members of this type in the Result list. As long as theiteration script returns a non-zero value, the store or storeNew primitives ofthe result type are applied to the result value.

� Originating component.This identifies the component that will be used when you check whetherresult records are already known to BOW, which causes a Store cycle, or not,which causes a StoreNew cycle.

� Reconstruct result value for each iteration.If you select this checkbox, BOW will, at the start of each iteration, reset eachmember of the result type to the member�s default value and call the constructprimitives for each participating component. If you do not select this checkbox, the iteration script is responsible for setting or clearing members of theresult type, and the members are not modified by BOW between iterations.

� Assume all rows are new.If you select this checkbox, BOW assumes that all result rows are new. As aresult, BOW always calls the StoreNew primitive, and does not bother tocheck the code mapping table for existence of a code for givencomponent/subsystem pair.

Iterators


Initialization tab

This tab has a script entry field, in which all initialization is performed. Thisexample sets an OleObject in the iterator state type (IteratorState). This is a COMobject that knows about new customers in the originating component.

Iterators


Iteration tab

The iteration script iterates over the new customers through the Next operationon the COM object, which in this example is assumed to return a boolean value.If there are any new customers, the Next operation must return TRUE, in whichcase a 1 is returned in the iteration phase script. If there are no more newcustomers, a 0 is returned to indicate to BOW that the iterator is complete.

Iterators


Finish tab

This tab has a script entry field, in which all work to finish the iteration isperformed. This example calls the endEnumeration operation on the OleObject inthe iterator state type (IteratorState).

Iterators


Logging tab

This tab enables the user to specify what kind of logging must be performed forerrors (and success).


This section describes the technical design of the recurrence schemes available inperiodic processes and alerts in Baan OpenWorld Broker (BOW). The recurrenceschemes are only available for periodic processes and alerts, and enable the userto specify advanced recurrence options for these types of objects in the objectrepository.

Previous versions of BOW had only one type of recurrence, which was a fixedinterval. Therefore, a process (periodic process or alert) ran at predefinedintervals only. A process with an interval of 10 minutes ran once every 10minutes.

The new scheme enables for a much more detailed specification of the times aprocess must run. For example, soft dates, for example, the third Tuesday of amonth, can be specified. See the following sections for a detailed overview.

The design of the recurrence schemes enables for maximum flexibility whilekeeping the user interface simple. The design is based on the recurrencefunctionality in Microsoft Outlook that is familiar to many users.

Interval recurrence schemeDescription

This scheme is similar to what was available in previous versions of BOW. Afixed interval is specified, and the process runs every time that interval expires.Additionally, the process is also allowed to run on weekedays.

Attributes

The following are the attributes for this scheme:

� Interval.

� Units seconds, minutes, hours, days and weeks.

� Weekdays that the attributes must be run on.

22 Recurrence schemes

Recurrence schemes


Behavior

In the following example, a process is defined to have an interval of 10 minutes.

The process starts at 10:15 and runs for 7 minutes, and finishes at 10:22. Theprocess is started again at 10:25.

The process overruns its interval, that is, the process starts at 10:15, but runs for12 minutes. The process is then started again at 10:35. The 10:25 run is thereforeomitted, because the process was already running at that time.

The interface enables you to specify on which weekdays the process must run.

User Interface

The following figure (see Figure 21) shows a user interface to create an intervalrecurrence:

Figure 21. To create an interval recurrence.

Monthly recurrence scheme

Description

The monthly recurrence scheme enables you to have a process run on a specifieddate every month, for example, the 15th of every month, and enables you to alsoset soft dates.

Soft dates are dates such as the first, second, third, fourth, or last Monday of amonth.

Recurrence schemes


Attributes

The monthly recurrence scheme has two possible attribute categories:

� Run on a given day every month.The day number and the month interval are specified. For example, you canset a process to run on the 15th of every other month.

� Run on the <first, second, third, fourth, last> <day, weekday, weekend day,Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday>.Additionally, you can also enter a month interval here.

Behavior

The process will run at the defined times. As before, if a process is running andoverruns its next run time, that run time is skipped.

User Interface

The following figure shows the user interface for creating a monthly recurrence:

Figure 22. To create a monthly recurrence.

Yearly recurrence scheme

Description

The yearly recurrence scheme enables you to set a process to run on a specifieddate on a specified month, for example, the 15th of November every year, as wellas to specify soft dates in a given month.

Recurrence schemes


Attributes

The yearly recurrence scheme has two possible attribute categories:

� Run on a given day in a given month. The day number and the month arespecified. For example, you can set a process to run on the 15th of Novemberevery year.

� Run on the <first, second, third, fourth, last> <day, weekday, weekend day,Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday> of agiven month.

Behavior

The process will run at the defined times. As before, if a process is running andoverruns its next run time, that run time is skipped.

User Interface

The following figure shows the user interface to create a yearly recurrence:

Figure 23. To create a yearly recurrence

CODA softdate recurrence scheme

Description

The CODA softdate recurrence scheme enables you to specify soft dates, such asPB (Period Begin). This option is only available if CODA-Financials is enabledin the configuration utility of BOW.

Recurrence schemes


Attributes

The yearly recurrence scheme has the following four attributes:

� Soft date.� User name.� Password.� Company.

The last three are used while logging on to CODA Financials to calculate thenext occurrence of the soft date.

Behavior

The process runs at the defined times. As before, if a process is running andoverruns its next run time, that run time is skipped.

User Interface

The following screenshot shows the user interface to create a yearly recurrence:

Figure 24 To create a CODA softdate recurrence.

Recurrence schemes


Ranges

Description

These recurrence schemes can be defined with a range.

Attributes

A range has the following attributes: a start date and one of the following:

�� No end date.

�� End at date.

�� End after a preset number of occurrences.

For example, you can specify a process to start on 11-30-1999 and end by12-15-1999, or start on 11-30-1999 and run 10 times.

Behavior

If either an end date or end after number of occurrences is set, the process willnot run after these conditions are met.

User Interface

You can see the user interface for ranges in the figures for the interval, monthly,and yearly recurrences.


IntroductionThe Baan OpenWorld Broker has a powerful library of built-in data types. Built-in data types are logical data types built into the Broker. These logical data typesare the primitive types from which you can construct composite types, such asrows and tables. Built-in types are stored in the \predef\system folder.

If you must enter a type in a dialog box, you can click the Type Assistant buttonto open the type assistant. In the type assistant, you can browse to a type or clickone of the buttons that represent a primitive type.

Overview of primitive typesThe primitive types in the Broker are:

23 Built-in primitive types

Built-in primitive types


Primitive typesType DescriptionNumber All numeric data, irrespective of whether the data is in integer or

floating-point format. The default value is 0.String Text data of any length. The storage space expands automatically

according to the length of the text. The default value is the emptystring ("").

Time A point in time, for example, 12:15:00 p.m. on March 17, 1999.Both the date and time are described by a single value of Time.The default value is the current time, taken from the computerclock.

Interval An interval of time, for example, 17 seconds or 3 days. Thedefault value is zero days and seconds.

Time Span A period between two points in time, for example, the first week of2001.

Picture A picture in any supported graphics format.Sound An object of type sound stores a sound that can be played

through the workstation�s speaker system. Sounds can originatefrom Windows wave audio (WAV) files, from Media ControlInterface (MCI) files, or from other supported sources.

TextAttribute

The TextAttrib logical data type describes fonts and attributes,such as font size, color, text effects, alignment.

Box Attribute The BoxAttrib logical data type describes attributes of boxes,such as line style and thickness.

Color Colors are defined in RGB (Red, Green, Blue) format.Void You use the Void type to indicate that there is no data at all.Object Object is a placeholder for any kind of object. You can use this in

the scripting language, to refer to objects of unknown type.UniqueId Values of the UniqueId logical data type are system-generated

unique number values. Unique IDs are useful for identifyingobjects.

Exception An exception is automatically generated if a runtime error oranother exceptional situation occurs which causes a deviationfrom the normal flow of processing.

OleObject An OleObject is a general placeholder for Microsoft COMAutomation objects, sometimes also called OLE or ActiveXcontrols. You can use OleObjects to integrate with externalprograms and functions through a COM interface.

HTML Objects of type HTML (Hypertext Markup Language) store parsedtext strings in HTML format. You can construct a HTMLdocuments from strings or you can use the Internet . getURL ()operation to retrieve HTML documents from the World Wide Web.



For information about the internal data representation of built-in types, see thecorresponding class description in the Scripting Language Reference(U7278D US).

OperationsEach built-in primitive type has a corresponding class in the scripting language.These classes have operations that you can use on values of the same type. Forexample, the String class has an operation toClipboard, which copies stringsto the clipboard. You can invoke the toClipboard operation on any value of thetype String, for example:

"Sample text" . toClipboard ()

(3.14157) . asString . toClipboard ()

\vars\stringGlobalVar . toClipboard ()

(where \vars\stringGlobalVar is a global variable of type String).

These operations are fully documented in the Scripting Language Reference(U7278D US).


The purpose of this chapter is to describe new functionality in OpenWorldBroker that enables the OpenWorld Broker to act as an OpenWorld AdapterServer, and therefore serve clients such as BaanERP or any otherclient/application that is connected to Baan OpenWorld through an OpenWorldAdapter. OpenWorld Adapter provides two kinds of services:

� Data manipulation: Insert, update, delete, show, list, and so on.� Method invocation

In the scope of this project, OpenWorld Broker provides only the methodinvocation service. Two types of method invocation is supported: a fixed set ofspecific Broker services and services that Broker will provide on behalf ofcomponents (ERP backend applications) that are connected to Broker.

Functional overviewThe services that OpenWorld Broker provides are:

� Fixed set of Broker related services.For example, to run a given profile, enable or disable processes, orsynchronize data across components.

� Act as an OW Adapter Server on behalf of other components that do not havean adapter server interface, but are connected to Broker through one of itsinterfaces.

OpenWorld Adapter clients will see this interface as, for example:

ReturnValue Broker.startProfile (Param1, Param2, …)

ReturnValue Broker.synchronize (Param1, Param2, …)

ReturnValue OnlineServer.ATP (Param1, Param2, …)

ReturnValue OnlineServer.CTP (Param1, Param2, …)

Where both ReturnValue and Parameters are defined as type safe objects, Javaclasses, that represent the return value and input parameters.

Here, Broker indicates the fixed set of Broker services and OnlineServer is acomponent object in Broker.

24 Broker as an Adapter Server

Broker as an Adapter Server


Broker users can create a user-defined operation on the Component object thatcan be invoked through the adapter interface. Because these operations are globalscript objects, the operations can be implemented in either Brokers nativescripting language or in IActive Scripting (VBScript, JavaScript).

Broker will accept all requests for service invocation made by the adapter. If theservice request is not directed to Broker, the server will look for a Componentobject with the corresponding name and user defined operation.

Technical Overview

To allow OpenWorld Adapters to communicate with Broker, the Broker COMClient is updated with a new method on the IBaanRepository interface that hasthe following syntax:

HRESULT InvokeServiceMethod (strDLLName, strFuncName,SAFEARRAY(VARIANT)* pvarParam, VARIANT* pvarResult)

This method will be the only entry point into the Broker software. By exposingthis method in the COM Client, other software component can make use of thisnew Broker service.

Messages received in the Adapter software are converted into a generic BusDocXML documents and the modified adapter software will extract from thosedocuments the DLL name and the function name that must run, as well as a listof parameters (encoded as XML documents). These parameters will be passed tothe Broker Server.



Broker services

The fixed set of Broker services is currently defined as follows:

DLL/object name Function name ParameterIterator name �synchronize� [parameter-value, flags]Type name �synchronize� strComponent, strCode,

[strSite, flags]Profile name �start� [flags]Script name �run� [parameter-value]Periodic process name �enable� 1 = enable, 0 = disable

Component Object � Operations

Function

In addition to these services, Broker can also perform operations on behalf ofcomponents. The operations are accessed through the COM client, or through thenative scripting language in the form of:

ReturnType ReturnValue = Component . <OperationName>

(ParamType ParameterValue)

HRESULT InvokeServiceMethod (strComponentName, strOperationName,SAFEARRAY(VARIANT)* pvarParam, VARIANT* pvarResult)



User Interface

The Component editor is updated with a new tab used to add new user-definedoperations to the Component object.

The user can use the Add and Remove buttons to add operations to a list fromthe archive. The listview shows the operation name, the script name, and itsfolder or path. The operation name is, by default, the name of the script and notthe full path, although the user can alter the name, and therefore create an aliasfor the script, when called through the component. When browsing theconfigured operations, the user can view the scripts� parameter and return types.



Script object with parameter and return values

Function

The Global Script Object is updated and now accepts parameters and can return avalue.

Global script objects are stand-alone scripts implemented in either native or anIActive scripting language. The script object has one parameter, and one returnvalue, each of which is defined as a type in the Broker repository. The parameteris exposed in the script with the Parameter object, and the return value is setby simply returning the value from the main function. The script object has oneoperation defined: �run�, and can be executed from within the native scriptinglanguage or through the COM client, for example:

Number n = \myScript . run (“parameter string”);

User interface

The script object editor, shown here, is modified to include the parameter andreturn type selectors, and the script type selection box. If you select the IActiveoption, the script engine and external file link edit boxes are also visible. Toenlarge the script editor, you must double-click the script edit window, or pressthe F4 function key.



Broker BOI Development

Function

Each Broker service that is to be exposed, which are listed in Section 3.2.1, mustbe represented by a QCD/DCD document. This document is then used in theBOI compiler to generate the BOI wrapper code. For more informationregarding BOI generation, see the documentation for OpenWorld Studio.

Mapping of dll and method names in the QCD/DCD

The following items are example QCD files for various Broker objects andmethods, with a small explaination of each.

Scripts

dllname: �\\AdapterTest\\getNumCustomers�

(The full path of the script object in Broker repository.

methodname: �run�

(The only valid method on a script object.)

The QCD given is used to expose the script �\AdapterTest\getNumCustomers�through the BOI. The �run� method takes no parameters, and returns a number.

<?xml version="1.0"?>

<QCD>

<ManagerDef Type="getNumCustomersManager">

<Query>run</Query>

</ManagerDef>

<QueryDef Type="run" Language="BaanDLL">

<DLL>\\AdapterTest\\getNumCustomers</DLL>

<Method Scope="Out">run</Method>

<Parameters/>

<Return>

<Element>getNumCustomersReturn</Element>

</Return>

</QueryDef>

<ElementDef Type="run" Id="getNumCustomersReturn"

Model="Elements">

<Group Occurs="Required">



<Element>run</Element>

</Group>

</ElementDef>

<ElementDef Type="run" Model="Data" Datatype="r8"/>

</QCD>

Component Methods

dllname: \\AdapterTest\CustomerComponent.

The full path of the component-object in the Broker repository.

methodname: �insert�

The �CustomerComponent� object has a method called �insert� implemented onit.

The following QCD exposes the �insert� method on the component�\AdapterTest\CustomerComponent.� This method takes parameters firstname(string), lastname (string), address1 (string), address2 (string), country (string),telephone (number), dateofbirth (date-time); and returns a number.


<QCD>

<ManagerDef Type="CustomerComponentManager">

<Query>insert</Query>

</ManagerDef>

<QueryDef Type="insert" Language="BaanDLL">

<DLL>\\AdapterTest\\CustomerComponent</DLL>

<Method Scope="Out">insert</Method>

<Parameters>

<Element Scope="In">firstname</Element>

<Element Scope="In">lastname</Element>

<Element Scope="In">address1</Element>

<Element Scope="In">address2</Element>

<Element Scope="In">country</Element>

<Element Scope="In">telephone</Element>

<Element Scope="In">birthdate</Element>

</Parameters>

<Return>

<Element>insertReturn</Element>



</Return>

</QueryDef>

<ElementDef Type="insert" Id="insertReturn"

Model="Elements">


<Element>insert</Element>

</Group>

</ElementDef>

<ElementDef Type="insert" Model="Data"

Datatype="r8"/>

<ElementDef Type="firstname" Model="Data"

Datatype="string"/>

<ElementDef Type="lastname" Model="Data"

Datatype="string"/>

<ElementDef Type="address1" Model="Data"

Datatype="string"/>

<ElementDef Type="address2" Model="Data"

Datatype="string"/>

<ElementDef Type="country" Model="Data"

Datatype="string"/>

<ElementDef Type="telephone" Model="Data"

Datatype="r8"/>

<ElementDef Type="birthdate" Model="Data"

Datatype="dateTime"/>

</QCD>

Type::Synchronise

dllname: �\\cis\\ComponentRow.�

The full path of the row-type in Broker repository.

methodname: �synchronize�

The only valid method on a row-type.

The QCD given exposes the row-type �\cis\ComponentRow� through the BOI.The �synchronize� method takes two string parameters, Component and Code,and returns a number.




<QCD>

<ManagerDef Type="ComponentRowManager">

<Query>sync</Query>

</ManagerDef>

<QueryDef Type="sync" Language="BaanDLL">

<DLL>\\cis\\ComponentRow</DLL>

<Method Scope="Out">synchronize</Method>

<Parameters>

<Element Scope="In">string1</Element>

<Element Scope="In">string2</Element>

</Parameters>

<Return>

<Element>synchronizeReturn</Element>

</Return>

</QueryDef>

<ElementDef Type="synchronize" Id="synchronizeReturn"

Model="Elements">


<Element>synchronize</Element>

</Group>

</ElementDef>

<ElementDef Type="synchronize" Model="Data"

Datatype="r8"/>

<ElementDef Type="string1" Model="Data"

Datatype="string"/>

<ElementDef Type="string2" Model="Data"

Datatype="string"/>

</QCD>

Mapping of datatypes

The following mapping is implemented:

Broker Type QCD/DCD typestring Stringnumber r8date dateTimeobject Element



Run-time configuration - Bus Components

Function

In order for Baan OpenWorld Broker 2.1 to receive service requests from clients,the Broker Server must start an Adapter listener service. The listener will thenforward the requests to Broker through the COM client. The listener itself mustbe configured to start a particular Bus Component. For more information on BusComponents, refer to the documentation for Baan OpenWorld Adapter.

User interface

Broker can automatically start a Bus Component on startup by specifying theBus Component name in the Broker configuration MMC snap-in.

Bus Components are specified in the form of cn=XXX, o= YYY, as shown here.The Bus Component is started and shut down with the Broker service. The BusComponent can also be disabled, if it is not needed.

By default, the Bus Component will log into Broker using the SUPERUSERaccount. To override this default setting, you must add a UserID and Passwordstring keys to the system registry key:�HKEY_LOCAL_MACHINE\SOFTWARE\OASHS\<ServiceName>\BusComponents.�

NOTE

Developer's GuideError! No text of specified style in document. - Page 1

AAccess database, 20-23Access rights, 14-2Action wizard, 9-5ActiveX, 20-38Alert, 12-1Alerter, 12-1, 20-4AMI, 20-92Application Messaging Interface. See

AMIArray loop, 6-9Array type, 20-72

BBackground query, 10-3BizTalk framework, 20-98bsrvitf.DLL, 19-2Built-in data types, 23-1

CCheck box, 20-37Check in, 17-1, 17-5Check out, 17-1, 17-4Client-server architecture, 2-1Clipboard, 23-3Code mapping, 7-7Color scheme, 9-4Color tool, 9-3COM interface

IBaanFolder, 19-21IBaanIntegrationServer, 19-8IBaanObject, 19-19IBaanRepository, 19-14

COM interfaces, 1-2, 19-1

Component, 20-6Component integration, 20-68Component integration subsystem, 7-1Compressed object storage, 3-6Configuration utility, 2-3Construct, 7-17Cursor library, 20-21

DDatabase connector, 20-9Delete, 7-17DLL proxy, 20-12do statement, 6-9Dynaset, 20-21

EE-mail, 8-4Enumeration type, 5-1, 20-66, 20-73Environment, 20-14Exceptions, 6-9Export locale strings, 15-2Exporting objects to file, 16-1Expression assistant, 9-11Expression tool, 9-2Expressions, 6-1

FFile object, 20-16Flags, 3-6Fonts tool, 9-2for statement, 6-8Form, 10-1, 10-2, 20-26Format for numbers, 20-35ForwardOnly, 20-21

25 Index

Error! No text of specified style in document.

Developer's GuidePage 2 - Error! No text of specified style in document.

GGauge, 20-37GetTimestamp, 7-17Global variable, 20-47GUID, 7-8

IIBaanFolder, 19-21IBaanIntegrationServer, 19-8IBaanObject, 19-19IBaanRepository, 19-14if statement, 6-7Import locale strings, 15-2Importing objects to file, 16-1Internet e-mail, 20-92Iterator, 7-22, 20-49

KKernel, 2-1

LLabel, 17-6Language support, 15-1Language-independent text table, 20-

114Load, 7-17, 19-22Locale strings, 15-1Locking, 17-5Log on, 14-1

as a different user, 20-118Logging system, 18-1Logical data type, 5-1, 7-10, 20-65

MMailbox, 8-5Menu, 20-85Message class, 8-1Message handler, 8-3, 20-88Message queue, 8-3, 20-91Message source, 8-3, 20-92

Messaging, 8-1Microsoft Access, 20-23Microsoft Management Console, 2-3Microsoft Message Queue Server, 20-

92Microsoft SQL Server, 20-23Modal dialog, 20-44Modeless dialog, 20-44MSMQ, 20-92

NNamed colors, 9-4Named object, 20-3Naming rules, 3-5NT service, 2-1

OObject flags, 3-6Object repository, 2-2Object set object, 20-99ODBC, 20-9OFA file, 16-1Ole object, 20-38Oracle database, 20-24

PPage variable, 20-45Periodic process, 11-1, 20-101Picture objects, 20-103Poll, 20-90POP3, 20-92PrepareStore, 7-17Primitive operations, 7-17Primitive types, 23-1Protected objects, 3-6

QQuery, 10-1, 10-2, 20-110

Error! No text of specified style in document.

Developer's GuideError! No text of specified style in document. - Page 3

RRecordset, 20-21Repository browser, 3-1Resource objects, 20-112Rollback, 7-16, 17-9Row type, 20-71runModal, 20-44runModeless, 20-44

SScript assistant, 9-12Scripting language, 6-1sendMessage, 20-120setFlags operation, 3-6SMTP server, 8-4Snapshot, 20-21SQL expression, 20-17, 20-20SQL Server, 20-23State variable, 20-45Store, 7-17, 19-27StoreNew, 7-17Superuser, 20-119SYNC_ALWAYS_NEW, 7-13SYNC_STORE_ALL, 7-13Synchronize, 19-22

TTable loop, 6-9Table operations, 20-24Table type, 20-72Text table, 20-114Time stamp, 7-13Tool dock, 9-1Translation support, 15-2Trusted logon, 14-1Two-phase commit, 7-14

Type, 5-1, 7-10, 20-65Type assistant, 9-11

UUser, 20-3, 20-118User group, 20-120User interface, 10-1User management, 14-1

VVariable, 4-2VBA. See Visual Basic for ApplicationsVCS. See Version Control SystemVCS object, 17-3Version Control System, 17-1

check in, 17-5check out, 17-4discard, 17-10enable, 17-2export, 17-9get, 17-8label, 17-6locking, 17-5rollback, 17-9

View object, 20-45Visual Basic for Applications, 19-7

Wwhile statement, 6-9Windows NT service, 2-1Workflow, 20-3, 20-121

XXML, 19-22XML documents, 20-97