Business Object Connector Manual

Copyright © 2004 Mincom Limited

All rights reserved.

No part of this document may be reproduced, transferred, sold, or otherwise disposed of, without the written permission of Mincom Limited.

Table of Contents

Introduction to Mincom Connector...................................................................................................1

Topic 1 – Mincom Connector Overview............................................................................................3

Topic 2 – The Mincom Object Model.................................................................................................6

Practice – Defining an Object......................................................................................................10

Demonstration – Business Object Browser.................................................................................12

Practice – Defining an Ellipse Object...........................................................................................13

Learning Checkpoints..............................................................................................................15

Topic 3 – COM Overview................................................................................................................16

Walkthrough – Object Connection Process..................................................................................19

Learning Checkpoints..............................................................................................................21

Topic 4 – Developing with Excel.....................................................................................................22

Demonstration – The Excel Sample – Behind the Scenes............................................................23

Practice – Modify an Excel Application........................................................................................27

Topic 5 – Developing with Microsoft Excel and Word.....................................................................28

Practice – Adding MIMSX Macros to an Excel Spreadsheet.........................................................29

Practice – Create Macros in a Word Document...........................................................................36

RevTopic 6 – Developing with the MSO interface...........................................................................37

Demonstration – Walk through example.....................................................................................41

Practice – Creating an Excel Application.....................................................................................42

Review of MSO Interface.........................................................................................................43

Topic 7 – Java Middleware..............................................................................................................44

Practice – Java Exercise 1...........................................................................................................59

Practice – Java Exercise 2...........................................................................................................60

Review of Java.........................................................................................................................61

Course Summary...........................................................................................................................62

Training Evaluation..................................................................................................................63

Appendix A – FAQs.........................................................................................................................65

Appendix B – Additional Exercises.................................................................................................72

Practice – Employee Leave.........................................................................................................73

Appendix C – Reference Material...................................................................................................77

Business Object Connector 2003 Mincom Page i

Notes Introduction to Mincom Connector

Mincom Connector 2004 Mincom Page 1 of 80

Notes

Page 2 of 80 2003 MincomMincom Connector

Notes Topic 1 – Mincom Connector Overview


Notes

Concepts:

Mincom Connector is a set of tools that provide users with the functionality to develop their own custom applications to access Ellipse Business Objects and Ellipse MSO Screens.

Endless application possibilities are available through the Mincom Connector. Existing productivity tools, such as Microsoft Office, and development environments, such as Microsoft Visual Basic, Borland Delphi, Visual .Net etc., can now take full advantage of Ellipse Business Object functionality.

Mincom Connector is available on multiple platforms:

Windows using the COM interface

Unix, OpenVMS, NT, IBM OS/390 using C APIs

JAVA

Mincom Connector consists of the following software components:

Ellipse Business Object Services Library

Ellipse Run-time Repository Server Library

Ellipse Non-Windows C API

Ellipse API (Client and Java Middleware)

Ellipse Local Data Services (Ellipse Cache)


Notes


Notes

Topic 2 – The Mincom Object Model


Notes

Concepts:

In order to maximize the use of the Connector, it is necessary to understand the Ellipse architecture and the Mincom Business Object Model.

The Ellipse Client/Server Architecture is a three-tiered structure made up of the following components:

Presentation Layer

Applications Layer

Database Access Layer

Each layer is independent of the others. There is no technological dependence between layers, except as defined by the middleware. This independence allows the separation of data layout and the application of business rules.


Notes

Presentation Layer

Mincom Connector provides the tools necessary to develop applications that exist in the Presentation layer. Current Ellipse Windows applications (all MSQ programs) form the Presentation Layer.

Applications Layer

The applications layer for Ellipse provides all the business rules. This layer consists of server programs (named MSKxxx), green screens (named MSOxxx) and the traditional subroutines (named MSSxxx) which provide the ELLIPSE business rules.

A MSK program at the Application Layer implements each Ellipse Service. The MSK's are Cobol programs that run under the control of a Transaction Processor (ie MincomTP, BEA Tuxedo, IBM CICS/ESA or Digital ACMS). One MSK program provides all the necessary methods for a ELLIPSE Business Object.

Database Access Layer

The Database Access layer is provided by Ellipse Macros and is implemented differently on each platform. The database access layer provides services to the application layer. For example, creating a new row in the database or retrieving several rows in a database according to a selection criteria.

Most Relational Database Machines (RDBM's) are accessed by native SQL, except for Oracle that uses the OCI interface.

Since the interfaces to the RDBM's are generic, the same source code can be used against different vendor’s databases.


Notes

Concepts:

Object A thing, or idea of a thing that has a behavior (i.e. does something) and a state (which is changed by the behavior).

Attribute Definable property of an object. These properties describe and define the object’s state. A property may be another object.

Method An action that can be performed on an object or by an object. Methods may change the properties and state of an object.

Event Signals when some kind of change in state has occurred.

Class Abstract definition of an object, describes the idea of an object.


Notes

Practice – Defining an Object

Scenario: In this activity, you will define an object chosen by your instructor. List the attributes, methods, and events of the object.

Class:

Attribute(s):

Method(s):

Event(s):


Notes

Concepts:

Ellipse Object Model Details are published in the ELLIPSE Repository and can be reviewed via the Business Object Browser. This information is also available in the help files.

Ellipse Object Example:

Ellipse Class: Employee

Ellipse Attributes: EmployeeId, FirstName, LastName

Ellipse Methods: Create, Modify, Retrieve, Fetch, etc.

Additional Examples:

Ellipse Classes: WorkOrder, EmpAvailability, APLItem, etc

Ellipse Attributes: Equipment.AccountCode, WorkGroup.Crew

Ellipse Methods: Standard operations, such as Create, Modify,Retrieve, Fetch, Search, Detail, etc.


Notes

Demonstration – Business Object Browser

Scenario: Use the Business Object Browser to look up Ellipse objects and their corresponding attributes and methods.

EnCore Path:

Demonstration Script:

Open MSQMOM.EXE in the Ellipse Client BIN directory

Review Ellipse Objects

Review corresponding attributes and methods


Notes Practice – Defining an Ellipse Object

Scenario: Use the Business Object Browser to look up an Ellipse Business Object.

EnCore Path:

Demonstration Script:

Open MSQMOM.EXE in the Ellipse Client BIN directory (C:\Program Files\Mincom\Ellipse\WinView\Bin)

Review the WorkOrder Business Object

List five WorkOrder attributes

1. CalcEquipCost

2. ClosedTo

3. ZipCode

4. FinalCosts

5. AccountCode

List three WorkOrder methods

1. Create

2. Delete

3. Modify


Notes


Notes

Concepts:

The Ellipse Repository contains the definitions of the data (objects) and evolves along with the software releases. The Repository is unique to the Ellipse application. The Ellipse API contains roughly four or five actions and is installed only once. The Repository, however, changes with each version of the software and is updated often.


Notes

Learning Checkpoints

Question 1.

List the three layers of the Ellipse Application Structure.

Question 2.

How can you access the Ellipse Repository?

Question 3.

Define the following:

Object

Method

Attribute

Event

Class


Notes Topic 3 – COM Overview


Notes

Concepts:

Microsoft ® Component Object Model, COM, is the core MS architectural technology after the WIN32 API. COM is the interface that enables users to develop applications for the windows platform.

COM enables users to create applications in the following:

Microsoft Excel Microsoft Word Microsoft Access Microsoft Project And other COM enabled applications

Benefits of developing with COM include:

Product openness Deliver functionality as components Internet and HTML hosting possibilities Exploit client platform technology


Notes

Concepts:

Connector programs are based around the building, sending and processing of network messages. Therefore, connector programs need a connection to the server—in Ellipse; a MIMSXServer object maintains the connection.

A network message (Block) is made up of requests, which are made up of instances. Blocks, requests and instances may all contain fields.

The Object Connection Process is based on the Object Hierarchy.

MIMSXServer An object representing a connection to a ELLIPSE Server.

MIMSBlock A network block (i.e. a set of requests) that is sent to the ELLIPSE Server for processing.

MIMSRequest A command to be executed by the ELLIPSE Server (i.e. WORKORDER.Fetch).

MIMSReply A network reply from the ELLIPSE Server in response to the MIMSBlock.

MIMSInstance The input or output parameters of a specific command in a MIMSRequest.

MIMSField A name/value pair used to define fields within a MIMSBlock, MIMSReply, MIMSRequest or MIMSInstance.


Notes

Walkthrough – Object Connection Process

Scenario: Connect to MIMSX Server.

EnCore Path:

Walkthrough Script:

Open mimsx_wo.xls, enable macros

Open the VB editor, select Tools>Macro>Visual Basic Editor from the menu bar or press ALT+F11

Create initial Ellipse Server Object

Set gobjMIMS = new MIMSXServer

Initialise the MIMSX object

gobjMIMS.Initialise

Connect to Ellipse

gobjMIMS.Connect(False)

Establish Block framework

Set myBlock = gobjMIMS.Blocks.New(“myBlock”)

Create initial request

Set myRequest =myBlock.Requests.New(“myRequest”)

Define requested service to Request

myRequest.AddFieldNameValue “_Service”“ELLIPSEOBJECT.Methodname”

Define ReplyList for Service (optional)

myRequest.AddfieldNameValue “_ReplyList”“Attribute1, Attribute2…”

Define initial Instance to contain request information

Set myInstance1 = myRequest.Instances.New(“myInstance1”)

Add as many Name/Value pairs for request instance as needed

myInstance1.AddFieldNameValue(“AttributeN”,someVarValue)


Notes Add other instances and/or requests as desired

Note: if performing silent login, then first request should be for a ELLIPSE.Login service

Once a Block of requests is complete, send to ELLIPSE Server, assigning result to Reply object

Set myReply = myBlock.Send (or myBlock.SendASync)

Check reply for errors generally,

for each ErrorItem in eObj.Errors

…or check each Request in Reply for errors

if myReply.IsError(RequestNo)

… or check each Instance in a Request for errors

if myReply.IsError(RequestNo, InstanceNo) orif myReply.Requests.Item(N).IsError

Use Reply information as desired

for each Request in myReply.Requests for each Instance in Request.Instances

Disconnect from Ellipse

eObj.disconnect


Notes

Learning Checkpoints

Question 1.

What are the benefits of developing COM applications?

Question 2.

What is the Connector Object Hierarchy?

____________________

____________________

____________________

____________________

____________________

Question 3.

Describe the object connection process.


Notes Topic 4 – Developing with Excel

Concepts:

Use Excel when data is best viewed in rows and columns, and if data requires manipulation or advanced formulas. Timesheets and financial statements benefit from the spreadsheet features in Excel.


Notes

Demonstration – The Excel Sample – Behind the Scenes

Scenario: Retrieve accounting information and review it using Excel.

EnCore Path:

Demonstration Script – Connect to Server:

Find and register mimsx.dll on local directory

..\mware\4.16\mimsx.dll

Copy sample spreadsheet from the sample code directory:

\Samples & Demos\mimsx.xls

Double-click mimsx.xls to load sample spreadsheet - click Enable Macros

Select MIMS RetrieveAccounts from MIMS menu Enter login details and click OK Choose default parameters on displayed form Results of search inserted into spreadsheet Select MIMS Disconnect to close server

Demonstration Script – View Source Code:

To view macro source, select Tools, Macro, Visual Basic Editor. In VB, select Tools, References and check Mincom - MIMS

Business Object Services Library to provide access to interface declaration.

Ensure Project Explorer is visible (View menu or control-R).

Demonstration Script - Workbook Routines

Open VBAProject for mimsx.xls, expand Microsoft Excel Objects and double-click ThisWorkbook.

Subroutine Workbook_Open shows code to add Ellipse menu - executed when file opened.

Subroutine Workbook_BeforeClose shows code to remove Ellipse menu when file closed.


Notes Demonstration Script - Module Routine 1

In Project Explorer, open Modules for mimsx.xls and double-click mdlMacro.

Subroutine MIMS_Connect shows code to create, initialize and connect to ELLIPSE Server:

Set gobjMIMS = new MIMSXServerIf Not gobjELLIPSE.Initialise Then <error handling>

If Not gobjMIMS.Connect(False) Then <error handling>

Demonstration Script - Module Routine 2

The MIMSX object can be declared using early binding (as in this example) with:

Public gobjMIMS As MIMSXServer

and created using:

Set gobjMIMS = New MIMSXServer

The MIMSX object could also have been instantiated using late binding with:

Public gobjMIMS as OLEObjectSet gobjMIMS = CreateObject("MIMSX.MIMSXServer.1")


Subroutine MIMS_Disconnect shows code to disconnect from ELLIPSE Server:

gobjMIMS.Disconnect

Subroutine MIMS_RetrieveAccounts calls routines to connect, display search form (which builds and sends the request), and display results of search.


Subroutine DisplayAccountDetails shows code to display results of search:

For Each Request In AccountReply.Requests For Each Instance In Request.Instances Cells(i + OutputRow, OutputCol).Value = Trim$(Instance.Fields("TransactionId").Value)

o Loops through all requests in replyo Loops through all instances in requesto Processes fields in instance and extracts value


Notes

Demonstration Script - Form Routine 1

In Project Explorer, open Forms for mimsx.xls and double-click frmExcelSearch.

Press F7 to view associated code. Subroutine btnOK_Click shows code to build and send a

ELLIPSE request using the data provided by the user. It sets up:

o Blocko Requesto Instanceo Fields


Create a new block:Set Block = gobjMIMS.Blocks.New("Accounts")

Create a new request:Block.Requests.New ("Request")

Create a new instance:Block.Requests("Request").Instances.New ("Instance")


Fill out the request information:

Block.Requests("Request").AddFieldNameValue "_Service", "ACCOUNTINGENTRY.Retrieve”

Block.Requests("Request").AddFieldNameValue "_ReplyList","TransactionId,ProcessDate, DstrctCode,AccountCode,AccountCodeDesc, TranType,TranAmount,Description”

Add fields:

If Not Block.Requests("Request"). Instances("Instance").AddFieldNameValue( "FromCreationDate", MIMSFromDate) Then error...


Notes Demonstration Script - Form Routine 4

Send the block to the server for processing :

Set AccountReply = Block.Send

Tidy up allocated resources:

gobjMIMS.Blocks.Remove ("Accounts")

Call subroutine to process reply:

DisplayAccountDetails


SetAccountData subroutine processes reply.

o Check if reply is empty:

If aobjReply.Requests(1).Instances.Count = 0 …

o Check for errors in reply:

If Reply.FindFirstError(nReq, nInst) Then …

o Error text in

Reply.Requests(nReq).Instances(nInst)._Fields("_ErrorTexts")

OR

Reply.Requests(nReq).Fields("_ErrorTexts")

o – Make reply available for display:

Set mdlMacro.AccountReply = Reply


Errors may also be accessed via the object using ErrorItem declared as MIMSError.

Check for errors in reply:

For Each MyErr In gobjMIMS.Errors If MyErr.ErrorType = ERROR_MIMS ' There was an Ellipse Error, display error messageElse ' A non Ellipse error occurred, display a generic error

Properties of MIMSError include:

o ErrorMessage

o ErrorField (ELLIPSE server errors only)

o ErrorCode (ELLIPSE server errors only)


Notes

Practice – Modify an Excel Application

Scenario: Modify an existing Excel application.

EnCore Path:

Practice Script:

Correct error handling when no records returned

Use Errors collection to display errors – distinguish between Ellipse errors and other errors

Add code for a silent login


Notes Topic 5 – Developing with Microsoft Excel and Word

Concepts:

Microsoft Excel and Microsoft Word are easy applications to format. These programs can be used as reports, such as a list of work order tasks parametrised by raised dates, work order status, etc.


Notes

Practice – Adding MIMSX Macros to an Excel Spreadsheet

Scenario:Using Visual Basic scripting, you will create ELLIPSEX Macros in an Excel Document.

EnCore Path:

Practice Script:

1. Run Microsoft Excel and save an empty document as EquipRetrieve.xls in your My Documents folder.

2. Select Tools>Macro>Visual Basic Editor.

3. In Visual Basic, select Tools>References and check Mincom – MIMS Business Object Services Library. This provides access to the Mincom-defined types, etc.

4. In the Tools>References dialog make sure that the Mincom – MIMS Run-time Repository Server Library is selected. This reference provides access to the Ellipse Repoistory.

5. Press control-R if the Project Explorer is not visible.

6. In Project Explorer, right-click project and select Insert Module.

7. Press F4 if the properties window is not visible. Ensure the new Module1 module is selected and change the (Name) property to EquipModule.

8. We need to declare some global variables to hold the MIMSX server object and a flag to indicate whether we are connected to the MIMSX server.

In the General Declarations area of EquipModule, add the following:

' Ellipse Connection variables Public gobjMIMS As MIMSXServerPublic gbConnected As BooleanPublic CurrentRow As Integer ' current row for output


Notes A subroutine is required which will be executed from the menu of the Word document, and which will connect us to the MIMSX server (ie. log us in to the back end). It needs to create the connection object, initialise it, and connect to it.

Select the Insert Procedure menu option and add a EllipseConnect public subroutine. It will contain the following code:

'**************************************************************'Sub: EllipseConnect'Paramateres: none'Description: Allows a connection to MIMS'**************************************************************Sub EllipseConnect() ' Check if we are already connected. If gbConnected Then MsgBox "Already Connected." Exit Sub End If ' Create the MIMSXObject Set gobjMIMS = New MIMSXServer ' Initialise the MIMSX object. If Not gobjMIMS.Initialise Then MsgBox "Unable to initialise the COM Server" gbConnected = False Exit Sub End If ' Connect the MIMSX object. (False) normal login (true) silent If Not gobjMIMS.Connect(False) Then MsgBox "Unable to connect to the COM Server" gbConnected = False Exit Sub End If gbConnected = TrueEnd Sub

9. Another subroutine is required which will be executed from the menu of the Word document, and which will disconnect us from the MIMSX server.

Select the Insert Procedure menu option and add a EllipseDisconnect public subroutine. It will contain the following code:

'***************************************************************'Sub: EllipseDisconnect'Paramateres: none'Description: Allows a disconnection from MIMS'***************************************************************Sub EllipseDisconnect() ' Disconnect from the MIMS Server If gbConnected Then gobjMIMS.Disconnect gbConnected = False Set gobjMIMS = Nothing Else MsgBox "Not currently connected." End IfEnd Sub


Notes

10. A third subroutine is required which will be executed from the menu of the Excel spreadsheet, and which will prompt for a equipment reference, build the request, then send the command to the back end through the MIMSX server to retrieve all Equipment References starting from the value inputed by the user.

This requires us to create a block to hold the requests, create a request within the block, and create an instance within the request. We specify the service (class name and operation name) and list of fields to be returned, then add the names and values of each input parameter to the first (and only) instance within the request. Finally, we must repetitively send the block with the request to the back end until no more data to retrieve is left, store the reply, check for errors and display the data.

Select the Insert Procedure menu option and add a EllipseRetrieveEquipRefs public subroutine. It will contain the following code:

'**************************************************************'Sub: EllipseRetrieveEquipRefs'Paramateres: none'Description: Retrieve equipment references starting with param value'*************************************************************Sub EllipseRetrieveEquipRefs() Dim CurrentRow As Integer Dim EquipBlock As MIMSBlock Dim EquipRequest As MIMSRequest Dim EquipReply As MIMSReply Dim EquipInst As MIMSInstance Dim ErrorItem As MIMSError If Not gbConnected Then EllipseConnect End If Cells(1, 1).Value = "" 'Clean columns 2 and 3 CurrentRow = 3 Do While True If Trim(Cells(CurrentRow, 1).Value) = "" Then Exit Do End If Cells(CurrentRow, 1).Value = "" Cells(CurrentRow, 2).Value = "" Cells(CurrentRow, 3).Value = "" CurrentRow = CurrentRow + 1 Loop CurrentRow = 3 EqStartWith = InputBox("Equipment Ref. From: ", "Equipment Search") ' Create a new block (network message) to send to the server Set EquipBlock = gobjMIMS.Blocks.New("B1") ' Create a request for information within the network message Set EquipRequest = EquipBlock.Requests.New("R1") ' Specify the back end class and method I want to execute EquipRequest.AddFieldNameValue "_Service", "EQUIPMENT.Retrieve" ' Specify the fields I want back from the employee EquipRequest.AddFieldNameValue "_ReplyList", _ "EquipRef,EquipDesc,EquipLocation"


Notes

' Create an instance of the request Set EquipInst = EquipRequest.Instances.New("I1") EquipInst.AddFieldNameValue "EquipRefSearchMethod", "W" EquipInst.AddFieldNameValue "EquipRef", Trim$(EqStartWith) On Error GoTo ErrorHandler Do While True ' Send the block to the server for processing Set EquipReply = EquipBlock.Send

If Not (EquipReply Is Nothing) Then DisplayEquipRefs EquipReply, CurrentRow End If ' if no restart information then exit the loop If Not EquipReply.Requests(1).IsRestart Then Exit Do End If ' add restart field, or set its value if already added If EquipRequest.IsRestart Then EquipRequest.Fields.Item("_Restart").Value = _ EquipReply.Requests(1).Fields.Item("_Restart").Value Else EquipRequest.AddFieldNameValue "_Restart", _ EquipReply.Requests(1).Fields.Item("_Restart").Value End If Loop ' go back for next lot of 20 Equipments ' free the memory for the request list gobjMIMS.Blocks.Remove (1)

MsgBox CurrentRow - 3 & " rows retrieved." 'quit here so we don't fall through into the error handling code Exit Sub ErrorHandler: DisplayErrorEnd Sub

Select the Insert Procedure menu option and add a DisplayEquipRefs subroutine which will display all the instances returned by the Equipment.Retrieve service. It will contain the following code:

'**************************************************************'Sub: DisplayEquipRefs'Paramaters: none'Description: Equipment Refs Display Routine'**************************************************************Public Sub DisplayEquipRefs(EquipReply As MIMSReply, CurrentRow As Integer) Dim EquipInst As MIMSInstance

With EquipReply.Requests(1) For Each EquipInst In .Instances Cells(CurrentRow, 1).Value = _ Trim$(EquipInst.Fields("EquipRef").Value) Cells(CurrentRow, 2).Value = _ Trim$(EquipInst.Fields("EquipDesc").Value) Cells(CurrentRow, 3).Value = _ Trim$(EquipInst.Fields("EquipLocation").Value)

CurrentRow = CurrentRow + 1


Notes

Next End WithEnd SubEnd Sub

11. The EllipseRetrieveEquipRefs subroutine needs an error handling routine. This routine checks for errors associated with the object and displays each one it finds. If the errors are from the back end the associated field and code are also displayed. If the error was not associated with an object, the routine simply displays the description of the error.

Select the Insert Procedure menu option and add a DisplayError function. It will contain the following code:

'**************************************************************'Sub: DisplayError'Paramaters: none'Description: Displays Error at cell 1, 1'**************************************************************Public Sub DisplayError() Dim ErrorItem As MIMSError For Each ErrorItem In gobjMIMS.Errors Select Case ErrorItem.ErrorType Case ERROR_MIMS Cells(1, 1).Value = "Error: - " & ErrorItem.ErrorMessage & _ " Field: - " & ErrorItem.ErrorField & _ " Code: - " & ErrorItem.ErrorCode Case ERROR_GENERIC Cells(1, 1).Value = ErrorItem.ErrorMessage End Select Next If Err > 0 Then Cells(1, 1).Value = Err.Description End IfEnd Sub

Next we need to execute a routine to add an Ellipse menu to Word when we open the document, with the Ellipse menu containing the commands to connect, disconnect, and retrieve the requested equipments.

In Project Explorer, expand the mimsx project, expand the Microsoft Word Objects node and double-click ThisWorkBook. The code window will appear.

12. In the left dropdown combo box, select Document and in the right combo box, select Open. A skeleton for the Document_Open subroutine will be displayed. Add the following code:


Notes '*******************************************************************************'Sub: Workbook_Open'Parameters: none'Description: Add a pull down menu to Microsoft Excel when this file is opened'*******************************************************************************Private Sub Workbook_Open() Dim cstmEllipse As CommandBarControl Dim cstmEllipseConnect As CommandBarControl Dim cstmEllipseDisconnect As CommandBarControl Dim cstmEllipseRetrieveEquipRefs As CommandBarControl Dim cbr As CommandBars Dim menu As CommandBarControl ' Make sure Ellipse is not already in the command bars. For Each menu In Application.CommandBars("Worksheet Menu Bar").Controls If menu.Caption = "&Ellipse" Then ' It is... we exit. Exit Sub End If Next ' Create a new Menu called "Ellipse" Set cstmEllipse = Application.CommandBars _ ("Worksheet Menu Bar").Controls.Add(Type:=msoControlPopup, Before:=9) cstmEllipse.Caption = "&Ellipse" ' Add a "Ellipse_Connect" option to the menu Set cstmEllipseConnect = Application.CommandBars _ ("Worksheet Menu Bar").Controls("Ellipse").Controls.Add(ID:=1) cstmEllipseConnect.Caption = "&Connect to Ellipse" ' Add a "Ellipse_Disconnect" option to the menu Set cstmEllipseDisconnect = Application.CommandBars _ ("Worksheet Menu Bar").Controls("Ellipse").Controls.Add(ID:=1) cstmEllipseDisconnect.Caption = "&Disconnect from Ellipse" ' Add a "Ellipse_RetrieveEquipRefs" option to the menu Set cstmEllipseRetrieveEquipRefs = Application.CommandBars _ ("Worksheet Menu Bar").Controls("Ellipse").Controls.Add(ID:=1) cstmEllipseRetrieveEquipRefs.Caption = "&Retrieve Equipment Refs" ' If the Ellipse_Connect Option is selected run the Ellipse_Connect sub With cstmEllipseConnect .OnAction = "EllipseConnect" End With ' If the Ellipse_Disconnect Option is selected run Ellipse_Disconnect sub With cstmEllipseDisconnect .OnAction = "EllipseDisconnect" End With ' If the Ellipse_RetrieveEquipRefs" option is selected, run ' EllipseRetrieveEquipRefs sub With cstmEllipseRetrieveEquipRefs .OnAction = "EllipseRetrieveEquipRefs" End WithEnd Sub

In the left dropdown combo box, select Document and in the right combo box, select Close. A skeleton for the Document_Close subroutine will be displayed. Add the following code:


Notes

'******************************************************' Function: Workbook_BeforeClose' Params: None' Desc: Removes the Ellipse menu after closing the document'******************************************************Private Sub Workbook_BeforeClose_Close(Cancel As Boolean) CommandBars.ActiveMenuBar.Controls("&Ellipse").DeleteEnd Sub

13. You are ready to test your code. Save the document, then close and re-open it. An ELLIPSE menu should appear (after we enable macros in the document). Select the ELLIPSE Retrieve Equipment Refs option. You should be prompted to log in. Following this, you will be prompted to enter an equipment reference (try with a letter as “W”). The working spreadsheet sould be filled with all equipment references starting with “W”.


Notes Practice – Create Macros in a Word Document

Scenario: Use Visual Basic scripting to create macros in a Word document.

EnCore Path:

Practice Script:

Develop a macro to retrieve employee positions from Ellipse.

Add a second request of the same block that fetches the position description of the connected user (use the Position class) and display it on the Word document.


Notes

RevTopic 6 – Developing with the MSO interface


Notes Ellipse Screen Object Model Summary


MIMSX Server

MIMSX Server

InitialiseConnectDisconnectGetParameterSetParamater

Screen

Screen

IdleExecuteMSO

MSO

MSO

MessageErrorNameActiveField

IsCommand

Command

Command

NameExecute

Field

Field

NameValueLength

Commands

Commands

Fields

Fields

Count Count

Notes

Concepts:

A large number of Business Objects have been made available as Classes for use with the Mincom Connector Business Object Services library (MIMSX). However, there are still a large number of fields that will not be found as attributes of any class, but which appear on various MSO screens within Ellipse.

New versions of the Mincom Connector Business Object Services library (MIMSX) have the functionality to be able to access MSO screens.

The MSO Interface

Access to MSO screens is built into the latest version of the MIMSX library. All access is via the Screens property of the MIMSX server object.

To use the MSO interface it is first necessary to open an MSO screen. Call the ExecuteMSO method to open an MSO screen.

It is possible to enter data into the screen through the screen field’s object. This is done by emulating data entry into the screen fields as if these values were being physically typed in. To set the value of a screen field use the Fields object in the following way: gobjMIMS.Screen.MSO.Fields(“field”) = value. To retrieve the value from an screen field use the Fields object in the following way: variable = gobjMIMS.Screen.MSO.Fields(“field”).

The easiest way of determining the screen field names is through MSQ000. In the options menu of MSQ000 turn on the “Use Hover Help to Display Field Names” option. This option will display the field name when the mouse pointer is hovered over the field while using MSQ000.

Once all the required information has been extracted and/or entered into the screen, it is then possible to execute a command on the screen. Some of the possible commands available are OK, Cancel, Home, Confirm etc. To execute a command use the Execute method from the Command interface.

In some situations, you may not know whether a given command is valid for a particular screen. For example, depending on the number of records returned, the Next Page command may or may not exist. Use the IsCommand method to check for this. Note that "OK", "Home", "Revert", "Cancel", and "Help" are always valid commands.

After an Execute has been completed it is necessary to make sure that no errors occurred. To check for errors use the MSO.Error property. This property contains the error code and error description. If an error has not occurred, this property will be empty.

Other Notes

It should be noticeable that the time required to access information from the MSO screens is considerably longer than that required to access the same information using a single Retrieve from the business object.

You should always close the MSO screen when you have finished with it, so that other screens can be used, since MIMSX can only have one screen open at any time. The Idle property can be checked to ensure that MIMSX is ready to open a new screen.


Notes Some menus (particularly in HR) contain chains of screens. For example, the addition of a new employee involves filling out several screens of information. These chains may be initiated using the ExecuteChain command rather than the ExecuteMSO command.


Notes

Demonstration – Walk through example

Scenario: Table codes upload using Excel.

EnCore Path:

Demonstration Script – Connect to Server:

Double-click mimsx_tables.xls to load sample spreadsheet - click Enable Macros

Select Get Leave Taken from the MIMS menu Enter login details and click OK Results of search inserted into spreadsheet Select MIMS Disconnect to close server

Demonstration Script – Routine 1 & 2

Open the Project Explorer (Visual Basic Editor) Review the MIMS_Connect and MIMS_Disconnect sub routines.

Notice how the connect and disconnect routines are the same as previous examples

Demonstration Script – Routine 3

Open the screen that will be used

gobjMIMS.Screen.ExecuteMSO ("MSOXXX")

Enter data into the required Ellipse data fields

gobjMIMS.Screen.MSO.Fields("field") = “data”

Execute screen command

gobjMIMS.Screen.MSO.Commands("command").Execute

List all available screen commands

For i = 1 To gobjMIMS.Screen.MSO.Commands.Count

MsgBox "Availabale command: " & _

gobjMIMS.Screen.MSO.Commands.Item(i).Name

Next

Check for errors

error = Trim(gobjMIMS.Screen.MSO.Error)

Demonstration Script – Routine 4

Extract data from the Ellipse data fields on the screen

Cells(CurrentRow, OutputCol).Value = _

gobjMIMS.Screen.MSO.Fields("field")


Notes Practice – Creating an Excel Application

Create a new spreadsheet called mso010load.xls.

Add two sub routines, including code, to connect and disconnect to the Ellipse server.

Create a new sub routine to upload to Ellipse all table codes of the spreadsheet and displaying any validating error.


Notes

Review of MSO Interface


Notes Topic 7 – Java Middleware

Concepts:

The Mincom Connector Java Middleware is a lightweight implementation of the Ellipse Middleware.

Characteristics:

Has the same object hierarchy as MIMSX, the COM implementation of the Middleware.

Uses the same Network message hierarchy as MIMSX. (i.e. Blocks, Requests and Instances, etc.)

Pure Java code. Does not rely on MIMSX. Uses sockets to connect via TPNET. Uses Jolt to connect via TUXEDO or native tuxedo calls if Java

Runtime is installed. Uses CTG to connect to CICS Implements a screen interface similar to the MUI COM

Interface. (Windows only) Runs on any platform that supports Java technology (Unix,

Windows, Linux, etc.)

Required Software:

An Operating System that supports Java technology.(Unix, Windows, Linux, etc.)

Java 2 SDK/JRE, Standard Edition, v1.2.2 or higher Java Middleware API


Notes

Ellipse 5.2 or higher (at present no MSO support for Ellipse 5.2.3).

A text editor (Notepad, JBuilder, etc.)


Notes

MimsSessionFactory:

Only one object of the MimsSessionFactory class can be instantiated in each JVM for speed of execution.

There are two public methods: getMimsSessionFactory() to get this object getMimsSession() to return an instance of a TpNetSession,

TuxSession or CICSSession object

IMimsSession:

IMimsSession is the Interface to a MIMS Session. The following methods must be implemented to run this interface:

connect() disconnect() login() executeMSO() executeChain() etc.


Notes

MimsSession:

MimsSession is the base class for a Mims Session and implements the MIMS Session Interface.

The methods for connect(), request(), and disconnect() must be implemented by the inheriting class, and the method for login() is fully implemented here calling request and connect as required.

The TpNet implementation can only talk to servers supporting TpNet version 7 or later.

TpNetSession:

TpNetSession Provides a Mincom TP session (TpNet). It extends the MimsSession and implements the IMimsSession Interface.

The methods for connect(), request(), and disconnect() are fully implemented and the method for login() is implemented by the base MimsSession Class.

TuxSession

TuxSession is the Tuxedo/Jolt MIMS Session. It extends the MimsSession and implements the IMimsSession Interface.


CICSSession

CICSSession is the CTG MIMS Session. It extends the MimsSession and implements the IMimsSession Interface.


TpNetMsgBuf

TpNetMsgBuf implements a Mincom TP, TpNet Header. Typically this is 3 int's, but could be just one byte when used as an Ack or Nak.

Methods:

getFlags() getMessageType() setMessageType() length() toMIMSBlob()


Notes

Concepts:

The implementation of the java middleware classes closely follows the structure of a Network message:

The MIMSBlock class is used to define both the Request List and the Reply List.

The MIMSRequest class is used to define the individual Request and Reply within the Request List and Reply List.

The MIMSInstance class is used to define the Reply Instance and the Request Instance

The MIMSFields collection is used to define the fields/ attributes/or data within the Request, Request Instance, Reply or Reply Instance.


Notes

Creating a Session:

When writing an application which communicates with a suite of server applications on a host machine, it is necessary to create a session object.

Information stored:

Type of connection used to establish the communication link between the server and web application

The host machine login information associated with the user The Ellipse system login information associated with the user

The session component is an IMimsSesssion object, which can be initialized by using the getMimsSession method of the MimsSessionFactory class.

The getMimsSession method, will create either a new CICS session, TpNet session or a new Tuxedo session, depending upon the string passed. If 'TpNet' is passed, a TpNet session will be created, otherwise a new Tuxedo session will be created. If any MSO screens are to be displayed via the Session, the getMimsSession method, must also pass in the location of the Screen Buffer Library.

Connecting via TpNet:

// validate user's session info

IMimsSession mySession = null;

MimsSessionFactory sessionFactory =

MimsSessionFactory.getMimsSessionFactory();

mySession = sessionFactory.getMimsSession("TpNet",

"C:\\MIMSJ\\BUFLIB");

Connecting via Tuxedo:





mySession = sessionFactory.getMimsSession("Tux");

Connecting via CICS:





mySession = sessionFactory.getMimsSession("Cics");


Notes Confirm the Connection:

// Determine whether the session is connected,

// and if not, then connect

if (!mySession.isConnected()) {

try {

mySession.connect("keg",8834, "UserName", "");

mySession.login("NINES","","ACME","AUS01");

} catch (InterruptedIOException i){

System.out.println(

"InterruptedIOException caught i = " +

i.getMessage());

} catch (IOException e) {

System.out.println("IOException caught e = " +

e.getMessage());

} catch (ServerException e) {

System.out.println("ServerException caught e = " +

e.getMessage() + e.block +

e.block.makeCbrBuffer(3));

} catch (MwareException e) {

System.out.println("MwareException caught e = " +

e.getMessage() + e.block);

} catch (CBRException e) {

System.out.println("CBRException caught e=" +

e.getMessage()); }

}


Notes

Concepts:

The Request List is the mechanism by which a request for some work to be performed on the database is carried to the server application.

Building a Request List Step-by-Step:

Step 1: Create a session object, and connect it to the host server machine

Step 2: Construct a Request List

This will detail the work to be carried out on the host server machine.

The Request List is the container for all the required requests and is defined by the MIMSBlock Class. A Request List can be created by using the MIMSBlock Constructor.


Notes Step 3: Add requests to the Request List

A number of requests can be added to the Request List. Each individual block of work to be performed, is defined within a Request. A blank Request within the Request List needs to be created. This can be done by first retrieving the requests for the new RequestList using the 'getRequests' method of the MIMSBlock class (this returns a MIMSRequests object containing all the requests belonging to the MIMSBlock). The 'create' method of the MIMSRequests class is then used to add a new blank Request. It is also possible to create a new Request, and then add the Request to the Request List. This is achieved by using the 'add' method of the MIMSRequests class, passing the pre-built MIMSRequest object, as a parameter to the method.

Step 4: Add new fields to the requests

Retrieve the fields for the new Request using ‘getFields’ method of the MIMSRequest.

(MIMSFields). Use the create method of MIMSFields to to add new name/value pairs to the MIMSFields object belonging to the MIMSRequest. (myEmpReq). Request Control information, can also be added at the Request Level.

One piece of Request Control information that is always required, is the name of the work that is to be carried out (or the service that is being requested). This is done by adding a name value pair of '_Service.myServiceName' to the Request. For example: EMPLOYEE.Fetch.

It is also usually necessary to send a list of the required outputs with the request. This tells the Server application what data is to be returned in the reply. This list of outputs is specified by adding a '_ReplyList' name/value pair to the Request. In the example below, we are requesting that some basic contact information about an Employee be returned.

Step 5: Add Request Instances

First, a Request Instance needs to be created. Request Instances are used to define which object in the database the Request is to be performed on.

A new instance can be added by first retrieving the instances for the new Request using the 'instances' field of the MIMSRequest class. This returns a MIMSInstances object containing all the instances belonging to the MIMSRequest).

The create method of the MIMSInstances class can then be used to add a new instance to the MIMSInstances object belonging to the MIMSRequest (myEmpReq).

It is also possible to create a new MIMSInstance object, and then add it to the Instance collection of the Request. This is achieved by using the 'add' method of the MIMSInstances class, passing the pre-built MIMSInstance object, as a parameter to the method.


Notes

Second, data is added to the instance as name/values pairs in much the same way the Request Control data is added to the Request.

Using the create method of the MIMSFields class, except that here the MIMSFields collection, is that belonging to the request Instance.

If desired the fields can be added by first creating the MIMSField object, and then using the add method of the MIMSFields class to add the new field to the Instance.

Once a request has been added to the Request List, a second request can now be added in exactly the same way.

Step 6: Send the Request List to the server.

The send of the Request is handled by the session component. This is accomplished by calling the 'request' method of the IMimsSession class, passing the MIMSBlock object which contains the Request List. The session component will wait until it receives a reply from the host server before continuing processing. The 'request' method returns a MIMSBlock object which contains the Reply List.


Notes Step 1: Create a session object, and connect it to the host server machine.

// validate user's session infoIMimsSession mySession = null;MimsSessionFactory sessionFactory = MimsSessionFactory.getMimsSessionFactory();mySession = sessionFactory.getMimsSession("TpNet", "D:\\jdk1.4.2\\mims\\BufLib");

Step 2: Construct a Request List.

if (mySession.isConnected()) { // Create a new Request List MIMSBlock myBlock = new MIMSBlock();

Step 3: Add requests to the request list.

// Create a new request to be added to the// Request listMIMSRequest myEqReq = null;myEqReq = myBlock.getRequests().create();

Step 4: Add new fields to the Requests.

String serviceName = "EQUIPMENT.Retrieve";String replyList = "EquipRef,EquipDesc,EquipLocation";// Add the required service name to the requestmyEqReq = myBlock.getRequests().create();myEqReq.getFields().create(myBlock.SERVICE, serviceName);myEqReq.getFields().create(myBlock.REPLYLIST, replyList);

Step 5: Add Request Instances.

//Add a new Instance with two fields to the RequestMIMSInstance myInstance = myEqReq.getInstances().create();myInstance.getFields().create("EquipRefSearchMethod", "W");MIMSField secondField = new MIMSField("EquipRef", "C");myInstance.getFields().add(secondField);

Step 6: Send the Request List to the server.

Try { MIMSBlock myReply = mySession.request(myBlock); } catch (ServerException e) { System.out.println("ServerException encountered in sendRequest: " + e.getMessage()); } catch (CBRException e) { System.out.println("CBRException encountered in sendRequest: " + e.getMessage()); } catch (IOException e) { System.out.println("IOException encountered in sendRequest: " + e.getMessage()); }}


Notes

Getting the Reply List:

When the Request List gets sent to the host server using the 'request' method of the MimsSession class, the result is a MIMSBlock object containing the Reply List. Therefore, the request method both sends the Request list and receives the Reply List.

The returned Reply List has the same structure as the Request List and contains the same number of replies as requests in the Request List. The Reply is matched to the original Request by its order. For example, the 3rd Reply in the Reply List will be the reply to the 3rd Request in the Request List.

Getting the Reply Data:

The Restart Data and Error Fields are returned at the Reply level, which then needs to be extracted.

The Restart data is returned from the host Server application when a multi-instance reply type operation is requested by the client application. The restart information is returned when not all the reply instances which satisfied the original request, could be returned. The _Restart name/value pair contains key information about the next record in the database which satisfies the original request, and is contained in the MIMSFields collection associated with the Reply. Access the appropriate reply in the Reply List to retrieve its restart data.

First, the getRequests method of the MIMSBlock will return the MIMSRequests collection associated with the Reply List. The item method of the MIMSRequests object can then be used to get access to the first MIMSRequest object (which is the 0th indexed MIMSRequest object in the MIMSRequests collection of the ReplyList).

The MIMSFields collection is then accessed by using the getFields


Notes method of the MIMSRequest, and from there the required Restart value can be obtained by using the item method of the MIMSFields collection, passing in the name of the field to be accessed. Last, the getValue method can be used to obtain the Restart data.

Getting the Reply Instance Data:

The data at the Reply Instance can be extracted in the same way as the data at the Reply level. Determine the Reply and Reply Instance that the data is to be extracted from.

Obtain the MIMSFields collection associated with the Reply instance.

Multi Instance Replies:

Some requests can result in a multi instance reply. These requests are usually a request for a 'Retrieve' operation, which are designed to get all the records which satisfy some search criteria. In these situations, each separate record which satisfies the search criteria is included in the Reply as one instance. Getting the information out of the reply, is a matter of cycling through the MIMSInstances collection for the Reply, and for each instance found, extracting the required data from the MIMSFields collection.


Notes

Processing the Reply Code:

Getting the Reply List

if (mySession.isConnected()) { *** build the Request List *** // Create the reply block MIMSBlock myReply = null; try { // Send the Request List to the server, returning // the Reply in the Reply block myReply = mySession.request(myBlock); } catch (ServerException e) { System.out.println( "ServerException caught e=" + e.getMessage()); } catch (CBRException e) { System.out.println("CBRException caught e=" e.getMessage()); }}

Getting the Reply Restart Data

String thisRestart = myReply.getRequests().item(0).getFields() .item(myBlock.RESTART).getValue();

Getting the Reply Instance Data

for (int i = 0; i < myReply.getRequests().count(); i++) { MIMSRequest myReplyReq = myReply.getRequests().item(i); displayFields("Reply Request " + i + ":", myReplyReq.getFields());

for (int j = 0; j < myReplyReq.getInstances().count(); j++) { MIMSFields repFlds = myReplyReq.getInstances().item(j).getFields();

displayFields("Reply Request " + i + ", Instance " + j + ", Row number " + rowNumber++ + ":", repFlds);

}}private static void displayFields (String msg, MIMSFields myFields) { int i; try { System.out.println(""); System.out.println(msg); System.out.print(" "); for (i = 0; i < myFields.count() - 1; i++) { System.out.print(myFields.item(i).getValue() + ", "); } System.out.println(myFields.item(i).getValue()); } catch (CBRException e) { System.out.println("CBRException encountered in displayFields: " + e.getMessage()); }}

Multi Instance Replies with Restart Handle

do { MIMSBlock myReply = mySession.request(myBlock);

for (int i = 0; i < myReply.getRequests().count(); i++) { MIMSRequest myReplyReq = myReply.getRequests().item(i); displayFields("Reply Request " + i + ":", myReplyReq.getFields()); for (int j = 0; j < myReplyReq.getInstances().count(); j++) { MIMSFields repFlds = myReplyReq.getInstances().item(j).getFields(); displayFields("Reply Request " + i + ", Instance " + j + ", Row number " + rowNumber++ + ":", repFlds); } }

if (myReply.getRequests().item(0).isRestart()) // getting restart value from request 0


Notes

restartRecord = myReply.getRequests().item(0).getFields().item(myReply.RESTART). getValue(); else break; myEqReq.getFields().create(myReply.RESTART, restartRecord);} while (true);


Notes

Practice – Java Exercise 1

Scenario:Using a Java, create and send a Request List.

EnCore Path:

Practice Script:

1. Create a Java public class

2. Create a session

3. Create a new request list (block). (MIMSBlock)

4. Create a new request. (MIMSRequest)

5. Add the service request “EMPLOYEE.Fetch” to the newrequest

6. Add the following list of outputs to the request:

– Employee

– EmployeeFormattedName

– EmailAddress

– Title

– TitleDesc

– LastName

– FirstName

– SecondName

– ThirdName

– PreferredName

– PhotoPathname

7. Create a new request instance to the request, adding the input field “Employee“ with value “NINES”

8. Create a reply block (MIMSBlock)

9. Send the request list to the server, returning the Replyin the Reply block

10. Get the first reply from the Reply Block (MIMSRequest)

11. Extract the output values from the reply and displaythem on the screen

12. Disconnect from the server


Notes Practice – Java Exercise 2

Scenario:

Using Java, retrieve information from Ellipse.

EnCore Path:

Practice Script:

1. Create a Java public class 2. Create a Session 3. Execute “MSO621”4. On “MSM621A” screen:

a. Set “OPTION1I” field to “1”b. Set “WORK_ORDER1I” field to “2001”

2. Execute the “OK” command on “MSM621A” screen3. Retrieve the following fields from the “MSM621D” and

display them using “System.out.println” to the consoleWORK_ORDER4I, L_WO_STATUS_M4I, JOB_DESC4I, EQUIPMENT4I, EQUIP_DESC_A4I, COMP_CODE4I, COMP_CODE_DESC4I, COMP_MOD_CODE4I, ASSIGN_PERSON4I, PERSON_DESC4I, ASSIGN_TO4I, ASSIGN_TO_DESC4I, NO_OF_TASKS4I

4. Disconnect from the server


Notes

Review of Java


Notes Course Summary


Notes

Training EvaluationPlease take a moment to complete the Evaluation form. Your comments help us ensure that we provide great training that meets your needs.Thank You.


Notes

Congratulations on completing the course.Thank you for your participation.


Notes

Appendix A – FAQsMIMS Business Object Services LibraryError TrappingAll errors will cause an OLE Exception to be thrown. In most environments the error message will be displayed automatically, for example in VB the message will be shown with an option to Stop or Debug.The error may be a MIMS Business Object Services Library internal error or an error returned from the Ellipse Server. To obtain more detailed information about the error use the MIMSXServer Errors property. The following code example shows a simple error handler for Visual Basic.This is especially relevant when trapping an error from the Block Send method which will throw an OLE Exception if an error is encountered from the MIMS Server. When examining an error from the MIMS Server it is important to view the error in the context of the Field to which it applies. For example, the error message may contain “Invalid field in reply list” but you need to examine the following code:Sub DisplayErrors(MIMSObj As MIMSXServer) Dim MyErr As MIMSError Dim strMsg As String If MIMSObj.Errors.Count > 0 Then For Each MyErr In MIMSObj.Errors Select Case MyErr.ErrorType Case ERROR_MIMS strMsg = "Message: " & MyErr.ErrorMessage & Chr$(10) strMsg = strMsg & "Field: " & MyErr.ErrorField & Chr$(10) strMsg = strMsg & "Code: " & MyErr.ErrorCode MsgBox strMsg Case ERROR_GENERIC MsgBox "MIMSX Error: " & MyErr.ErrorMessage End Select Next Else MsgBox "VB Error: " & Err.Description End IfEnd SubWhy do I receive security errors on a method?When sending a request to Ellipse Server you may receive a security error relating to a particular business object method. The most common cause of this error is that the case of the request is incorrect. When building a request block the object name for the “_Service” field must be in upper case. The method must be in the same case as shown in the repository. All fields names used in the “_ReplyList” and Instance data must be in the same case as in the repository.Using the ELLIPSE Trace FileThe ELLIPSEAPI (middleware) provides a debugging trace file that may be used to aid with locating errors caused during development. The properties of the trace file may be accessed through right clicking on the ASIA tray Icon (visible after logging into a ELLIPSE application).The following screen shots show three of the property tabs that may be accessed by right clicking on the ELLIPSEAPI tray icon (visible when any ELLIPSE application is active). ELLIPSEAPI TabThe ELLIPSEAPI Tab is used to set the level of debug information for the main Middleware component. By setting the options shown above the debug file will contain dumps of the information sent between the client and server. Viewing this information can help to locate possible sources of problems. For example, ensuring the correct information is actually being sent to the server and the that expected information is actually being received. WDEBUG TabThe WDEBUG Tab is used to setup general debug file information


Notes settings. Debug output may be directed to a file or to a window. The level of detail that is included with each trace message may also be controlled.


Notes

SampleThe following example shows the trace information from a request to a ELLIPSE Server to fetch a particular employee.This extract from the trace file shows a block being sent to a ELLIPSE Server. The _Service.EMPLOYEE.Fetch is visible as the first Request. This request contains two instances fetching employees 521 and 560. A second request is also submitted to fetch a WorkOrder (_Service.WORKORDER.Fetch). Only one instance is requested that is WorkOrder 90.0000 - 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................0010 - 00 00 00 00 00 00 00 00-00 00 00 02 00 78 5f 53 .............x_S0020 - 65 72 76 69 63 65 00 45-4d 50 4c 4f 59 45 45 2e ervice.EMPLOYEE.0030 - 46 65 74 63 68 00 5f 4d-61 78 49 6e 73 74 00 32 Fetch._MaxInst.20040 - 00 5f 53 65 72 76 69 63-65 00 57 4f 52 4b 4f 52 ._Service.WORKOR0050 - 44 45 52 2e 46 65 74 63-68 00 45 6d 70 6c 6f 79 DER.Fetch.Employ0060 - 65 65 00 35 32 31 00 35-36 30 00 57 6f 72 6b 4f ee.521.560.WorkO0070 - 72 64 65 72 00 39 30 00-00 02 00 00 00 9c 00 02 rder.90.........0080 - 00 02 00 9c 00 00 00 01-00 b0 00 00 00 01 00 ba ................0090 - 00 01 00 01 00 c0 00 00-00 01 00 ca 00 0e 00 27 ...............'00a0 - 00 0a 00 08 00 1e 00 01-00 3f 00 0a 00 08 00 36 .........?.....600b0 - 00 03 00 63 00 0a 00 08-00 5a 00 03 00 67 00 5a ...c.....Z...g.Z00c0 - 00 0f 00 4a 00 0a 00 08-00 41 00 02 00 75 00 0a ...J.....A...u..00d0 - 00 09 00 6b ...k


Notes The following shows part of the response from the ELLIPSE Server to the above request block.0000 - 00 07 00 10 1d 98 00 00-00 22 01 00 00 00 01 00 ........."......0010 - 00 00 00 01 01 f7 00 00-00 00 00 02 12 b8 5f 53 .............._S0020 - 65 72 76 69 63 65 00 45-4d 50 4c 4f 59 45 45 2e ervice.EMPLOYEE.0030 - 46 65 74 63 68 00 54 69-74 6c 65 44 65 73 63 00 Fetch.TitleDesc.0040 - 4d 72 00 52 45 53 55 4c-54 00 00 50 72 69 6e 74 Mr.RESULT..Print0050 - 65 72 4e 61 6d 65 00 54-45 4e 43 50 53 32 2d 4c erName.TENCPS2-L0060 - 00 50 72 65 76 69 6f 75-73 4c 61 73 74 4e 61 6d .PreviousLastNam0070 - 65 00 41 4c 42 45 52 54-00 50 6f 73 74 61 6c 53 e.ALBERT.PostalS0080 - 74 61 74 65 00 51 00 50-68 6f 74 6f 50 61 74 68 tate.Q.PhotoPath0090 - 6e 61 6d 65 00 43 3a 5c-00 50 72 69 6e 74 65 72 name.C:\.Printer00a0 - 43 6f 64 65 00 30 33 00-50 72 65 66 65 72 72 65 Code.03.Preferre00b0 - 64 4e 61 6d 65 00 48 4f-4d 45 52 00 52 65 73 6f dName.HOMER.Reso00c0 - 75 72 63 65 43 6c 61 73-73 00 51 00 48 6f 6d 65 urceClass.Q.Home00d0 - 4d 6f 62 69 6c 65 50 68-6f 6e 65 4e 75 6d 62 65 MobilePhoneNumbe00e0 - 72 00 00 57 6f 72 6b 46-61 63 73 69 6d 69 6c 65 r..WorkFacsimile00f0 - 4e 75 6d 62 65 72 00 35-35 35 2d 39 39 38 00 52 Number.555-998.R0100 - 65 73 69 64 65 6e 74 69-61 6c 41 64 64 72 65 73 esidentialAddres0110 - 73 4c 69 6e 65 33 00 55-53 41 00 50 6f 73 74 61 sLine3.USA.Posta0120 - 6c 41 64 64 72 65 73 73-4c 69 6e 65 31 00 31 33 lAddressLine1.130130 - 20 45 76 65 72 67 72 65-65 6e 20 54 65 72 72 61 Evergreen Terra0140 - 63 65 00 43 6f 6d 70 65-74 65 6e 63 79 44 65 73 ce.CompetencyDesThis is the 2nd instance. Note it does not repeat the field names0670 - 00 00 00 00 48 49 4c 4c-2c 53 41 4e 44 52 41 20 ....HILL,SANDRA 0680 - 45 6c 69 7a 61 62 65 74-68 20 4d 53 00 51 55 45 Elizabeth MS.QUE0690 - 45 4e 53 4c 41 4e 44 00-00 4f 56 45 52 42 55 52 ENSLAND..OVERBUR06a0 - 44 45 4e 00 00 00 00 4d-45 4c 42 4f 55 52 4e 45 DEN....MELBOURNE06b0 - 20 50 52 49 4e 54 45 52-20 31 00 30 30 30 30 30 PRINTER 1.0000006c0 - 30 30 35 36 30 00 41 43-4d 20 4f 50 52 20 4d 4e 00560.ACM OPR MN06d0 - 45 20 4f 56 42 00 4e 00-00 4f 50 45 52 41 54 4f E OVB.N..OPERATO06e0 - 52 20 4c 45 56 45 4c 20-33 20 28 4f 2e 42 2e 29 R LEVEL 3 (O.B.)This is the response for the WorkOrder0730 - 00 48 49 4c 4c 00 00 5f-53 65 72 76 69 63 65 00 .HILL.._Service.0740 - 57 4f 52 4b 4f 52 44 45-52 2e 46 65 74 63 68 00 WORKORDER.Fetch.0750 - 50 65 72 6d 69 74 52 65-71 64 53 77 00 00 52 6c PermitReqdSw..Rl0760 - 6f 63 57 6f 00 00 4c 61-62 63 46 69 6e 61 6c 53 ocWo..LabcFinalS0770 - 77 00 00 57 6f 53 74 61-74 75 73 4d 00 43 00 45 w..WoStatusM.C.E0780 - 73 74 4f 74 68 65 72 43-6f 73 74 00 2b 30 2e 30 stOtherCost.+0.00790 - 30 00 52 6c 6f 63 56 61-72 41 63 63 74 44 00 00 0.RlocVarAcctD..07a0 - 41 72 46 69 6e 61 6c 53-77 00 00 43 6f 6d 70 6c ArFinalSw..Compl07b0 - 65 74 65 64 43 6f 64 65-00 41 43 00 45 71 75 69 etedCode.AC.Equi07c0 - 70 52 65 66 00 32 32 33-30 31 00 41 63 74 43 6f pRef.22301.ActCo07d0 - 73 74 49 6e 76 00 00 4c-61 73 74 54 72 61 6e 52 stInv..LastTranR07e0 - 6c 6f 63 00 00 43 6f 6d-70 6c 65 74 69 6f 6e 54 loc..CompletionT07f0 - 65 78 74 45 78 69 73 74-73 00 4e 00 50 63 43 6f extExists.N.PcCo0800 - 6d 70 6c 65 74 65 00 2b-30 2e 30 30 00 43 6f 6d mplete.+0.00.Com


Notes

Excel VBACan I add popup boxes containing all existing data on the ELLIPSE server, for example, all Transaction Types and Account Codes available?No. This requires access to the local pop-up menu data which has not been implemented as part of the MIMS Business Services Library at this time.How do I add a Menu to an Excel Application?In the ThisWorkBook Microsoft Excel Object add the following function and code as shown below:Private Sub Workbook_Open()Dim cstmELLIPSE As CommandBarControlDim cstmELLIPSEConnect As CommandBarControlDim menu As CommandBarControl‘ See if the ELLIPSE menu already exists. If it does don’t add another one.For Each menu In Application.CommandBars("Worksheet Menu Bar").Controls If menu.Caption = "&ELLIPSE" Then Exit Sub End IfNext' Create a new Menu called "ELLIPSE"Set cstmELLIPSE = Application.CommandBars("Worksheet Menu _Bar").Controls.Add(Type=msoControlPopup, Before=9)cstmELLIPSE.Caption = "&ELLIPSE"' Add a "ELLIPSE_Connect" option to the menuSet cstmELLIPSEConnect = Application.CommandBars("Worksheet Menu _Bar").Controls("ELLIPSE").Controls.Add(Id=1)cstmELLIPSEConnect.Caption = "&ELLIPSE Connect"' If the ELLIPSE_Connect Option is selected run the ELLIPSE_Connect macroWith cstmELLIPSEConnect .OnAction = "ELLIPSE_Connect"End WithEnd Sub


Notes Microsoft Project 98 VBAHow do I add a Menu to a Project Application?In a module add the following function and code similar to that stated below:Sub Auto_Open()Dim cstmELLIPSE As CommandBarControlDim cstmELLIPSEConnect As CommandBarControlDim menu As CommandBarControl' See if the ELLIPSE menu already exists. If it does don’t add another' oneFor Each menu In Application.CommandBars.ActiveMenuBar.Controls If menu.Caption = "&ELLIPSE" Then Exit Sub End IfNext' Create a new Menu called "ELLIPSE"Set cstmELLIPSE = _ Application.CommandBars.ActiveMenuBar.Controls.Add(Type=msoControlPopup, Before=9)cstmELLIPSE.Caption = "&ELLIPSE"' Add a "ELLIPSE_Connect" option to the menuSet cstmELLIPSEConnect = _Application.CommandBars.ActiveMenuBar.Controls("ELLIPSE").Controls.Add(ID=1)cstmELLIPSEConnect.Caption = "&ELLIPSE Connect"' If the ELLIPSE_Connect Option is selected run the ELLIPSE_Connect macroWith cstmELLIPSEConnect.OnAction = "ELLIPSE_Connect"End WithEnd SubHow do I transfer the ELLIPSE Server information into Microsoft Project?You must use the SetTaskField method of Microsoft Project to update data for a given task. To add a new task use the Tasks.Add method of the appropriate Project document.Set tsk = ActiveProject.Tasks.Add(Trim$(Instance.Fields("WorkOrder")))SetTaskField Field="Access Field Name Here", _Value = Instance.Fields("ELLIPSE Server Field Name Here"), TaskID=tsk.ID


Notes

HTML and VBScriptI receive script errors when running the sampleEnsure that you have the latest VBScript engine. This is especially relevant if you are running Internet Explorer 3. This engine can be obtained from the Microsoft web site at http://www.mincom.com.


http://www.mincom.com/

Notes Appendix B – Additional ExercisesThis section contains additional exercises.


Notes

Practice – Employee LeaveScenario:In this exercise you will modify an Excel spreadsheet to retrieve “Employee Leave Taken” summary information. You will be adding additional code to retrieve this information from an MSO screen.Access to MSO screens is built into the latest version of the MIMSX library. All access is via the Screens property of the MIMSX server object. You will use this facility to modify the code so that it retrieves the Employee Leave Taken information.EnCore Path:Double-click the mimsx_employee_leave.xls file to open it with Microsoft Excel. When prompted to enable the macros, click the Enable Macros button.

Select Tools>Macro>Visual Basic Editor from the menu bar, or press ALT+F11, to open the VB Editor.

Select MIMS_GetLeaveTaken from the procedures drop down on the upper right hand corner of your VB editor screen. This is the procedure you will be coding in this exercise.

Practice Script:

1. Declare local variables.

Dim CurrentRow As Integer ' current row for output

Dim CurrentLine As Integer ' current screen line

Dim Employee As String ' employee id entered (eg. 564)

Dim msg As String ' error messages

2. Prompt the user to enter a valid employee ID and convert it to uppercase.(Note: Ellipse only recognizes employee IDs in uppercase letters.)

Employee = InputBox("Enter a valid payroll employee id:", _

"Leave Taken for Employee")

If Employee = "" Then Exit Sub

Employee = UCase$(Left$(Employee, 10))


Notes 3. Check to see if you are connected to Ellipse, if not execute the

ELLIPSE_Connect procedure to connect. Set the starting row to the constant, OutputRow, which is row number 2:

If Not gbConnected Then ELLIPSE_ConnectEnd If CurrentRow = OutputRow

4. Launch MSO887 (MSO887 contains employee leave information).

gobjMIMS.Screen.ExecuteMSO ("MSO887")

5. Fetch employee leave taken details for the employee, by entering the employee id in the Next Employee field on the screen and clicking OK. This is done by emulating the entry of data into screen fields, as if these values were being physically typed in by an active user.

To obtain the names of the fields on the screen, use MSQ000 hover functionality. Once the mouse is over a field, the field name will appear in a tool tip.

6. Set the Next Employee field, as per the above input field, to the value retrieved from the Employee variable. (Note: the field names must use underscores, exactly as they appear in the msm887a.unx file.)

gobjMIMS.Screen.MSO.Fields("NEXT_EMP1I") = Employee

7. To simulate clicking on the OK button, execute the OK command:

gobjMIMS.Screen.MSO.Commands("OK").Execute


Notes

8. Check to see if there are any errors as a result of executing the OK button, such as employee ID not being on file. If there are none, then continue to retrieve and display all the leave taken information as long as there is a Next Screen command available. Utilize the DisplayDetails procedure already coded to display the data retrieved in the appropriate rows.

' check for errors

msg = Trim(gobjMIMS.Screen.MSO.Error)

If msg > "" Then

MsgBox msg

Else

' loop to get every screenful of table codes

Do While True

' loop to get each line on the current screen

For CurrentLine = 1 To 12

With gobjMIMS.Screen.MSO

If Trim(.Fields("LVE_TYPE1I" & _

Format$(CurrentLine))) > "" Then

DisplayDetails CurrentRow, CurrentLine

Else

Exit For

End If

End With

Next

' if more lines to get, carry on

If Not gobjMIMS.Screen.MSO.IsCommand("Next Screen") Then

Exit Do

Else

gobjMIMS.Screen.MSO.Commands("Next Screen").Execute

End If

Loop

End If

9. After all employee leave taken information has been retrieved, close the MSO887 screen:

gobjMIMS.Screen.MSO.Commands("Home").Execute


Notes Other Notes:

It should be noticeable that the time required to access information for multiple employee leave taken information using MSO screens is considerably longer than that required to access the same information using a single Retrieve from the business object.

You should always close the MSO screen when you have finished with it, so that other screens can be used, since MIMSX can only have one screen open at any time. The Idle property can be checked to ensure that MIMSX is ready to open a new screen.

In some situations, you may not know whether a given command is valid for a particular screen. For example, depending on the number of records returned, the Next Page command may or may not exist. Use the IsCommand method to check for this. Note that "OK", "Home", "Revert", "Cancel", and "Help" are always valid commands.

For screens with multiple scrolling lines of data, appending the line number to the field name will allow access to individual lines. For example, TABLE-DESC2I4 is the description of the fourth table code on the MSM011B screen.

Some menus (particularly in HR) contain chains of screens. For example, the addition of a new employee involves filling out several screens of information. These chains may be initiated using the ExecuteChain command rather than the ExecuteMSO command.


Notes

Appendix C – Reference Material

The following reference material will aid your design and creation of Connector applications.

Installshield Installs:

ELLIPSE/Connector:

o C APIs

o Documentation

o Help Viewer

o Samples

MSQMOM Repository Explorer (might choose MOMBrowser instead)

Middleware

Runtime Repository (CDR files)

Installed Software:

MIMS Business Object Services Library (mimsx.dll)

ELLIPSE Repository Run-time Services Library (msyr01.dll)

Non-Windows C API

ELLIPSE API (Middleware)

ELLIPSE Local Data Services (msymcach.dll)

Please Note: MSQ000 and MSQERM are not installed as part of ELLIPSE/Connector

Installed Documentation:

523bod.chm

o Describes Ellipse Business Objects

Classes

Attributes

Operations

Data Types

Connector.chm

Samples

HTML Help File Viewer

ELLIPSE/Connector Documentation:

ELLIPSE/Connector User’s Guide

ELLIPSE Business Object Services Library (mimsx)

o User’s Guide

o Reference Manual


Notes ELLIPSE Runtime Repository Services (msyr01)

o User’s Guide

o Reference Manual

Miscellaneous

o C API User’s Guide and Reference

o ELLIPSE Error Reporter (msqerm)

o ELLIPSE Client Data Services - Cache (msymcach)Mincom Connector FAQInstalled Samples:ELLIPSE Account Summary - Excel 97

Project Maintenance - Project 98

Object Services Test Bed - Visual Basic

Repository Browser - Visual Basic

Standard Text Maintenance - Delphi 3

Unbounded Arrays - Visual Basic

C APIs also include examples

How do I use the Connector?

Ensure software installed and services registered

(eg. regsvr32 c:\…\mimsx.dll regsvr32 c:\…\msyr01.dll)

Develop macros or procedures within target application to communicate with ELLIPSE Server

Refer to Reference help file for details on objects, properties etc.

Refer to Data help file for data definition

Distribute as template file (eg. Word.dot).


Business Object Connector Manual

Documents

Transcript of Business Object Connector Manual