Programmer's Guide for BaanC Client Adapterbaansupport.com/docs/baan/Programmers Guide for Baan C...

Baan OpenWorld 2.1

Programmer's Guide for BaanCClient Adapter

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: U7538A USGroup: User DocumentationEdition: ADate: January, 2001

i

Programmer's Guide for BaanC Client Adapter

1 Overview 1-1Object-oriented vs procedural 1-1Generated BOIs 1-2Generated BusinessManager 1-2Generated BusinessElement 1-3To use the API 1-5Memory management/ownership 1-5If you use the function model 1-5If you use the data model 1-5DataTypes and Type-Safeness 1-6The error interface 1-6

2 API reference 2-1BusinessElement 2-1BusinessElementManager 2-2The Iterator 2-6Synchronization 2-7The UserInfo 2-8Error functions 2-9Generic Error Functions 2-9Type-Specific Error Functions 2-11

Appendix A Function model example 1

Appendix B Data model examples 1

Appendix C Special features examples 1

Appendix D Error API example 1

Table of contents

Table of contents

Programmer's Guide for BaanC Client Adapterii

Programmer's Guide for BaanC Client Adapteriii

This document describes the BaanC OpenWorld Adapter Client API. This API ispart of the OpenWorld Adapter For BaanERP and can be used to write Clientcode For OpenWorld in BaanC. For more high-level descriptions of thefunctionality of an OpenWorld Client in combination with BOIs the BOI UsersGuide can be referred.

References� Baan OpenWorld 2.1, User�s Guide for BOIs (U7452C US).� Baan OpenWorld 2.1, Configuration Guide for Adapter for BaanERP

(U7305E US).� Baan OpenWorld 2.1, Adapter Installation and Configuration Guide

(U7304D US).� Baan OpenWorld 2.1, Deployment Guide (U7455B US).� Baan OpenWorld 2.1, BOI Developers Guide (U7453B US).� Baan OpenWorld Adapter (Java) Documentation:

− Adapter Configuration Help− BusComponent Editor Help− JavaDoc

About this document

About this document

Programmer's Guide for BaanC Client Adapteriv

Programmer's Guide for BaanC Client Adapter1-1

This document describes how to use the OpenWorld Client Adapter API inBaanC. You use an OpenWorld Adapter with BOIs. The BaanC client Adapteruses BOIs that are generated in BaanC.

With the BOIs and this API you can make your BaanERP program a client of anOpenWorld server.

This document is an extension to the User�s Guide for BOIs, which describes thefunctionality you can use with BOIs. This document assumes you haveknowledge of the things described in the User�s Guide for BOIs. This documentdescribes how you can use the functionality described in the Users Guide forBOIs.

Object-oriented vs proceduralThe most visible language-specific feature of Baan 3GL is procedural instead ofobject-oriented. However, this does not mean that the interface is completelydifferent. Baan3GL is designed in an object-oriented fashion.

To achieve this, Baan simulates objects with an XML tree. This tree representsthe state of the object. To invoke methods on this object, Baan passes the state asthe first parameter in a function call. All functions for a particular object areusually grouped in one DLL.

This solution does not allow Baan to use all features of object orientation. Baandoes not have any inheritance, nor is polymorphism supported. However, Baandoes get encapsulation.

Most of the methods that are available through inheritance in Java, are eithergenerated on the BOIs, or are written on a more generic object, that simulates aform of inheritance. An example of the latter is the Manager.add() method,which can be called with the generated manager.

Example Java:

SpecificManager.add( SpecificBusinessobject )

Example BaanC:

Manager.add( SpecificManager, SpecificBusinessobject )

1 Overview

Overview


Generated BOIsBesides the API of the Adapter, the BOI API consists of the functions on thegenerated BOIs itself. These BOIs are generated from a BOI Definition describedin QCD/DCD files. The generated code consists of Managers and Elements. Thefunctions available on these generated BOIs depend on the content of theQCD/DCD files.

Generated BusinessManagerAs example we use

package : package1

name : manager1

functions : long function1(f1_par1, f1_par2)

BusinessElement function2( f2_par1, f2_par2)

f1_par1 : double

f1_par2 : string

f2_par1 : BusinessElement

f2_par2 : BusinessElement

always generated*

long package1.manager1.create( )

depending on QCD

long package1.manager1.function1(long manager1,double

f1_par1,string f1_par2)

long package1.manager1.function2(long manager1, long

f2_par1, long f2_par2)

* The name of the manager depends on the content of the QCD.

Overview


Generated BusinessElementElements can contain different types of data.

� Basic type.� Structure of basic types.� Structure of BusinessElements.� Array of basic types.� Array of BusinessElements.

Each of the attributes of these types causes set and get functions to be generated.

As example we use

package : package1

name : Order

Layout example1 : Order = array of doubleval (doubleval = basic type double)

Layout example2 : Order = structure {long field1, double field2, string field3}

Layout example3: OrderContainer = structure{Order order1}

always generated*

long package1.order.create( )

This function creates an BusinessElement of type Order

long package1.order.destroy( )

This function destroys a BusinessElement of type Order

string package1.order.type( )

This function returns the internal type(name) of an generated businessElement

string package1.order.id( )

This function returns the name of an generated object wrapper

Overview


depending on QCD (example1)

double package1.order.getdoublevalat(long order, long index)

void package1.order.adddoubleval (long order, double d)

void package1.order.setdoublevalat(long order, double d,

long index)

void package1.order.insertdoublevalAt(long order, double d,

long index)

void package1.order.removealldoubleval(long order)

void package1.order.removedoublevalAt(long order long index)

void package1.order.removedoubleval (long order, double d)

long package1.order.sizedoubleval (long order)


void package1.order.setfield1(long order, long value)

long package1.order.getfield1(long order)

void package1.order.setfield2(long order, double value)

double package1.order.getfield2(long order)

void package1.order.setfield3(long order, string value)

string package1.order.getfield3(long order)


void package1.OrderContainer.setorder1(long Container, long

Order)

long package1.OrderContainer.getorder1(long Container)

* The name of the BusinessElement always depend on the QCD/DCD

Overview


To use the APIAs explained before, the BOI API contains the following parts.

� The Adapter API.� Generated BOIs.

To use these codes in your application, you must import/link this code.

To include the Adapter API:

#include <bic_tmboa>

To include a specific BOI, which is already compiled in a dll:

#pragma used dll <package><module><name>

example: #pragma used dll tststtestboi

To compile the BOI in your application, which is available as a function:

#include i<package><module><name>

example: #include itststtestboi

Memory management/ownershipAll data retrieved through BOIs is in the shape of BusinessElements (XMLtrees). The BOIs consist of generated BusinessElements code, which can act astypesafe-wrappers for these XML trees. Through these wrappers, you canretrieve the base types from or set them into the XML tree. (setters and getters).

If you use the function modelIf you retrieve the return and out parameters of a BOI with the function model,you must make sure that this BusinessElement, represented by an XML tree, isremoved from memory. On a BusinessElement, you can use the Destroy functionfor this.

If you use the data modelAll the data retrieved by the BOI is stored inside the Manager with which youretrieve this data. You must make sure that after you finish using a manager, youdestroy the data in it. You can also delete the individual BusinessElements whileyou retrieve them from the Iterator.

Overview


DataTypes and Type-SafenessBaanC supports a limited set of base datatypes:

� Long.� Double.� String.

OpenWorld supports a larger set of datatypes, so the BOI does a mappingbetween them. You must refer to the documentation provided with your BOI todefine this mapping. For example, BaanC base types can contain such things asDate and DateTime.

If you use generated BusinessElements, then you must make sure as a clientprogrammer that you pass the correct XML-tree to this type-safeBusinessElement.

If, for example, you retrieve a specific BusinessElement from an Iterator, youmust use the correct BusinessElement for this specific XML-tree.

The error interfaceBaan 3GL does not support exceptions as Java does. Therefore, error handling isdifferent from what is described in Chapter 6 , �To handle errors,� of the User�sGuide for BOIs. Instead of catching exceptions, the Adapter API for BaanCprovides functions to check whether an error occurred, and what the error is.

To get the error semantics equal to Java, the application must check for errorsafter each call to the BOI interface. However, if a number of relativelyindependent calls are performed, you can check the errors after a number of calls.

Three types of errors can occur:� BusErrors.� ApplicationErrors.� SynchronisationErrors.

They contain information equivalent to the different types of Exceptions in theJava API.

These different type of errors have different content. Various functions exist onthe error API to retrieve this data.

BoiError contains a string that indicates the problem.

ApplicationError: contains a list of error parts that each contain a string.

SynchronisationError: contains a struct with three fields; FieldName,MessageCode, and MessageDescription.


BusinessElementlong businesselement.destroy( long businesselem )

Destroys a BusinessElement. It frees up the memory it consumes. This functioncan be used while you go through large BusinessElements to reduce the memoryconsumption of your 3GL program.

businesselem This is the Typesafe BusinessElement.

retval 0 if succeeded, < 0 if a memory/XML error occurs.

long businesselement.getManager( long businesselem )

Returns the manager object to which the BusinessElement object is linked.

businesselem This is the Typesafe BusinessElement.

retval The Typesafe Manager to which this BusinessElement islinked.

2 API reference

API reference


BusinessElementManagerlong manager.close( long manager )

Closes a manager. This function unregisters this manager with the connectionlayer. It does not free up the resources it consumes.

manager This is the Typesafe Manager to close.

retval 0.

Can Generate Error.

long manager.initialize(long manager,const string

buscomponentid())

Initializes a Manager for a specific BusComponent.

manager This is the Typesafe Manager to initialize.

buscomponentid This is the identifier of the BusComponent to initialize thismanager with.

retval The reference to the TypeSafe Manager.

Can Generate Error.

long manager.getTimeout( long manager )

Returns the timeout, which is currently configured for this manager.

manager This is the Typesafe Manager.

retval The time in milliseconds.

manager.setTimeout( long manager, long timeout )

Sets the timeout, which this manager uses during communication. This timeout isthe time, which this Manager waits for a reply from the OpenWorld Backend.


timeout The timeout in milliseconds.

API reference


string manager.getCurrentBackend( long manager )

This function returns the identifier of the BusComponent with which themanager is currently initialized.


retval The string that represents the identifier of the BusComponent.

manager.add( long manager, long buselement )

This function adds a BusinessElement to the control of this manager. With thisfeature new elements can be sent to the backend.


buselement This is the Typesafe BusinessElement to add to this manager.

long manager.synchronize( long manager )

Synchronizes local changed BusinessElement objects to the backend. Thismethod is part of the Data Oriented Programming model, and can be used to add,change, or remove data from the backend (DB).


retval 0.

Can Generate Error.

manager.release( long manager, long buselement )

Release one particular BusinessElement object from this manager. The managerno longer keeps track of the changes of this BusinessElement, and also does notsend it to the Backend or synchronize.


buselement This is the Typesafe BusinessElement to release from thismanager.

API reference


manager.releaseAll( long manager )

Release all the BusinessElement objects from this manager. The manager nolonger keeps track of the changes of these BusinessElements, and does not sendthem to the Backend or synchronize.


manager.remove( long manager, long buselement )

Earmarks a local business object for removal. With the next synchronize on thismanager, the request for removing the business object from the backend is sendto the server.


buselement This is the Typesafe BusinessElement to remove from thebackend.

long manager.destroy( ref long manager )

This function removes a manager and all its content and frees up all the memoryof received BusinessElements. Afterwards, the complete manager is gone andcannot be used anymore. If any references are left to BusinessElements, they arenot valid anymore, and the xml-trees that represent these BusinessElements aredeleted.



manager.destroyData( long manager )

This function releases all the BusinessElements that are controlled by thismanager and frees up the memory they consume. Afterwards you can continue touse this manager.


API reference


manager.setUnconditional( long manager )

Sets the unconditional feature for this manager. With this feature turned on, theoptimistic locking mechanism is disabled. The consistency rules of the backendare, however, still in place.


manager.setUserinfo( long manager, long userinfo )

Sets a UserInfo object to this manager. This manager works with a securitycontext from now on.


userinfo This is the UserInfo object to set in this manager.

API reference


The Iteratorlong iterator.destroy( ref long this )

This function destroys the Iterator object. It does not destroy theBusinessElements retrieved by this Iterator. To destroy all the BusinessElements,use the Manager.destroy and Manager.destroydata functions. Afterwards, thisIterater cannot be used anymore and the reference to this Iterator is 0.

iterator This is the Iterator Object.


long iterator.hasMoreElements( long this )

Determines whether more BusinessElements exist to retrieve from this Iterator.


retval True, if more BusinessElements exist, False if they do not.

long iterator.nextElement( long iterator )

Retrieves the next BusinessElement. If no more business elements are present inthe local buffer, then a call to the backend is made to retrieve the next set of data.The received element can be a basic type or a BusinessElement that has its ownType Safe wrapper.


retval This is the Typesafe BusinessElement retrieved from theIterator.

Can Generate Error.

iterator.hintNextBufferSize( long iterator, long bufsize )

Sets the fetch size for this iterator. The Iterator retrieves all its data in sets, andthe size of these sets is configurable. This can be set with the adapterconfiguration tools, but the size of the set can also be set at run-time with thismethod. Note that retrieving the data in sets is performed for performancereasons. The optimal fetch size depends on the size of one record (and number ofsub records), the transport speed, and the time the OpenWorld backend needs toproduce the data.


bufsize The size of the buffer to use with the next fetch.

API reference


Synchronizationlong synchronization.create( )

Creates a synchronization object, which is a context that you can use to performupdates on multiple managers.

retval The synchronization object.

long synchronization.addManager(long synchronization,long

manager)

Adds a type-safe Manager to this synchronization context.

synchronization The synchronisation object.

manager The type-safe manager to add to the synchronization context.

retval The type-safe manager added.

long synchronization.execute( long synchronization )

Synchronizes the changed BusinessElements in all the type-safe managers in thissynchronization to the backend.

synchronization The synchronisation object.

retval 0.

Can Generate Error.

API reference


The UserInfolong userinfo.create( )

Creates an empty UserInfo object that you can use to store usercontextinformation.

retval An empty UserInfo Object.

string userinfo.getPlainUsername( long UserInfo )

Returns the username that is stored in this UserInfo Object.

retval String that contains the username.

userinfo.setPassword( long UserInfo, const string

password())

Sets the password string in this UserInfo Object.

userinfo The UserInfo object.

password The password to set in this UserInfo object.

userinfo.setUsername( long UserInfo, const string

username())

Sets the username string in this UserInfo Object.

userinfo The UserInfo object.

username The username to set in this UserInfo object.

API reference


Error functionsGeneric Error Functionslong error.hasErrors( )

Checks whether errors are generated and stored by the OpenWorld Client API.The errors are logged while you work with the API.

retval True if errors occurred, False if no errors occurred.

long error.getFirst( )

Returns the first error generated by the 3gl BOI API.

retval Error, of type BusError, SynchronisationError, orApplicationError.

long error.getLast( )

Returns the last error generated by the 3gl BOI API.


long error.getNext( long error )

Returns the next error generated by the 3gl BOI API, according to the givenerror.

error Error generated by the 3gl BOI API.


long error.getPrevious( long error )

Returns the previous error generated by the 3gl BOI API, according to the givenerror.



API reference


string error.getNiceString( long error )

Returns a Formatted String that contains the information in the error. The stringdepends on the type of the error and the data in the error.


retval Formatted string that contains the information in the error.

Examples:

bus error:Security error,missing UserInfo. (Backend Security Mode = ThisUser)

synchronization error:FieldName = ��MessageCode = �ttstps114�MessageDescr. = �Record already exists�

application error:MethodName �nofunc� unknown in dll �otmboab3server�

string error.getErrorType( long error )

Returns the type of an error generated by the 3gl BOI API.


retval String that indicates the type of error: BusError (�bus�),SynchronisationError(�synchronization�), orApplicationError(�application�).

error.clear( )

Clears all the errors logged by the OpenWorld 3gl Client Adapter API.

error.clearlast( )

Clears the last error logged by the OpenWorld 3gl Client Adapter API.

API reference


Type-Specific Error Functionsstring error.getBusErrorString(long buserror)

Returns the string that contains the information in this BusError.

buserror Error generated by the 3gl BOI API, of type BusError.

retval String that contains the information in this BusError.

long error.getApplicationErrorFirstPart(long appllicerror)

This function returns the first detailed error inside this application error.

appllicerror Error generated by the 3gl BOI API, of type ApplicationError.

retval The first part of inside this Application Error

long error.getApplicationErrorNextPart(long app_error_part)

This function returns the next detailed error inside this application error.

app_error_part Detailed error inside an Application Error.

retval The next part of the Application Error.

string error.getApplicationErrorPartString(long

app_error_part)

This function returns the error information from this part of an application error.

app_error_part Detailed error inside an Application Error.

retval The string that contains the error information of this part of theapplication error.

string error.getSynchronisationFieldName(long syncherror)

This function returns a part of the information of a synchronization error, theFieldName that caused the error.

syncherror Error generated by the 3gl BOI API, of typeSynchronisationError.

retval The string that contains the FieldName information.

API reference


string error.getSynchronisationMessageCode(long syncherror)

This function returns a part of the information of a synchronization error, theMessageCode of this error.


retval The string that contains the MessageCode information.

string error.getSynchronisationMessageDescription(long

syncherror)

This function returns a part of the information of a synchronization error, theMessageDescription of this error.


retval The string that contains the MessageDescription information.

Programmer's Guide for BaanC Client AdapterFunction model example - Page 1

long mymanager, ret

mymanager = 0

| Creating typesafe Managermymanager = boa.basictypemanager.create( )

| Initializing typesafe Managerret = manager.initialize( mymanager, "cn=orbix,o=baan.com" )

| Setting timeout to 5 sec.manager.settimeout( mymanager, 2000 )

| Check errors

long copystringret, nofuncretstring str1(25), str2(25)str1 = "The String to Copy"str2 = ""

| doing call on BOI with one argumentcopystringret = boa.basictypeManager.copystring( mymanager,str1)str2 = boa.copystringreturn.getstring2( copystringret )

| Check errors

| doing call on BOI without argumentsnofuncret = boa.basictypeManager.nofunc( mymanager )

| Destroy the businesselement receivedret = businesselement.destroy( copystringret )ret = businesselement.destroy( nofuncret )

| Close the managerret = manager.close( mymanager )| Destroy the managerret = manager.destroy( mymanager )

Appendix A Function model example

Function model example

Programmer's Guide for BaanC Client AdapterPage 2 - Function model example

Programmer's Guide for BaanC Client AdapterData model examples - Page 1

To retrieve data:

long streetmanager, street, resident, iterator,long ret, noresidents, counter

streetmanager = 0| Creating typesafe Managerstreetmanager = boa.streetsmanager.create( )s = manager.getcurrentbackend( streetmanager )ret = manager.initialize( streetmanager,"cn=orbix,o=baan.com" )iterator = boa.streetsmanager.list_aggregated(streetmanager, 0, 2 )

string ComponentId(30)ComponentId = manager.getcurrentbackend( streetmanager )

| Check errors

while iterator.hasmoreelements( iterator )street = iterator.nextelement( iterator )noresidents = boa.streets.sizeresidents( street )for counter=1 to noresidents

resident = boa.streets.getresidentsat( street,counter )

boa.residents.getlastname( resident ))endforret = businesselement.destroy( street)

endwhile| Destroy the iteratorret = iterator.destroy( iterator )| Close the managerret = manager.close( mymanager )| Destroy the managerret = manager.destroy( mymanager )

Appendix B Data model examples

Data model examples

Programmer's Guide for BaanC Client AdapterPage 2 - Data model examples

To update data:

| Assuming Manager is correctly initialized

datatype = boa.datatypes.create()

boa.datatypes.setlong1( datatype, 1 )boa.datatypes.setlong2( datatype, 20 )boa.datatypes.setdouble1( datatype, 10.10 )boa.datatypes.setdouble2( datatype, 20.20 )boa.datatypes.setstring1( datatype, "11110" )boa.datatypes.setstring2( datatype, "22220" )

| Adding local BusinessElement to manager.manager.add( datatypemanager, datatype )

| Synchronize changes to backend.ret = manager.synchronize( datatypemanager )

| Check errors

| Destroy Manager and data

Programmer's Guide for BaanC Client AdapterSpecial features examples - Page 1

To get the name of the current busComponent:

string ComponentId(30)ComponentId = manager.getcurrentbackend( myManager )

To change the timeout:

| Getting the cureent timeoutlong timeouttimeout = manager.gettimeout( mymanager )| Setting timeout to 5 sec.manager.settimeout( mymanager, 5000 )

To use UserInfo:

| create a new userinfo Objuserinfo = userinfo.create()userinfo.setusername( userinfo, "myName" )userinfo.setpassword( userinfo, "myPassword" )

| setting the userinfo to the manager, to enable securitymanager.setuserinfo( myManager, userinfo )

Appendix C Special features examples

Special features examples

Programmer's Guide for BaanC Client AdapterPage 2 - Special features examples

Programmer's Guide for BaanC Client AdapterError API example - Page 1

Function that puts all the errors in message boxes:

function void checkandprinterrors(){

long error.objif error.haserrors() then

error.obj = error.getfirst()while error.obj

message(error.getnicestring(error.obj))error.obj = error.getnext(error.obj)

endwhileerror.clear()

endif}

To retrieve the error type:

long error.objstring errorType(16)

if error.haserrors() thenerror.obj = error.getfirst()while error.obj

errorType = error.geterrortype( error.obj )error.obj = error.getnext(error.obj)

endwhileendif

Appendix D Error API example

Error API example

Programmer's Guide for BaanC Client AdapterPage 2 - Error API example

Date post:	14-Mar-2018
Category:	Documents
Upload:	lyhuong
View:	214 times
Download:	0 times

Programmer's Guide for BaanC Client Adapterbaansupport.com/docs/baan/Programmers Guide for Baan C...

Documents