newObjects Active Label Variables object

Obtained from the VisiLabel object:
ds = VisiLabel.Variables;
The Variables object (also called Internal Data Source) implements the data connectivity for the Active Label ActiveX. This object can work as both - connection to an external data source (through ADO for instance) or it can be configured to maintain internal data cache which can be filled during the object initialization or/and at run-time. As the main area of application for the newObjects Active Label product is WEB based applications - for them the internal cache is much more convenient for use than a connection to an external data source (see the remarks section).

Members reference:

Properties
Field  Returns 
Syntax:
obj.Variables.Field(name_or_Index)
Parameters:
name_or_index - The name or the 0-based index of the field.
return value - the field object specified by the name_or_index argument
Count Long integer. Returns the number of the fields in the data source.
CacheMode Boolean. Switches between internal cache and external data source mode.
When set to true (default) the internal cache is used, When set to false an external data source is used - see also DSType, ConnectString, Query, Username and Password. 
Example:
objVisiLabel.Variables.CacheMode = true;
EOF Boolean read only indicators for end of data (EOF) or before the first record (BOF). The names come from End/Begin of file which may not be entirely correct but is traditional for objects that behave like recordsets.
BOF
SaveCache Boolean. Default is false. If set to true when the label is saved/uploaded the data entries of the internal cache are saved/uploaded as part of the label data/file. The CacheMode must also be true in order this to happen.
UseDataSource Boolean. Default is true. If true data source is used if false it is not used. This means that if this property is true when the VisiLabel.Print method is called set of labels will be printed by navigating the Variables object from its first record to its last (or less if the Print is called with a limitation for the maximum labels printed - see Print for more details).
If the property is false the internal data source is not used at all. The Print method will print sets of copies of the same label.
IgnoreErrors Boolean. Default is true.
This property is useful not only during the development. It instructs the Variables object to ignore most of the errors (all the errors that can be ignored) during the data navigation and data exchange between the fields and the label. For example you may have a field linked to non-existent element, the reverse or some fields may have completely inappropriate values. When set to true these will not lead to an error - the operation will proceed further and the effect on the screen will be that the missing data (for example) will result in empty values or the element will not change if it is linked incorrectly.
Why and when to use? During the development and tests you will want to have as much error information as possible, thus setting this to false will help you catch any omissions you have made - such as wrong data linking between elements and field, some unexpected data fetched by a query from a database etc. However, during the normal exploitation you will want to not bother the user with such details. Furthermore very often the data may actually be incomplete in some records. Depending on what you print and the data there is a level of tolerance for such problems - i.e. you can be completely content with some missing fields and so on. Thus once you test for other errors you can set the property to true for the production environment in order to allow the ActiveX ignore any such acceptable inconsistencies.
The property affects: Update. ReRead, MoveXXXX methods which return boolean success indicator if IgnoreErrors is true. It can be easily ignored by the application if it does not need to deal with the errors.
Note: It is recommended to set the property to false while configuring external data source. A typing mistake It is quite a typical case and you will want to receive descriptive errors and correct the problem.
DSType Long integer. Default is 0 (ADO). When the CacheMode is false this property specifies the external data source type. In version 1.0 only 0 - ADO is supported.
Note: Ado is used through automation. The ActiveX does not require any specific ADO version. To maximize the compatibility the features used are the minimal set needed thus any ADO version even very old one will work with Active Label.
ConnectString String. Default is empty. When the CacheMode is false this property specifies the connection/init string.
Example value:
Provider=Microsoft.Jet.OLEDB.4.0; Data Source=G:\databases\clothing.mdb;
The value syntax depends on the DSType. For ADO (0) you can use any init string that works with ADO and a desired OLEDB provider.
Query String. Default is empty. When the CacheMode is false this property specifies a query or a name of stored query which is executed to obtain the data.
Note that once you specify it and ensure that the ConnectString and the query are ok you can use FetchFields method to auto-configure the fields in the internal data source (Variables) - this object. After that you can connect them to the desired elements on the label. There are corresponding property sheets that allow this to be done interactively if you do not want to implement custom user interface for that purpose.
Username String. Default is empty. These properties specify the Username and the Password for the database connection. They have effect only with external data sources (i.e. CacheMode = false) that support credentials.
Password
ObjectState In version 1.0 always 4 - complete.
VisiLabel Returns the root object - VisiLabel object to which this internal data source belongs.
Methods
ShowProperties Example:
obj.ShowProperties();
objVisiLabel.Variables.ShowProperties();
Shows the property sheets for the Variables object enabling interactive configuration of the data source and its fields.
Clear Example:
obj.Clear();
Clears all the fields configured with the Variables object. Also clears the cache if in Cache mode. 
AddField Syntax:
var field = obj.AddField(name, type [, size]);
Parameters:
name - String. The name of the new field
type - Integer. The type of the new field (use VARTYPE constants)
size - Integer, optional. The size of the field for variable length types (Strings for example)
returns: the created and added field object.
The VARTYPE values supported are:
var cvtByte = 17; // unsigned byte
var cvtInteger = 2; // two bytes short integer
var cvtLong = 3; // 4 bytes long integer
var cvtFloat = 4; // 4 bytes floating point number
var cvtDouble = 5; // 8 bytes double precision number
var cvtBoolean = 11; // Boolean value
var cvtCurrency = 6; // Currency (8 bytes integer)
var cvtDate = 7; // Date value (double treated in a special manner)
var cvtString = 8; // String - requires size to be specified.
var cvtSByte = 16; // signed byte
var cvtUInteger = 18; // unsigned 2 bytes short integer
var cvtULong = 19; // Unsigned 4 bytes long integer.
Note that you need to configure fields in CacheMode because they define the cache geometry. If external data source is used the fields can be automatically created by calling the FetchFields after configuring the data source.
Remove Syntax:
obj.Remove(name_or_index);
Parameters:
name_or_index - the name or the 0-based index of the field.
Removes the specified field.
UpdateLabel Syntax:
obj.UpdateLabel([ignoreErrors]);
obj.ReadLabel([ignoreErrors]);

These methods transfer the data between the fields of the Variables object and the elements on the label using the defined data bindings (see Field.Property and Field.Element). The ReadLabel transfers them from the label elements to the fields, while the UpdateLabel transfers them from the fields to the label elements.
Apparently UpdateLabel is most often needed, while the other method is provided mainly for applications that want to implement direct data editing from the label design form/window/page.
Both methods have an optional argument - ignoreErrors. It is by default true which means that if the data transfer is not successful the operation will continue. For example there could be a missing field or element. During printing the UpdateLabel is called internally also with ignoreErrors = true. When called directly for another reason the application may need to allow errors to be generated in order to enable the user correct them - then it should call them with the optional argument set to false.
These methods are typically used together with navigation methods (MoveXXXX) and over an initialized Variables object. Note that the Variables object does not support writing data to external data sources, thus only the internal cache can be updated (see Update) using data from the label elements. 
ReadLabel
Update Syntax:
b = obj.Update();
returns: true - success or false - failure.
This method works only if CacheMode is true. It updates the current cache entry with the current values of the fields. Can be used together with ReadLabel to transfer data from the label elements to the internal cache.
See also IgnoreErrors.
ReRead Syntax:
b = obj.ReRead();
returns: true - success or false - failure.
Rereads the data from the cache or the external data source (depending on the CacheMode) into the fields of the object.
See also IgnoreErrors.
MoveNext Syntax:
b = MoveXXXX();
returns: true - success or false - failure.
These methods navigate through the data - position the Variables object over the Next (MoveNext), precious (MovePrev), first (MoveFirst) or the last (MoveLast) record. Note that over external data sources only MoveFirst and MoveNext are guaranteed to work. This limitation is here because Active Label keeps its requirements to the external data sources to the possible minimum (i.e. it needs to be able to print sets of labels or give the user the option to cycle through them and see if everything is ok, but nothing else is vitally important).
See also IgnoreErrors.
MovePrev
MoveFirst
MoveLast
AddNew Syntax:
b = obj.AddNew( [records] );
Parameters:
records - Integer, default is 1. How many records to add.
returns: true - success or false - failure.
Adds a new record to the internal cache if the object is in CacheMode. It is also affected by IgnoreErrors. Cannot be used with external data sources.
ClearFieldValues Syntax:
obj.ClearFieldValues();
Sets all fields empty.
Reset Syntax:
obj.Reset();
Resets the state of the object. Reconnects and positions over the first record. Can be used instead of MoveFirst to guarantee that everything is ok. In case of CacheMode = true, it just positions over the first cache record (no need of re-connection in this case). In case of external data source re-establishes the connection to the database and re-executes the query. This may seem like slow process, but considering the situations in which it is needed (printing for example - VisiLabel.Print does this internally) the time needed is minimal compared to the following operations.
ResetCache Syntax:
obj.ResetCache();
Resets the internal cache (clears all the records in it). 
FetchFields Syntax:
b = obj.FetchFields();
Can be used only if CacheMode is false. Connects to the external database (see ConnectString), executes the specified Query and determines what fields are returned. Then it destroys all the fields in the Variables object and creates fields to match the fields returned by the query. It is affected by IgnoreErrors. Most often you will need to set IgnoreErrors to false before calling it in order to be able to inspect the error if such occurs (for example there could be an error in the query or the connection string that prevent the operation from completion). However in some cases it is desired to ignore the errors and just report success or failure (Many end-user oriented UI-s are designed this way).

Remarks

A developer familiar with ADO or other database ActiveX library will easily notice the similarities between the Variables object and the recordsets in these libraries. However, the Variables object is dual. It can work with its own internal cache or bind to an external recordset-like object provided by the external data access facilities in use. Once configured and connected it is navigated much like a recordset. Lets put some lines of code to illustrate this (see also the installed examples).  

Lets connect to MS Access database:

var vars = objVisiLabel.Variables; // Get the object in a variable to minimize the typing work
vars.CacheMode = false; // Change to external data source mode
vars.DSType = 0; // We will use ADO to manage the external data source. 
vars.ConnectString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=G:\\databases\\clothing.mdb;";
vars.Query = "SELECT * FROM T";
// Assuming that the database is there and the table exists
// we can fetch the fields returned and thus auto-configure the object with the appropriate fields.
if (vars.FetchFields()) {
  // We have the fields
  // there we can end for now and may be leave the user define links with the elements
  // on the label.
} else {
  // error something is wrong with the database or the query
}

If everything is correct at this point we have a configured Variables object: It "knows" how to connect to the DB, what a query to execute, and we gave it a chance to try it and learn what fields are returned. During this test the object deleted any exiting fields previously configured in it (if there were any) and created automatically fields that match the fields returned by the query. They are named after the names returned by the query and they have types set to the closest COM type match of the DB field type. 

// Lets put a HTML button that resets the DB connection
<INPUT TYPE="BUTTON" VALUE="Reset" onClick="vars.Reset()">
// Of course we can use any other user interface approach for the same purpose.

If we want to give the user means to move to another record we can do this like this:
<INPUT TYPE="BUTTON" VALUE="Reset" onClick="vars.MoveNext();vars.UpdateLabel();">

The set back of the above code is that it does not deal with errors. If we did this early enough to ensure that the user will be able to click the buttons in Ignore errors mode:
vars.IgnoreErrors = true;
It will be ok because the errors will just be ignored and nothing strange for an end-user will happen - no error messages. However we may want to be precise and show the error to him/her. Then we can use code like this:

vars.IgnoreErrors = false;
try {
  vars.MoveNext();
  vars.UpdateLabel(false);
} catch (e) {
  // Deal with the error. For example simply show the error:
  alert(e.description);
}

Still in many cases the end users are not to be bothered with such errors. Then we can go for the middle:

vars.IgnoreErrors = true;
if (vars.MoveNext()) {
  vars.UpdateLabel(true);
} else {
  // Show simple error.
  alert("No more records");
}

We do not check the details about the error and just check if the operation was successful. Is this enough? In most cases yes - if the database connection has been successful and we just navigate through the recordset there is not much else that may happen unless there is a general problem with the machine (such as low memory, disrupted network connections etc.). If that is so a MoveNext failure most likely will be the last thing on our mind.  So why bother the end-user with messages he/she may not understand.

Note that the above examples are in Javascript with assumption that we use a DHTML page. As we mentioned using external data source in WEB page is not too convenient. For instance the page in which we write this is probably generated on the WEB server by ASP, JSP, PHP or other script, while the database in the code lines above is accessed on the local machine. Of course with a different connection string we can access a database server on the network, but typically the data needed for the label is known for the server side of the application (for the ASP, JSP, PHP script for instance). So the above sample lines are not the best way for an WEB application. In fact they illustrate what a stand alone application would do - such as a desktop application written in VB, C++, Delphi or other language. The remarks illustrated by Javascript are also true for such application and just the syntactical constructions will differ. For WEB applications it is more convenient to use the cache mode and send the data to the label from the WEB server and not leave the control fetch it on its own. 

So, lets now illustrate the typical techniques for an WEB application. Note that we will be very brief here, a fully working code can be found in the installed examples.

In HTML pages Active Label is embedded like this:

<object classid="clsid:09A02CEE-410B-47BA-A837-E62C9C8D70BF" id="VisiLabel" width="100%" height="400">
... Series of <PARAM> tags
</object>

The PARAM elements between the OBJECT tags specify the settings and the contents of the label (see the reference in Data, file and command formats). Alternatively the label can be initialized by using DATA attribute in the opening OBJECT tag or using a SRC parameter. No matter which method is used you can fill the contents of the internal cache of the ActiveX during the initialization. 

................

 

 

 

newObjects Copyright 2001-2006 newObjects [ ]