Example: Working with API Objects Step by Step

Let us explain the typical process of working with API object. We assume that you have logged in correctly and oVM variable now holds Application object. (see Logging In for a description of login). The following example demonstrates removing the first object in the "Person” catalog.

1. Get the container of API objects. You reach it by calling one of the “get” methods implemented in the main, Application object as we can show on the case of CATALOGS with its method getCatalogs. Getting a container is a first step you must always do in order to get some objects from the database, after that you can follow the relations that these object holds to get more diferrent objects.

Application.getCatalogs()

You can see that you always call methods using a dot convention. That is, you state the name of the object followed by a period (dot) and the name of the method and its argument list, like this:

oObjectYouWorkWith.itsMethod(arg1,arg2,arg3)

Most methods are run with some parameters that you put in the brackets, it can be for example a primitive value (string, integer, date…) or an object. As you see, in the case of getCatalogs the method doesn’t require any parameters.

In VBScript, you should formulate this command like

Set oCatalogs=oVM.getCatalogs()

This line results in creation of oCatalogs object that comprises the result of the getCatalogs method – it is a container of all catalogs.

2. Pick a particular item, let’s say a Catalog named “Person” from this container.

This item is created in the “oTransaction”, which you pass as a parameter for calling this method. This transaction must exist prior to running this line of code. See Work in Transactions for more information about transactions.

Set oCatalog=oCatalogs.find(oTransaction,”Person”)

3. Call a method implemented in this object.

It can be for example item, which returns a single business object held by this catalog.

Set oBO=oCatalog.item(0)

4. Finally you reach the object that has the method that can perform the desired action (it can be a BusinessObject or for example one of its BOFields further below in the API tree).

oBO.remove()

All this you can always put together in a single command on a single line, in other words, you can chain various methods into one command, without needing to allocate variables to outputs of particular steps. Remember that the type of the return value (object) must be always compatible with the following method call, i.e. if the return object does not provide the method you are calling (e.g. it is a different object type), the operation will result in an exception:

Calling methods step by step and on one line

The crucial quality of each application, including a script, is the speed of its run, in other words, the efficiency of the algorithm. Calling each method takes its time. For this reason, if you call a method in a cycle several times, as it happens when browsing the contents of a catalog using item as in the case shown above, it is obviously preferable to put most of the previously called methods into one new variable like we did with the oCatalog object. After that you call only the methods provided by oCatalog (in our case, item), which will result in a shorter code and a considerably faster run.

However, if you call the method only once, it is preferable to put the code in a single command on a single line to save memory and time, which would be taken by creating of unnecessary new variables.

Example – Running methods in a cycle and a single line

We assume that you have run Valuemation and logged in correctly before starting this code. oVM variable now holds Application object. See Login Syntax for the section of the opening code.

‘calling a method step by step

oCatalog=oVM.getCatalogs.find(oTransaction,”Person”)

for i=0 to oCatalog.length-1

  oCatalog.item(i).remove

next

’calling a method on one line

oVM.getCatalogs.find(oTransaction,”Person”).item(0).remove