Frequently Asked Questions

This section covers a series of 'How do I ?' type questions.  It is intended to be used as an introductory guide to getting started with the Core Objects product.  If you have any 'How do I' style questions that do not appear in this chapter, please email them to us at support@bluefinity.com and we will be very happy to answer them.  We will also add them to our on-line knowledge base for the benefit of others.

Core Objects FAQ
How do I start using Core Objects?
How do I let Core Objects know about the databases that I wish to access?
How do I connect to a database from my application?
How do I open a data file and read items?
How do I access the data within an item?
How do I write item data back to a file?
How do I delete items from a file?
How do I run my DataBASIC programs?
How do I select items from a file?

Binding Objects
Why Use a SecondaryDataSource?

How do I start using Core Objects?

The first action is to install the software - please refer to the Getting Started Guide for full details on how to do this.  The software installation process needs to be done on your software development workstation - a workstation that must, at the very least, have the Microsoft .NET framework installed, but will typically also have Visual Studio .NET installed.

The Core Objects module which needs to be installed first is the Client Interface Developer.  The installation routine for this product will install all of the components that you will utilize in getting connected to and then working with an mv database. 

The CIDSetup routine installs a Getting Started Guide.  We strongly recommend that developers read this guide if they are new to mv.NET.  A link to the guide is placed in the Start\Programs\mv.NET menu. 

Once the Client Interface Developer has been installed, you need to reference the following dll from within your .NET project: 

BlueFinity.mvNet.CoreObjects.dll

This dll can be found in Program Files\BlueFinity\mv.NET\lib 

Note, in Visual Studio .NET, you can use the Project\Add Reference menu option to add project references.  Once you have installed the software, you then need to use the Data Manager to define a server and an account profile in order to allow access to your mv account data and programs. 

<< Back to top

How do I let Core Objects know about the databases that I wish to access?

Before Core Objects can connect to an mv database, you need to give it some basic details about where the database is located, how it can be connected to and what kind of flavor it is.  These pieces of definition information are collectively known as a 'Server Profile'.  Thus, you need to create a server profile for each mv database installation that you wish to access.

The easiest way to do this is to use the Data Manager application - this will have been installed as part of the Client Interface Developer product installation procedure.  A shortcut to the Data Manager will have been placed in your Start\Programs\mv.NET menu. 

Once you have created a server profile, you will need to create an 'account profile' for each mv database account that you wish to access on that server.  Again, the Data Manager should be used to do this.

Once you have a server profile created that contains an account profile, you are ready to connect to and use your mv database.

<< Back to top

How do I connect to a database from my application?

The first thing to check is that you have a reference to the following Core Objects assembly (dll file): 

BlueFinity.mvNet.CoreObjects.dll 

This dll can be found in Program Files\BlueFinity\mv.NET\lib 

Next, you need to create an instance of an mvAccount object.  This can be done as follows: 

Dim myAccount As New mvAccount(Server, Account, User, Password) 

Where Server and Account are respectively the names of the server and account profiles you wish to use to control the connection process.  User and Password are optional arguments and can be incorporated into the connection negotiation process if necessary.

If a connection is successfully established, the mvAccount object can then be used to access any of the information in the account.  If the connection process fails, an exception will be raised. 

The mvAccount class has an overloaded constructor which allows you to use the following alternate form: 

Dim myAccount As New mvAccount(Login, User, Password) 

The Login variable needs to be the name of a Login Profile that has been defined using the Data Manager.  We recommend that you use Login Profiles wherever possible as it provides a valuable level of naming abstraction from the names of your servers and accounts. 

<< Back to top

How do I open a data file and read items?

Using an mvAccount object (see 'How do I connect into a database?'), you first need to use its FileOpen method, for example, to open a file called ORGANIZATION, you would use the following code: 

Dim OrgFile As mvFile = myAccount.FileOpen("ORGANIZATION")

If the file is successfully opened, the mvFile object's Read Method can then be used to read an item.  For example, to read item ID '0001', you would use the following code: 

Dim OrgItem As mvItem = OrgFile.Read("0001") 

The mvItem object can then be used to access the data within the item.  See 'How do I access the data within an item?'. 

Note, the mvFile object supports a range of methods that read data from a file, e.g. ReadV and ReadBool.  Please refer to the class library chapter for further details.

<< Back to top

How do I access the data within an item?

Using an mvItem object (see 'How do I open a data file and read items?'), you need to use its Data property in order to both retrieve and update its data content.  For example, to set the Text property of a control to attribute 3 of an item, you would use the following code: 

txtAddress.Text = OrgItem.Data(3) 

The Data property is the default indexer of the mvItem class, therefore you could shorten the above code to: 

txtAddress.Text = OrgItem(3) 

As well as accepting an integer argument, the Data property can alternatively accept the name of a dictionary item for the file,  So, using the previous example, if we assume that dictionary item 'ADDRESS' is defined to access attribute 3, the following code could also be used: 

txtAddress.Text = OrgItem("ADDRESS") 

The Data property can additionally be passed a MultiValue and subvalue position to further refine the piece of item data that is accessed.  For example, if we assume that the address field is MultiValue, the following code would retrieve the 3rd MultiValue from the ADDRESS attribute. 

txtAddress3.Text = OrgItem("ADDRESS", 3) 

Note, that when data is retrieved using a dictionary name, the mvItem object will return a value that has been converted (if relevant) and cast as the appropriate data type using the contents of the dictionary item to guide it in this conversion/casting process.  The exception to this rule is if a return value contains MultiValue or subvalue marks, in which case constituent values will be converted to their appropriate output format but the overall return value has to be cast as a string type. 

Retrieving data via attribute position, on the other hand, will always result in an unconverted (raw item) string value being returned (unless you explicitly supply a conversion code as an argument to the Data property call).  

Updating the data within an item is just as straightforward.  For example, to amend attribute 1 in an item, the following code would be used: 

OrgItem(1) = "XYZ Systems Inc." 

Or, using a dictionary name: 

OrgItem("NAME") = "XYZ Systems Inc." 

The same rules (in terms of data conversion and casting) as per retrieving data content via dictionary name apply to updating data via dictionary name.  That is, the following code would result in attribute 4 being set to string "Feb 13 1961": 

OrgItem(4) = "Feb 13 1961" 

Whereas, the following code would result in attribute "DATEFORMED" being set to the mv internal date integer value representing date Feb/13/1961 (assuming that dictionary item DATEFORMED contains a date conversion/correlative). 

OrgItem("DATEFORMED") = "Feb 13 1961" 

If you want to update data content via attribute position, but still want data to be stored in internal format (i.e. input conversion to be performed), you will need to pass a conversion code as part of the update call.  The following examples illustrate storing a date value and a currency value: 

OrgItem(4, "D") = "Feb 13 1961"

OrderItem(3, "MR2") = 2050.75 

Finally, the mvItem list object also has an ID property which returns the associated item ID.

<< Back to top

How do I write items data back to a file?

Using an mvItem object (see 'How do I open a data file and read items?'), you need to use its Write method in order for its data content to be written back to the database.  For example: 

OrgItem.Write 

The above line of code will write the current data content of the OrgItem to the associated file and item ID that were used to retrieve it originally. 

If you wish to write an item back to a different ID in the same file, you can supply an alternative ID as an optional argument to the Write method:

 OrgItem.Write("0002") 

If you wish to write the item back to different file, you need to use the Write method of the alternative mvFile object.  For example: 

OrgArchiveFile.Write OrgItem

<< Back to top

How do I delete items from a file?

You can delete items from a database file by using either an mvFile object or an mvItem object. 

Using an mvFile object, you need to use its Delete method.  For example, to delete item "0001" from the file which has been opened into variable OrgFile you would use the following code: 

OrgFile.Delete("0001") 

With an mvItem object, you have to use its DeleteItem method.  This will delete the item indicated by the value of the object's ID property.  Note, the object's data content (i.e. the data content of the object in client memory) will be unaffected by the use of the DeleteItem method – only the database file item will be deleted.

<< Back to top

How do I run my DataBASIC programs?

There are 2 ways of executing DataBASIC code from within your .NET application - the method you should use depends upon whether the code is within a main-line program or a subroutine. 

If it is a main-line program, you can execute it by using the Execute method of an mvAccount object.  For example, to run program 'BATCHUPDATE' you would use the following code. 

myAccount.Execute("BATCHUPDATE") 

In fact, the Execute method can be used to run any command-level statement.  You can also provide arguments to the Execute call that will capture any output produced by the command and also its return status. 

If your code resides in a subroutine, you need to use the CallProg method of the mvAccount object.  This method also allows you to pass multiple (updateable) arguments to the subroutine.  For example, to call subroutine CHECKORDER, passing 2 arguments you would use the following code: 

myAccount.CallProg("CHECKORDER", OrderNo, OrderStatus) 

It is very important to make sure that the number of arguments that you supply to the CallProg method exactly matches the number of arguments defined within the subroutine that you are calling.

<< Back to top

How do I select items from a file?

There are a number of ways of selecting data from a file.  Below are the most common: 

mvAccount.Select

mvFile.Select

mvFile.IndexSelect

mvFile.QSelect  

The first 2 methods allow you to select items from a file in a manner which allows you to specify selection and sort criteria.  The third method (IndexSelect) allows you to select items from a file using a binary index that has been associated with the file.  The fourth method (QSelect) allows you to select items based on item IDs held within a specific item within a specific file. 

Below are examples of each of the above methods being used:

myAccount.Select("SELECT ORGANIZATION BY NAME WITH NAME = "E]") 

OrgFile.Select("NAME = "E]", "BY NAME") 

OrgFile.IndexSelect("NAME", "SW", "E") 

OrgFile.QSelect("PRODUCT", "RGY954", "4") 

The first 2 examples result in exactly the same selection of items, i.e. all organizations with a NAME attribute starting with the letter 'E' sorted in ascending NAME order. 

The third example assumes that you have created an index for the file called 'NAME' which indexes the ORGANIZATION file on sorted NAME attribute.  It selects items from this index starting at the point where NAME starts with the letter 'E' and will stop selecting when a name not starting with 'E' is encountered. 

The fourth example assumes that a MultiValue list of supplier codes is held in attribute 4 of all product items.  The code example here, thus, reads the list of item IDs from attribute 4 of item RGY954 within the PRODUCT file and then uses this as the basis to assemble a list of items from the ORGANIZATION file. 

All of the methods that can be used to select items from a file return an mvItemList object.  This object can then be used to access the selected items.  The following example illustrates how to access the first attribute of the 3rd selected item with mvItemList variable orgItems: 

name = orgItems(3)(1) 

If you want to iterate through the selected items, you can use the mvItemList’s EOL (end of list) property: 

Do Until orgItems.EOL

    OrgItem = orgItems.ReadNext

Loop 

Please refer to the class library chapter for more details on the mvItemList object.  Note, that the ReadNext method (as used above) returns an mvItem object – not just an item ID.  You can then use the ID property of this item if you wish to access its item ID.  However, if you ONLY want the item ID, the ReadNextID method is more efficient. 

Finally, all of the Item selecting methods can accept an mvSelect object within their argument list.  The mvSelect object provides a dozen or so properties that provide a high degree of control over both what data is selected from the server and how the selected data it is passed back to the client.  Some examples of these properties are: 

DictionaryList – the list of dictionary derived values required

AttributeList – the subset of attributes required

PreSelection – the command to run before the main selection

RetrievalStyle – the style of data retrieval from the server to client 

One of the main reasons for providing the mvSelect object is to allow the developer to optimize both the volume and timing of data transfer from server to client - this issue being of prime importance when ensuring that applications are scalable and capable of being run across a variety of network bandwidths. 

<< Back to top

Why Use a SecondaryDataSource ?

Within Binding Objects there are numerous places where you are able to specify the source of option data for a control or grid column – this is termed a secondary data source.  In all of the places where you may define secondary data, you may either specify the name of a file or the name of a SecondaryDataSource control as the source of such data.  The main advantages of using an SDS control are: 

• You are able to control the fetch-on-demand parameters used when the secondary data is assembled.

• You are able to reuse or share a single secondary data source amongst a group of controls.

• Option data needs to be drawn from a different database. 

The main disadvantage of using an SDS control is simply that you need to explicitly create it before you can use it.  The simple guideline is, therefore: only use an SDS if you need to utilize one of the above 3 capabilities, otherwise, specify secondary data sources via simple file name.

Basic Principles
The use of an SDS control to obtain option data is a 2-step affair.  Firstly, you create an SDS instance – an SDS icon is placed within the VS.NET Property window's mv.NET tab.  After creating an SDS instance, you may set the appropriate entries within the Property window's grid. 

Secondly, within the databinding definition for a control (accessed via the 'Databinding on' extended property for the control) you may set the selection criteria to be used for that specific control.   At runtime, the 2 sets of definitions are combined together in order to obtain the relevant option data.  The SDS control has no visible interface.

Class Interface Overview
The SecondaryDataSource control's class interface is accessible both at design time (via the VS.NET properties tool window) and also programatically.  The table below gives an overview of each member of the SDS interface.  More detailed documentation can be found in the on-line help integrated within Visual Studio.

<< Back to top