Documentación Plataforma ByXOne

As with the treatment of dataobjects, when we speak of the datacoll scope, we do not refer to an object with a fixed name that remains active throughout the execution of the application. Unlike appdata, this field does not have a specific name, but rather the user, through the work process with collections, decides to assign such name.

At the following example, we see how the objects of coll type would be as “:CollTestigos” as “a”. To make easier the understanding and maintenance of the code, it is preferable using a notation similar than “CollTestigos”.

Set CollTestigos=appdata.GetCollection("TestigosCYCIn")
Set a=appdata.GetCollection("TAREAID")

So, in this section we are going to describe functions which utility makes reference to collections, and in turn, they will be composed of objects which we can work with.

It returns the access string to data of the collection, with the macros replaced, with no filters and no subqueries.

It is basically used to debug and something like that.

It adds the object passed as parameter to the collection.

Optionally it allows to insert it in the position we want within the set of objects there is inside the collection.

If the Index parameter is not passed (its value is Empty), the object will be insered at the end of the collection.

This is the most used behaviour.

Example of Use:

	Set Obj=Coll.CreateObject
		Obj("LOGIN")=This("MAP_USUARIO")
		Obj("FECHAATT")=Now
		Obj("UPWD")=This("MAP_PWD")
		Coll.AddItem Empty,ObjG
		Obj.save
	Set Obj=nothing

It deletes from the database all the objects that meet the conditions of the access string and the filters of the collection.
It is the equivalent to run a collection with StartBrowse, MoveNext and delete each of them.

It is the most recommended method to delete sets of big objects, since loading all the objects with LoadAll and then delete them with DeleteAll it is a waste.

Example of Use:

	this.contents("Presupuesto").BrowseDeleteAll
 
	-----
 
	Set Coll=AppData.GetCollection("TerminadasBorradoFinalizadas")
		filtro=Coll.LinkFilter
		Coll.LinkFilter="ACEPTADA=2 OR (ESTADO=1 AND FECHA<"+CStr(ahora)+")"	
		Coll.BrowseDeleteAll
		Coll.LinkFilter=filtro
	Set Coll=Nothing

It is similar than BrowseDeleteAll] but the rules for removing objects are not checked.

This system is used to delete quicly and with no interruption a big deal of object.

As the removing rules are not checked, the actions are executed with greater speed and there is no possibility to interrup the cycle by failing any delete rule.

Example of use:

	this.contents("Presupuesto").BrowseDeleteWithNoRules

It returns the amount of object that will be run in theStartBrowseactive cycle.
If there is no cycle active, or if the one has been activated by passing False (or not passing anything) to the call to StartBrowse, this property returns -1. In the Win32 platforms(PC, Web, Windows Mobile) this property always returns -1 unless that the database supports records counting, or in negative case, that the collection has the alternate-counter=true attribute.

In cases such as MySQL this is always like that.

The mobile platforms different than WM always use the alternative method, so they do not depend on the type of database used.

Example of Use:

	.....
	coll.StartBrowse true
	nLenData=coll.BrowseLength
	.....

It clears the collection (downloading the objects it has).

The call to this method does not affect the StartBrowse actives browse, so CurrentItem won´t be affected by the call to this method.

It is important that if we have references to objects that are loaded in the collection, such references are canceled before calling to Clear, since in platforms working with COM errors can occur when trying to cancel the references later, or when exiting from the script, since when the references come out from the scope they will try to release and being the objects destroyed, errors will occur.

This same scripts, when executing in backgrounds that not use COM, they wouldn´t give error whereas we do not try to use the references later, which wouldn´t imply that they were well programmed, but just they are develooped by using a different technology.

Example of use:

	....
	obj.save
	set obj=Nothing
	coll.Clear
	set coll=Nothing

It returns the value of an attribute of the collection heading.

coll.CollPropertyValue("title")

If there is an active platform and there is the <platfom> node for it within the collection, the value will be searched first within such node.

If the attribute doesn´t exist or it has no value, the property will return an empty string.

It returns the amount of objects loaded in memory by this collection.

The objects can be loaded by calling to LoadAll, by calling to AddItem, or by making searches that load objects in memory (Item o FindObject).

....
Set Coll=appdata.GetCollection("UserAttempts")
Coll.filter="t1.LOGIN="+appdata.varianttostring(This("MAP_USUARIO"))
Coll.LoadAll
cantidad=Coll.Count
if cantidad<5 then
....

It creates a copy of the collection and it returns it.

The content of the collection is not copied, in case we want to copy also the data, we have to do it by hand.

Set Usuarios=AppData.GetCollection("Usuarios").CreateClone
Usuarios.Filter="t1.LOGIN='" + Cstr(This("MAP_USUARIO")) + "'"
Usuarios.StartBrowse
Set Usuario=Usuarios.CurrentItem
Set UCorrecto=false
If Not Usuario Is Null Then
	If This("MAP_PWD") = Usuario("PWD") Then
		UCorrecto = True
	End if
End If
Usuarios.EndBrowse
Set Usuario=nothing
Set Usuarios=Nothing

It creates a new object by using the collection templates.

The class used to build the object will be taken from the “progid” attribute of the collection.

Each platform uses a map to transfer the names of the progids to the names of the class recognaised by such platform.

In those ones in which there is the possibility to use reflection, it can be used the “classname” attribute to indicate directly the class name, although the most advisable is using the same progid as always and let the platform makes the conversion.

Whatever the class used, it will be descendent from the XoneDataObject base class or whatever it is called in any platform.

Now, the createObject method can be passed parameters.

Examples:

  var param = {
  USUARIO:”usuario 1”,
   DESCRIPCION:”Descripción de usuario 1”
  }
  var obj = appData.getCollection(“Usuarios”).createObject(param);

\\
var param = {
  USUARIO:”usuario 1”,
   DESCRIPCION:”Descripción de usuario 1”
   }
   var obj = appData.getCollection(“Usuarios”).createObject(param,true);

Set coll=appdata.getcollection("Previstas")
Set det=coll.CreateObject
coll.AddItem Empty, det
	det("IDENCARGO")=this("IDENCARGO")
	det("IDEMPRESA")=this("IDEMPRESA")
	det("IDUSUARIO")=this("IDUSUARIO")
	det("MODELOPLATAFORMA")=this("MODELOPLATAFORMA")
	det("NUMCOMPLETO")=this("NUMCOMPLETO")
	det("FECHA")=this("FPREVISTA")
	det("HORA")=this("HPREVISTA")
det.Save
set det=nothing
set coll=nothing

It returns the current object of the StartBrowse active browser.

If there is no active browser, this property worths Nothing. This is what is used to know that a browser is over.

Appart from the PC and web platforms, all the rest use by default the same object and only replace the properties when moving by the browse, so the references must be not compared but the values (prefereably from the keys) in order to know which object is the one that is active in every moment or if the current object has changed.

Set Coll=appdata.GetCollection("ClasificarBlanco")
Coll.StartBrowse
Set Obj=Coll.CurrentItem
If not Obj is nothing then
....

It deletes all the object that are loaded in the collection.

The objects are deleted from the database (if the delete conditions are met) and then they are removed from the collection.

If any of the If any of the rules of elimination of any of the objects fails, the execution is interrupted at that moment.

It is most advisable thing could be use the BrowseDeleteAll method, but if we already have done a LoadAll we can use this one.

It deletes the object which key or index is indicated, both of the collection and the database.

If the delete rules are not met, the method fails and launch an error.

If the execution of any delete actions fails, the object is not deleted either and an error will be launched.

The example that follows, browse a collection of sale details, it checks if the field IDARTICULO=0, then it deletes the line.

Set cDetVenta=This.Contents("DetVenta")
i =0
While i<cDetVenta.Count
  Set vDet=cDetVenta(i)
  If vDet("IDARTICULO")=0 Then
     cDetVenta.DeleteItem(i)
     i=i-1
  End If
  Set vDet= Nothing										  			
  i =i +1
Wend	   
Set cDetVenta=Nothing

It returns the access string to data of the collection with all the macros replaced, the filters applied and in case it is about a collection supporting subqueries, already prepared to be used in the database or in the remote connection that is going to be executed.

It returns the main filter of the collection already developed with the macros replaced and ready to be used inside the data access string.

It returns the link filter of the collection (LinkFilter) already developed and with the macros replaced, ready to be used in the data acces string.

AppData.CurrentEnterprise.Variables("COLLFILTER")=this.contents("ImpDocumento").DevelopedLinkFilter+" AND t1.id="+cstr(IDDoc)

It ends the active browse in the collection.

If there is no browse, this function does nothing.

The call to this method always cancels CurrentItem, but it doesn´t affect to the objects loaded in memory through LoadAll, searches or calls to AddItem.

Set Usuarios=AppData.GetCollection("Usuarios").CreateClone
Usuarios.Filter="t1.LOGIN='" + Cstr(This("MAP_USUARIO")) + "'"
Usuarios.StartBrowse
Set Usuario=Usuarios.CurrentItem
Set UCorrecto=false
If Not Usuario Is Null Then
	If This("MAP_PWD") = Usuario("PWD") Then
		UCorrecto = True
	End if
End If
Usuarios.EndBrowse
Set Usuario=nothing
Set Usuarios=Nothing

It executes a SQL sentence by using a collection. It is useful for the maintenances, since if we define a ForMaintenance collection without replica, the sentences executed through would not be replicated. If it is used as source in a “traditional” collection, the ExecuteSqlString functioning is equivalent to AppData.ExecuteSQL.

Example of use:

<coll name="ForMaintenance" title="ForMaintenance" objname="ForMaintenance" updateobj="ForMaintenance" progid="ASData.CASBasicDataObj" sql="SELECT t1.*
		FROM ##PREF##ForMaintenance t1" connection="mtto">
      <connection name="mtto" connstring="bd/gestion.db" />
      <group name="General" id="1" />
</coll>
 
<coll name="ForUpdates" title="Consulta Stock" fontsize="7" progid="ASData.CASBasicDataObj" objname="" updateobj="" sql="SELECT t1.* FROM ##PREF##Empresa t1" special="true" notabx="true">
      <group name="General" id="1" />
      <prop name="MAP_CODTECNICO" visible="0" group="1" type="T" fieldsize="15" size="50" title="Tecnico"></prop>
 </coll>
 
 
'Actualizar el campo REPORTADO localmente, no replicar
appdata.GetCollection("ForMaintenance").ExecuteSqlString "UPDATE gen_instalaciones SET REPORTADO=0 WHERE ID=" + CStr(This("ID"))
 
'Actualizar el campo REPORTADO y replicarlo
appdata.GetCollection("ForUpdates").ExecuteSqlString "UPDATE gen_instalaciones SET REPORTADO=0 WHERE ID=" + CStr(This("ID"))

It returns or assigns value to the main filter of the collection.

The filter there is in the filter attribute of the collection in the mappings, IT IS NOT this filter.

This filter is the one used in the UI when the content is filtered through the visual controls.


Modifying this filter does not affect to a contents selection, since it is not the one used to limit the objects that are part of such contents.

Coll.filter="t1.LOGIN="+appdata.varianttostring(This("MAP_USUARIO"))

It searchs an object by following the search criteria passed as parameter.

The format used is the same than the one to filter the collection.

If the object is not found as result of the query, the method returns Nothing.

set Coll=Appdata.GetCollection("ConsultaExistencias")
set Obj = Coll.FindObject("SERIE='"+Cstr(this("MAP_SERIE"))+"'  AND IDALMACEN="+Cstr(this("IDALMACEN")))
If not Obj is nothing then
	Obj("EXIST")=Obj("EXIST")+1
	Obj.Save
End If
Set Obj=Nothing
Coll.Clear
Set Coll=Nothing

It returns True (not zero) if the collection is full (it has been named LoadAll and every object that met with the criterium have been loaded.). It returns False (zero) if the collection has not been loaded with LoadAll, or after loading it some objects have been deleted or some searches have been made which modify the load status of the collection.

It generates a ROWID by using the replica data of the connection used in the collection, as well as the table data and else.

This method encapsulates to the internal system of ROWIDs generation so it is quite safe to use it to generate unique values.

In all the environments that support it the GUIDs generation methods are used. In those in which this mechanism is not available, it is about to use a machinery of En todos los entornos que lo soporten se usan los métodos de generación de GUIDs. En aquellos en que este mecanismo no está disponible se trata de usar una random number generation machinery as secure as possible.

Example of use:

'Usar para generar un nombre único y asignárselo a un fichero jpg
This("MAP_FILENAME")="FT" + User("LOGIN")+ "_" + AppData.GetCollection("CollParaRowid").GenerateRowId + ".jpg"

It returns the visible name of a group of the collection given its ID.

If the group has inside platform node and there is active platform, first it will be searched in such node and after in the name of group.

It returns the amount of groups there are declared in the collection.

It returns the name of the key field of the collection.

Usually, key field is not declared, but it is used the value by default (ID). In case the key field has another name, it will be defined in the collection heading and that is the valud that this property returns.

It returns the ID of the currency to be used to clean monetary amounts in the list, and in the outputs used by this collection.

This property only works in the platforms displayed in the table, although they can be consulted in any platform, except that its value always be zero.

Assigning value to this property in another platform different than the diplayed ones in the table neither will have any effect.

It returns True (not zero) if the collection has a browse open :StartBrowse. The CurrentItem also can be checked, but in case the browse is at the end, CurrentItem will be Nothing and nevertheless it will have an open browse, that is, resources of the connection in use.

It returns False (zero) if there is no active browse.

It returns True (not zero) if the collection is locked by using Lock. It returns False (zero) if the collection is free (its normal status).

It returns an object of the collection given its key taken to text, its index inside the collection or the value of one of its fields.

The numeric index search is always made in memory. The search by key of by field pair, value is done first in memory and in case not finding the object with these features, the search will be made in the data connection.

This allows to accelerate the searchs in collections that have few elements by loading them in memory and keeping them there during the execution of the application.

It returns the value of the link filter of the collection.

This is the filter which is declared in the filter attribute of the collection in the mappings, or in the contents declaration and as its name indicates it is an auxiliary filter that wouldn´t be modified in execution time.

Even so, everyone can do what he thinks fit.

It loads in memory all the objects that meet with the filtering criteria the collection has.

It is important before calling to this method to make sure there are filters put already, since in case there are too many objects that meet the criteria, a problem with lack of memory may occur.

Example of use:

Set cDetVenta=This.Contents("DetVenta")
cDetVenta.filter="d.IDDOCUMENTO=" + CStr(This("ID"))
cDetVenta.LoadAll

It locks the collection to avoid its content will be modified.

If the collection is locked, the LoadAll and Clear methods won´t have any effect over the collection content.

The objects search is not affected by the lock status of the collection.

The following example, clears and filters a collection of sales details, and then, it locks it in order not to modify it.

Set cDetVenta=This.Contents("DetVenta")
cDetVenta.UnLock
cDetVenta.Clear
cDetVenta.filter="d.IDDOCUMENTO=" + CStr(This("ID"))
cDetVenta.LoadAll
cDetVenta.Lock

It returns or assigns value to the macro which name it is indicated.

The macros are replaced when the access strings, the filters and else are evaluated, so this is a way to achieve that the change of these data is made in a dynamic way during the execution of the program.

<coll name="ContarPiezas" title="ContarPiezas" objname="PiezasInc" updateobj="PiezasInc" progid="ASData.CASBasicDataObj" sql="SELECT count(t1.ID) AS ID FROM ##PREF##PiezasInc t1" filter="t1.NUMINCIDENCIA=##NUMINCIDENCIA##">
      <group name="GENERAL" id="1"></group>
      <macro name="##NUMINCIDENCIA##" value="0" default="true" />
      <prop name="NUMINCIDENCIA" group="1" type="T" visible="0" title="Incidencia" class="editreadonly" fieldsize="10" size="10" />
      .......
    </coll>
 
 
 'Después en un script, asignar valor a la macro ##NUMINCIDENCIA## para modificar el filtro de la colección
 Set cPiezas=AppData.GetCollection("ContarPiezas")
 cPiezas.macro("##NUMINCIDENCIA##")=AppData.VariantToString(nInc)
 cPiezas.StartBrowse
 .......

It returns the amount of macros there are defined in the collection, both those that have received value dynamically and those that have been declared in the mappings.

It moves the browse to the first object of the collection.

The method is defined in all the platforms, but in those in which are not shown, it has no effect.


In the platforms shown only works when the database associated to the connection supports it.

It moves the browse to the last object of the collection.

Same than MoveFirst, it only works in those platforms that work with several databases and specifically in those that allow this operation.

In the platforms not shown, the method has no effect.

It moves the browse to the previous object. Here, the same observations are fulfilled as for the MoveFirst or for MoveLast.

It moves the browse toward the next object.

If as a result of the movement, the end of the browse is reached, the current object (CurrentItem) will be Nothing to indicate that the browse has ended.

Set cRec =AppData.GetCollection("RecPend")
cRec.filter="r.IDCLIENTE=" + CStr(This("IDCLIENTE")) 
cRec.StartBrowse
While Not cRec.Currentitem is Nothing 
  Set ObjRec = cRec.Currentitem
  ....... 			
  Set ObjRec = Nothing
  cRec.MoveNext
Wend						
.....

It returns true (not zero) if the key of the object is multiple or False (zero) if the key is a single field.

This property always returns False in the platforms that are not listed in the table, since in these platforms the use of multiple keys is not supported.

Actually, the multiple keys are designed to use the XOne machinery with databases designed for other apps use, something that in mobility is not the case, since the idea is that the mobile application has a database designed from the first moment.

The integration interface with the possible backend must take care of translate the multiple keys into a single key (usually an autonumeric field).

It returns the collection name, such as declared in the mappings.

Example of use:

' Se comprueba si el nombre de la colección padre es MenuPersonalizado antes de modificar la propiedad MAP_IDSELECCIONADO
If This.OwnerCollection.Name="MenuPersonalizado" Then
    This("MAP_IDSELECCIONADO")=0
End If

It returns the application owner of the collection.

Because in an execution environment there can not be more than one application, the value of this property is the same one as that of the AppData global variable .

It returns the owner object of the collection.

This owner has value only when the collection is a contents.

If it is about a global collection or if it is a copy of a contents, the value of this property is Nothing.

<selecteditem show-wait-dialog="false">
  <action name="runscript">
     <script language="VBScript">
        'Asignar el ID del registro seleccionado, al campo MAP_SELECTEDITEM del padre
        This.OwnerCollection.OwnerObject("MAP_SELECTEDITEM")=This("ID")
     </script>
  </action>        
</selecteditem>   

It returns the amount of properties the collection has.

If the collection inherit from another one, this property returns the correct amount of properties (the own ones plus those inherited from the father). Although the inheritance mechanism is not very decent, at least, what works works on all platforms.

Anyway, that of trying not to use the mechanism of inheritance remains valid until further notice.

It returns the name of a property of the collection given its numeric index (in order of declaration in the mappings. ).

With this name we can access the properties and methods that have as parameter a field name.

It returns the property title (data field) of the collection.

If there is an active platform and this property has a platform node, firstly, it will be searched in this node the title attribute. If it is not found, the title attribute of the property will be searched, and in case of not appearing, the text of the prop node will be returned.

If the node has no text, the field name will be returned.

It returns the type of the data property as declared in the mappings.

It returns the name of the group to which the property belongs in the collection.

In order to search the name, the rules of the platforms displayed in the previous properties are followed.

It returns the value of the visible field of the property.

It meets the rules of the platforms previously described. If at the end of all the tests there is no value to return, it will be returned 1, since the value by default of visibility is always 1.

It removes from the collection the object which index or key is passed as parameter.

The object is not removed from the database, only from the collection.

It saves all the object that the collection has.

If any recording fails the method will stop and the occurred error will be launched.

It returns or assigns the sorting string to the collection.

The sintax is the same one than an ORDER BY sentence must have in a SQL string.
The value that this property has when the collection is created is the value of the sort atribute of the collection heading.

....
'Ordenar la colección Kilometraje por FECHA descendente, antes de comenzar a recorrerla
Set cKm = AppData.GetCollection("Kilometraje")
cKm.sort="FECHA DESC"
cKm.StartBrowse
...

It starts a browse by following the rules of the access string, filters and collection sorting.

If there is at least an object, this one will be loaded in the CurrentItem. If it is passed to True as parameter, the collection counts the amount of objects that are going to be browsed.

Set Usuarios=AppData.GetCollection("Usuarios").CreateClone
Usuarios.Filter="t1.LOGIN='" + Cstr(This("MAP_USUARIO")) + "'"
Usuarios.StartBrowse
Set Usuario=Usuarios.CurrentItem
Set UCorrecto=false
If Not Usuario Is Null Then
	If This("MAP_PWD") = Usuario("PWD") Then
		UCorrecto = True
	End if
End If
Usuarios.EndBrowse
Set Usuario=nothing
Set Usuarios=nothing

It returns True (Not zero) if the collection uses a non-numeric key (usually is used together with “idfieldname” to use keys set different than the ones used in the XOne databases).

It returns False (zero) when the key is numeric (value by default).
The way of counting will depend on the platforma and the database.

It unlocks the collection in order to use Clear and LoadAll again.

The following example, clears and filters a collection of sales details and then, it locks it so that it does not change.

Set cDetVenta=This.Contents("DetVenta")
cDetVenta.UnLock
cDetVenta.Clear
cDetVenta.filter="d.IDDOCUMENTO=" + CStr(This("ID"))
cDetVenta.LoadAll
cDetVenta.Lock

It returns the name of the key field used for the updates.

Usually, this field is the same than IdFieldName, although there may be cases in which it is read in one object and written in another, so the update field may be different.

Also, it may happen that the key field is qualified and we want to use it without qualifying in order to be able to update the data.

It returns or assigns value to the variable which name is indicated.

The collections also may have variables, what allows there to be an really global environment to storage values that go beyond the scripts scopes, since the global collection always are.

The values stored in the variables of the global collections can be kept there while the execution of the application is maintained or while the variables are not cleaned.