Business Object Connector Manual

Mincom Conne ctor
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.....................................................................................................16 Topic 3 COM Overview......................................................................................................17 Walkthrough Object Connection Process..........................................................................20 Learning Checkpoints.....................................................................................................22 Topic 4 Developing with Excel............................................................................................23 Demonstration The Excel Sample Behind the Scenes.....................................................24 Practice Modify an Excel Application................................................................................28 Topic 5 Developing with Microsoft Excel and Word...............................................................29 Practice Adding MIMSX Macros to an Excel Spreadsheet....................................................30 Practice Create Macros in a Word Document....................................................................38 RevTopic 6 Developing with the MSO interface....................................................................39 Demonstration Walk through example.............................................................................43 Practice Creating an Excel Application.............................................................................44 Review of MSO Interface................................................................................................45 Topic 7 Java Middleware...................................................................................................46 Practice Java Exercise 1.................................................................................................61 Practice Java Exercise 2.................................................................................................62 Review of Java..............................................................................................................63 Course Summary................................................................................................................64 Training Evaluation........................................................................................................65 Appendix A FAQs..............................................................................................................67 Appendix B Additional Exercises.........................................................................................75 Practice Employee Leave................................................................................................76 Appendix C Reference Material..........................................................................................80
Business Object Connector
2003 Mincom
Page i
Introduction to Mincom Connector
Notes
Welcome & Orientation

Welcome Orientation Schedule Participant Objectives
Mincom Connector 80
2004 Mincom Page 1 of
Course Objectives
At the end of this course you will be able to :

Notes
Identify the Mincom Object Model Develop applications using COM Develop Connector applications using Ellipse business objects and the MSO Interface
Page 2 of 80
2003 Mincom Mincom Connector
Topic 1 Mincom Connector Overview
Notes
Mincom Connector Overview
What is Mincom Connector? Mincom Connector Architecture
Mincom Connector 80
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 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
Mincom Connector consists of the following software components:
Page 4 of 80
Notes
Connetor Arcitecture2
Mincom Connector 80
Topic 2 The Mincom Object Model Notes
Mincom OOD Objectives

On completion of this topic you will be able to:
Identify the Ellipse Architecture
Define an Ellipse Object Browse the Ellipse Repository
Page 6 of 80
Notes
Ellipse Architecture
Presentation Layer
Interface
Application Layer
Interface
Database Layer
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.
Mincom Connector 80
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 vendors databases.
Notes
Page 8 of 80
Notes
Object Oriented Design
Concepts: ObjectA 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 objects state. A property may be another object. An action that can be performed on an object or by an object. Methods may change the properties and state of an object.
Method
Event Signals when some kind of change in state has occurred. Class Abstract definition of an object, describes the idea of an object.
Mincom Connector 80
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:
Notes
Attribute(s):
Method(s):
Event(s):
Page 10 of 80
Notes
Ellipse Object Terminology
Ellipse Class
Employee
Ellipse Attributes (or Properties)

EmployeeId, FirstName,
LastName
Operations (or Methods)

Create, Modify, Retrieve
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: Ellipse Attributes: Ellipse Methods: Employee EmployeeId, FirstName, LastName Create, Modify, Retrieve, Fetch, etc.
Additional Examples: Ellipse Classes: Ellipse Attributes: Ellipse Methods: WorkOrder, EmpAvailability, APLItem, etc Equipment.AccountCode, WorkGroup.Crew Standard operations, such as Create, Modify, Retrieve, Fetch, Search, Detail, etc.
Mincom Connector 80
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:

Notes
Open MSQMOM.EXE in the Ellipse Client BIN directory Review Ellipse Objects Review corresponding attributes and methods
Page 12 of 80
Practice Defining an Ellipse Object
Notes
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
Mincom Connector 80
Notes
Page 14 of 80
Notes
Ellipse Repository
MSQ Applications, e.g. MSQ620 .cdr files, e.g. msaworko.cdr PRESENTATION LAYER Front-End Repository
Middleware
Transport
ml.mac files, e.g. msk620ml.mac MSK Applications, e.g. MSK620
Back-End Repository Business Object Server
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.
Mincom Connector 80
Learning Checkpoints Notes
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
Page 16 of 80
Topic 3 COM Overview
Notes
COM Overview Objectives


Describe the benefits of COM Identify the Connector COM Object Hierarchy
Describe the Object Connection Process
Mincom Connector 80
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
Notes
Benefits of developing with COM include: Product openness Deliver functionality as components Internet and HTML hosting possibilities Exploit client platform technology
COM Automation
Client
5. Call interface members. E.g. ReqApp.SummaryView.Show; 4. COM Gets object interface pointer, and returns it to client.
Server Object
3. Factory creates object instance.
Class Factory
COM
1. Create object given a ProgID.
2. COM locates implementation and launches or loads server.
E.g. ReqApp := CreateOLEObject(MSQ140.MimsApplication);
Registry
Page 18 of 80
Notes
MIMSXServer MIMSBlocks MIMSBlock MIMSRequests MIMSRequest MIMSInstances MIMSInstance MIMSFields MIMSField MIMSReply
COM Object Hierarchy
MIMSRequests MIMSRequest MIMSInstances MIMSInstance MIMSFields MIMSField
Object Collection Internal Object (Returned)
Concepts: Connector programs are based around the building, sending and processing of network messages. Therefore, connector programs need a connection to the serverin 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 MIMSBlock MIMSRequest MIMSReply MIMSInstance MIMSField An object representing a connection to a ELLIPSE Server. A network block (i.e. a set of requests) that is sent to the ELLIPSE Server for processing. A command to be executed by the ELLIPSE Server (i.e. WORKORDER.Fetch). A network reply from the ELLIPSE Server in response to the MIMSBlock. The input or output parameters of a specific command in a MIMSRequest. A name/value pair used to define fields within a MIMSBlock, MIMSReply, MIMSRequest or MIMSInstance.
Mincom Connector 80
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
Notes
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)
Page 20 of 80
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)
Notes
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) or if 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
Mincom Connector 80
Learning Checkpoints Notes
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.
Page 22 of 80
Topic 4 Developing with Excel
Notes
Developing with Excel Objective

Modify an Excel Application
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.
Mincom Connector 80
Demonstration The Excel Sample Behind the Scenes
Scenario: Retrieve accounting information and review it using Excel. EnCore Path: Demonstration Script Connect to Server:
Notes
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.
Page 24 of 80
Demonstration Script - Module Routine 1
In Project Explorer, open Modules for mimsx.xls and doubleclick mdlMacro. Subroutine MIMS_Connect shows code to create, initialize and connect to ELLIPSE Server:
Set gobjMIMS = new MIMSXServer If Not gobjELLIPSE.Initialise Then <error handling>
Notes
If Not gobjMIMS.Connect(False) Then <error handling>
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 OLEObject Set 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 o o
Loops through all requests in reply Loops through all instances in request Processes fields in instance and extracts value
Mincom Connector 80
Demonstration Script - Form Routine 1

In Project Explorer, open Forms for mimsx.xls and doubleclick 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 Block o Request o Instance o Fields
Notes

Create a new block:
Set Block = gobjMIMS.Blocks.New("Accounts") Block.Requests.New ("Request") Block.Requests("Request").Instances.New ("Instance")
Create a new request:
Create a 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...
Page 26 of 80
Send the block to the server for processing :

Set AccountReply = Block.Send
Notes
Tidy up allocated resources:

gobjMIMS.Blocks.Remove ("Accounts")
Call subroutine to process reply:

DisplayAccountDetails
SetAccountData subroutine processes reply. o o o Check if reply is empty: Check for errors in reply: Error text in
If aobjReply.Requests(1).Instances.Count = 0
If Reply.FindFirstError(nReq, nInst) Then
Reply.Requests(nReq).Instances(nInst). _Fields("_ErrorTexts")
OR
Reply.Requests(nReq).Fields("_ErrorTexts")
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 message Else ' A non Ellipse error occurred, display a generic error
Properties of MIMSError include: o o o ErrorMessage ErrorField (ELLIPSE server errors only) ErrorCode (ELLIPSE server errors only)
Mincom Connector 80
Practice Modify an Excel Application
Scenario: Modify an existing Excel application. EnCore Path: Practice Script:
Notes
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
Page 28 of 80
Topic 5 Developing with Microsoft Excel and Word
Notes
Developing with Word Objective

Create MIMSX Macros in a Word Document
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.
Mincom Connector 80
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 Public gobjMIMS Public gbConnected Public CurrentRow variables As MIMSXServer As Boolean As Integer ' current row for output
Notes
Page 30 of 80
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 = True End Sub
Notes
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:
Mincom Connector 80
'*************************************************************** '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 If End 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 = ""
Page 32 of 80
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" ' 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: DisplayError End Sub
Notes
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:
'**************************************************************
Mincom Connector 80
'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 Next End With End Sub End Sub
Notes
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 If End 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
Page 34 of 80 2003 Mincom Mincom Connector
Document_Open subroutine will be displayed. Add the following code:
Notes
Mincom Connector 80
'******************************************************************************* '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 With End Sub
Notes
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:
Page 36 of 80
'****************************************************** ' 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").Delete End Sub
Notes
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.
Mincom Connector 80
Practice Create Macros in a Word Document
Scenario: Use Visual Basic scripting to create macros in a Word document. EnCore Path: Practice Script:
Notes
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.
Page 38 of 80
RevTopic 6 Developing with the MSO interface
Notes
Developing with the MSO Interface Objective On completion of this topic you will be able to:
Use the MSO interface in Mincom Connector
Mincom Connector 80
Ellipse Screen Object Model Summary

MIMSX Server MIMSX Server Initialise Connect Disconnect GetParameter SetParamater Notes
Screen Screen Idle ExecuteMSO MSO MSO Message Error Name ActiveField IsCommand Commands Commands Count Command Command Name Execute Fields Fields Count Field Field Name Value Length
Page 40 of 80
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 fields 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. Notes
Mincom Connector 80
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. 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
Page 42 of 80
Demonstration Walk through example
Notes
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")
Mincom Connector 80
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
Page 44 of 80
Review of MSO Interface
Notes
Review

Review of the MSO Interface Questions?
Mincom Connector 80
Topic 7 Java Middleware Notes
Java Middleware Objectives

Identify the Java Object Model
Build a Java Application
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 Ellipse 5.2 or higher (at present no MSO support for Ellipse 5.2.3).
Page 46 of 80
A text editor (Notepad, JBuilder, etc.) Notes
Mincom Connector 80
Java Object Model
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.
Page 48 of 80
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. The methods for connect(), request(), and disconnect() are fully implemented and the method for login() is implemented by the base MimsSession Class. CICSSession CICSSession is the CTG MIMS Session. 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. 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
Mincom Connector 80
Java Implementation
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.
Page 50 of 80
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 Notes
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: // validate user's session info IMimsSession mySession = null; MimsSessionFactory sessionFactory = MimsSessionFactory.getMimsSessionFactory(); mySession = sessionFactory.getMimsSession("Tux"); Connecting via CICS: // validate user's session info IMimsSession mySession = null; MimsSessionFactory sessionFactory = MimsSessionFactory.getMimsSessionFactory(); mySession = sessionFactory.getMimsSession("Cics");
Mincom Connector 80
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
Page 52 of 80
Notes
Building a Request List
Step 1: Create a Session Object and connect to the host server
Step 2: Construct a Request List Step 3: Add requests to the Request List Step 4: Add new fields to the requests Step 5: Add Request Instances Step 6: Send the Request List to the server
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.
Mincom Connector 80
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
Page 54 of 80
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.
Notes
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.
Mincom Connector 80
Step 1: Create a session object, and connect it to the host server machine.
// validate user's session info IMimsSession mySession = null; MimsSessionFactory sessionFactory = MimsSessionFactory.getMimsSessionFactory(); mySession = sessionFactory.getMimsSession("TpNet", "D:\\jdk1.4.2\\mims\\BufLib");
Notes
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 list MIMSRequest 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 request myEqReq = 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 Request MIMSInstance 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()); } }
Page 56 of 80
Notes
Processing the Reply

Getting the Reply List Getting the Reply Data Getting the Reply Instance Data Multi Instance Replies
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
Mincom Connector 80 2004 Mincom Page 57 of
MIMSRequest object in the MIMSRequests collection of the ReplyList). The MIMSFields collection is then accessed by using the getFields 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
Page 58 of 80
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()); } }
Notes
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); } }
Mincom Connector 80
if (myReply.getRequests().item(0).isRestart()) // getting restart value from request 0 restartRecord = myReply.getRequests().item(0).getFields().item(myReply.RESTART). getValue(); else break; myEqReq.getFields().create(myReply.RESTART, restartRecord); } while (true);
Notes
Page 60 of 80
Practice Java Exercise 1
Notes
Scenario: Using a Java, create and send a Request List. EnCore Path: Practice Script: 1. 2. 3. 4. 5. 6. Create a Java public class Create a session Create a new request list (block). (MIMSBlock) Create a new request. (MIMSRequest) Add the service request EMPLOYEE.Fetch to the new request Add the following list of outputs to the request: 7. 8. 9. 10. 11. 12. Employee EmployeeFormattedName EmailAddress Title TitleDesc LastName FirstName SecondName ThirdName PreferredName PhotoPathname
Create a new request instance to the request, adding the input field Employee with value NINES Create a reply block (MIMSBlock) Send the request list to the server, returning the Reply in the Reply block Get the first reply from the Reply Block (MIMSRequest) Extract the output values from the reply and display them on the screen Disconnect from the server
Mincom Connector 80
Practice Java Exercise 2
Scenario: Using Java, retrieve information from Ellipse. EnCore Path: Practice Script: 1. 2. 3. 4. Create a Java public class Create a Session Execute MSO621 On MSM621A screen: a. Set OPTION1I field to 1 b. Set WORK_ORDER1I field to 2001 Execute the OK command on MSM621A screen Retrieve the following fields from the MSM621D and display them using System.out.println to the console WORK_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 Disconnect from the server
Notes
2. 3.
4.
Page 62 of 80
Review of Java
Notes
Review

Java Object Model Creating a Session Building a Request List Processing the Reply Interfacing with MSQMUI
Mincom Connector 80
Course Summary Notes
Course Summary

Connector Architecture Mincom Object Model
Course Summary
Developing Connector applications with Ellipse business objects and the MSO Interface
Developing Connector applications with the Java Middleware
Page 64 of 80
Training Evaluation
Notes
Please take a moment to complete the Evaluation form. Your comments help us ensure that we provide great training that meets your needs. Thank You.
Mincom Connector 80
What Next

Notes
One-on-One Training Consulting
Congratulations on completing the course. Thank you for your participation.
Page 66 of 80
Appendix A FAQs
Notes
MIMS Business Object Services Library

Error Trapping All 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 If End Sub
Why 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 File

Mincom Connector 80 2004 Mincom Page 67 of
The 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 Tab The 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 Tab The WDEBUG Tab is used to setup general debug file information 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
Page 68 of 80
Sample The 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 ................ 0010 - 00 00 00 00 00 .............x_S 0020 - 65 72 76 69 63 ervice.EMPLOYEE. 0030 - 46 65 74 63 68 Fetch._MaxInst.2 0040 - 00 5f 53 65 72 ._Service.WORKOR 0050 - 44 45 52 2e 46 DER.Fetch.Employ 0060 - 65 65 00 35 32 ee.521.560.WorkO 0070 - 72 64 65 72 00 rder.90......... 0080 - 00 02 00 9c 00 ba ................ 0090 - 00 01 00 01 00 27 ...............' 00a0 - 00 0a 00 08 00 36 .........?.....6 00b0 - 00 03 00 63 00 ...c.....Z...g.Z 00c0 - 00 0f 00 4a 00 ...J.....A...u.. 00d0 - 00 09 00 6b 00 00 00-00 00 00 00 00 00 00 00 00 00-00 00 00 02 00 78 5f 53 65 00 45-4d 50 4c 4f 59 45 45 2e 00 5f 4d-61 78 49 6e 73 74 00 32 76 69 63-65 00 57 4f 52 4b 4f 52 65 74 63-68 00 45 6d 70 6c 6f 79 31 00 35-36 30 00 57 6f 72 6b 4f 39 30 00-00 02 00 00 00 9c 00 02 00 00 01-00 b0 00 00 00 01 00 c0 00 00-00 01 00 ca 00 0e 00 1e 00 01-00 3f 00 0a 00 08 00 0a 00 08-00 5a 00 03 00 67 00 5a 0a 00 08-00 41 00 02 00 75 00 0a ...k
Notes
Mincom Connector 80
The following shows part of the response from the ELLIPSE Server to the above request block.
0000 - 00 07 00 10 1d 00 ........."...... 0010 - 00 00 00 01 01 53 .............._S 0020 - 65 72 76 69 63 ervice.EMPLOYEE. 0030 - 46 65 74 63 68 Fetch.TitleDesc. 0040 - 4d 72 00 52 45 Mr.RESULT..Print 0050 - 65 72 4e 61 6d erName.TENCPS2-L 0060 - 00 50 72 65 76 .PreviousLastNam 0070 - 65 00 41 4c 42 e.ALBERT.PostalS 0080 - 74 61 74 65 00 tate.Q.PhotoPath 0090 - 6e 61 6d 65 00 name.C:\.Printer 00a0 - 43 6f 64 65 00 Code.03.Preferre 00b0 - 64 4e 61 6d 65 dName.HOMER.Reso 00c0 - 75 72 63 65 43 urceClass.Q.Home 00d0 - 4d 6f 62 69 6c MobilePhoneNumbe 00e0 - 72 00 00 57 6f r..WorkFacsimile 00f0 - 4e 75 6d 62 65 998.R 0100 - 65 73 69 64 65 esidentialAddres 0110 - 73 4c 69 6e 65 sLine3.USA.Posta 0120 - 6c 41 64 64 72 lAddressLine1.13 0130 - 20 45 76 65 72 Terra 0140 - 63 65 00 43 6f ce.CompetencyDes 98 00 00-00 22 01 00 00 00 01 f7 00 00-00 00 00 02 12 b8 5f 65 00 45-4d 50 4c 4f 59 45 45 2e 00 54 69-74 6c 65 44 65 73 63 00 53 55 4c-54 00 00 50 72 69 6e 74 65 00 54-45 4e 43 50 53 32 2d 4c 69 6f 75-73 4c 61 73 74 4e 61 6d 45 52 54-00 50 6f 73 74 61 6c 53 51 00 50-68 6f 74 6f 50 61 74 68 43 3a 5c-00 50 72 69 6e 74 65 72 30 33 00-50 72 65 66 65 72 72 65 00 48 4f-4d 45 52 00 52 65 73 6f 6c 61 73-73 00 51 00 48 6f 6d 65 65 50 68-6f 6e 65 4e 75 6d 62 65 72 6b 46-61 63 73 69 6d 69 6c 65 72 00 35-35 35 2d 39 39 38 00 52 6e 74 69-61 6c 41 64 64 72 65 73 33 00 55-53 41 00 50 6f 73 74 61 65 73 73-4c 69 6e 65 31 00 31 33 67 72 65-65 6e 20 54 65 72 72 61 6d 70 65-74 65 6e 63 79 44 65 73 Evergreen Number.555-
Notes
This is the 2nd instance. Note it does not repeat the field names
0670 - 00 00 00 00 ....HILL,SANDRA 0680 - 45 6c 69 7a MS.QUE 0690 - 45 4e 53 4c ENSLAND..OVERBUR 06a0 - 44 45 4e 00 DEN....MELBOURNE 06b0 - 20 50 52 49 1.00000 06c0 - 30 30 35 36 MN 06d0 - 45 20 4f 56 OVB.N..OPERATO 06e0 - 52 20 4c 45 (O.B.) 48 49 4c 4c-2c 53 41 4e 44 52 41 20 61 62 65 74-68 20 4d 53 00 51 55 45 41 4e 44 00-00 4f 56 45 52 42 55 52 00 00 00 4d-45 4c 42 4f 55 52 4e 45 4e 54 45 52-20 31 00 30 30 30 30 30 30 00 41 43-4d 20 4f 50 52 20 4d 4e 42 00 4e 00-00 4f 50 45 52 41 54 4f 56 45 4c 20-33 20 28 4f 2e 42 2e 29 PRINTER 00560.ACM OPR E R LEVEL 3 Elizabeth
This is the response for the WorkOrder

0730 - 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.
Page 70 of 80
0750 - 50 65 72 6d PermitReqdSw..Rl 0760 - 6f 63 57 6f ocWo..LabcFinalS 0770 - 77 00 00 57 w..WoStatusM.C.E 0780 - 73 74 4f 74 +0.0 0790 - 30 00 52 6c 0.RlocVarAcctD.. 07a0 - 41 72 46 69 ArFinalSw..Compl 07b0 - 65 74 65 64 etedCode.AC.Equi 07c0 - 70 52 65 66 pRef.22301.ActCo 07d0 - 73 74 49 6e stInv..LastTranR 07e0 - 6c 6f 63 00 loc..CompletionT 07f0 - 65 78 74 45 extExists.N.PcCo 0800 - 6d 70 6c 65 +0.00.Com
69 74 52 65-71 64 53 77 00 00 52 6c 00 00 4c 61-62 63 46 69 6e 61 6c 53 6f 53 74 61-74 75 73 4d 00 43 00 45 68 65 72 43-6f 73 74 00 2b 30 2e 30 6f 63 56 61-72 41 63 63 74 44 00 00 6e 61 6c 53-77 00 00 43 6f 6d 70 6c 43 6f 64 65-00 41 43 00 45 71 75 69 00 32 32 33-30 31 00 41 63 74 43 6f 76 00 00 4c-61 73 74 54 72 61 6e 52 00 43 6f 6d-70 6c 65 74 69 6f 6e 54 78 69 73 74-73 00 4e 00 50 63 43 6f 74 65 00 2b-30 2e 30 30 00 43 6f 6d mplete. stOtherCost.
Notes
Mincom Connector 80
Excel VBA
Can 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 CommandBarControl Dim cstmELLIPSEConnect As CommandBarControl Dim menu As CommandBarControl See if the ELLIPSE menu already exists. If it does dont add another one. For Each menu In Application.CommandBars("Worksheet Menu Bar").Controls If menu.Caption = "&ELLIPSE" Then 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 = "&ELLIPSE Connect" ' If the ELLIPSE_Connect Option is selected run the ELLIPSE_Connect macro With cstmELLIPSEConnect .OnAction = "ELLIPSE_Connect" End With End Sub
Notes
Page 72 of 80
Microsoft Project 98 VBA

How 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 CommandBarControl Dim cstmELLIPSEConnect As CommandBarControl Dim menu As CommandBarControl ' See if the ELLIPSE menu already exists. If it does dont add another ' one For Each menu In Application.CommandBars.ActiveMenuBar.Controls If menu.Caption = "&ELLIPSE" Then Exit Sub End If Next ' Create a new Menu called "ELLIPSE" Set cstmELLIPSE = _ Application.CommandBars.ActiveMenuBar.Controls.Add(Type=msoControlPopu p, Before=9) cstmELLIPSE.Caption = "&ELLIPSE" ' Add a "ELLIPSE_Connect" option to the menu Set 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 macro With cstmELLIPSEConnect .OnAction = "ELLIPSE_Connect" End With End Sub
Notes
How 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
Mincom Connector 80
HTML and VBScript

I receive script errors when running the sample Ensure 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. Notes
Page 74 of 80
Appendix B Additional Exercises
Notes
This section contains additional exercises.
Mincom Connector 80
Practice Employee Leave
Scenario: 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:
Notes
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 Dim CurrentLine Dim Employee Dim msg As Integer ' current row for output As Integer ' current screen line As String As String ' employee id entered (eg. 564) ' 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))
Page 76 of 80
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_Connect End If CurrentRow = OutputRow
Notes
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
Mincom Connector 80
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
Notes
9. After all employee leave taken information has been retrieved, close the MSO887 screen:
gobjMIMS.Screen.MSO.Commands("Home").Execute
Page 78 of 80
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
Mincom Connector 80
Appendix C Reference Material Notes
The following reference material will aid your design and creation of Connector applications. Installshield Installs: ELLIPSE/Connector: o o o o C APIs Documentation Help Viewer Samples
MSQMOM Repository Explorer (might choose MOMBrowser instead) Middleware Runtime Repository (CDR files) 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)
Installed Software:
Please Note: MSQ000 and MSQERM are not installed as part of ELLIPSE/Connector Installed Documentation: 523bod.chm o Describes Ellipse Business Objects Classes Samples HTML Help File Viewer ELLIPSE/Connector Users Guide ELLIPSE Business Object Services Library (mimsx) Connector.chm Attributes Operations
Data Types
ELLIPSE/Connector Documentation:
Page 80 of 80
o o
Users Guide Reference Manual Notes
ELLIPSE Runtime Repository Services (msyr01) o o Users Guide Reference Manual
Miscellaneous o o o o C API Users Guide and Reference ELLIPSE Error Reporter (msqerm) ELLIPSE Client Data Services - Cache (msymcach) Mincom Connector FAQ
Installed 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 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).
How do I use the Connector?
Mincom Connector 80

Business Object Connector Manual

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Business Object Connector Manual

Încărcat de

Drepturi de autor:

Formate disponibile

Mincom Conne ctor

Business Object Connector

Introduction to Mincom Connector

Welcome & Orientation

Welcome Orientation Schedule Participant Objectives

2004 Mincom Page 1 of

2003 Mincom Mincom Connector

Topic 1 Mincom Connector Overview

Mincom Connector Overview

What is Mincom Connector? Mincom Connector Architecture

2004 Mincom Page 3 of

Mincom Connector consists of the following software components:

2003 Mincom Mincom Connector

2004 Mincom Page 5 of

Topic 2 The Mincom Object Model Notes

Mincom OOD Objectives

Identify the Ellipse Architecture

Define an Ellipse Object Browse the Ellipse Repository

2003 Mincom Mincom Connector

2004 Mincom Page 7 of

2003 Mincom Mincom Connector

Object Oriented Design

2004 Mincom Page 9 of

Practice Defining an Object

2003 Mincom Mincom Connector

Ellipse Object Terminology

Ellipse Attributes (or Properties)

Operations (or Methods)

2004 Mincom Page 11 of

Demonstration Business Object Browser

2003 Mincom Mincom Connector

Practice Defining an Ellipse 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

2004 Mincom Page 13 of

2003 Mincom Mincom Connector

ml.mac files, e.g. msk620ml.mac MSK Applications, e.g. MSK620

Back-End Repository Business Object Server

2004 Mincom Page 15 of

Learning Checkpoints Notes

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

2003 Mincom Mincom Connector

Topic 3 COM Overview

COM Overview Objectives

Describe the Object Connection Process

2004 Mincom Page 17 of

3. Factory creates object instance.

1. Create object given a ProgID.

2. COM locates implementation and launches or loads server.

E.g. ReqApp := CreateOLEObject(MSQ140.MimsApplication);

2003 Mincom Mincom Connector

COM Object Hierarchy

MIMSRequests MIMSRequest MIMSInstances MIMSInstance MIMSFields MIMSField

Object Collection Internal Object (Returned)

2004 Mincom Page 19 of

Walkthrough Object Connection Process

Initialise the MIMSX object

Establish Block framework

Create initial request

Define requested service to Request

Define ReplyList for Service (optional)