Methods of the oEORun object
Creating an oEORun object
After you created a model with the Force4 Modeler, you create the server components for the Omnis Studio platform. For this to work you enable OMNIS in the preferences in the Modeler page. Leaving the into Folder entry empty will automatically find the Omnis Studio java path for the platform u are working with when you hit the servercomponents button in Force4 Modeler.
For using the methods of the oEORun object you need an instance of this object. Therefore we create a new oEORun object with the following code:
Do $clib.$objects.oEORun.$new() Returns oeo
To receive the results from methods like $queryByFormat, $queryRelation, $queryObject, $modelList, $entityList and $attributeList you have to create Omnis list variables. But you doesn't have to define them in code as this will be done automatically when you call these methods.
Our newly created object oeo will allow us to call the other methods described here.
$openModel opens the recently generated model of the Force4 Modeler.
For this method to run, you must supply 3 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pFilename (Character)
The name of the model. is the combination of the packet name and the model name. For example, the packet name is net.aplusl.Force4Demo and the model name is Force4Demo, then the combination net.aplusl.Force4Demo.Force4Demo will be the parameter pFilename.
3.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
Though you can open the model many times, it will only be loaded once.
Example
We will open the model Force4demo with the help of the object oeo:
Do oeo.$openModel($ctask().$name,'net.aplusl.Force4Demo.Force4Demo',lerrtext) Returns #F
$closeModel helps you with closing the previously opened model. Every session connected with this model will loose its connection with the database.
The method $modelList will tell you, if an model is already opened.
For this method to run, you must supply 3 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pFilename (Character)
The name of the model. is the combination of the packet name and the model name. For example, the packet name is net.aplusl.Force4Demo and the model name is Force4Demo, then the combination net.aplusl.Force4Demo.Force4Demo will be the parameter pFilename.
3.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$queryByFormat let you perform a search within an entity. You can refine the search with the help of some search clauses, which logically combine some rows of this entity or return only values which met special conditions.
In return, you get a list of found records. The rows of this list correspond to the data type of what you will search, when you define the parameter pInterests.
If there are fields in the database that contain the value NULL, you don't get resulting rows containing this fields. For example: looking only for firstName like '*' doesn't match rows with firstName=NULL. You overcome this limitation by combining more columns in your pSearchCriteria parameter.
For this method to run, you must supply 10 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pEntityName (Character)
The entity name as defined in the Force4 Modeler.
3.pSearchCriteria (Field reference -> List)
The search clauses are being passed as a list of the following columns (all of type Character)
Column 1
You can combine search clauses here with logical AND and telling the search to meet both, or with logical OR to meet either one of the clauses.
The clause in the first row will be ignored.
Column 2
holds the attribute name to be searched in the entity as defined in the Force4 Modeler.
Searching in relations of this entity is possible with the dot notation relation.attribute (address.city)
Column 3
contains one of the possible search operators:
4.|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
less than or equal search clause
|
|
|
greater than or equal search clause
|
|
|
contains part of the search clause. Respects the case.
|
|
|
contains part of the search clause. Not respecting the case.
|
like und caseInsesitiveLike operators may contain the wildcards ‚*‘, as well as ‚?‘. This enables your search to match parts of the data to be searched.
Column 4
will be the value of what to be searched. This row is of type Character an automatically converted to the type the attribute is defined with.
For example: a Date data type is of the form 'y M D H:N:S' ('1980 01 15 23:10:59')
Column 5
is a flag. Possible value is 'V' for operating on values (lastName=Schmidt) or 'A' for operating on attributes (lastName=firstName)
Examplelist iSearchList
-
6.pInterests (Field reference -> List)
Is a list with one column of type Character which will hold the attribute names you are interested in as the result of your search. You ask for relational attributes with the dot notation relation.attribute (address.city). The resulting list pList converts this as relation_attribute in the column name of the List pList (address_city)
Examplelist iInterestList
7.pSortBy (Field reference -> List)
Is a list with one column of type Character which will hold the attribute name the resulting list pList will be sorted by.
Examplelist iSortList
8.pFetchLimit (Number - Long integer)
The maximum numbers of rows to fetch into the resulting list (0 means unlimited)
9.pKeepIds (Boolean)
Setting pKeepIds=kTrue (what you normally should do) will tell the result list pList to add the columns holding the primary keys. These extra columns have a name starting with 3 underscores ('___'). You should not alter these columns.
10.pDistinct (Boolean)
Setting pDistinct=kTrue let the search be distinct, normally you set pDistinct=kFalse to get all records.
11.pList (Field reference -> List)
This is the list of found records. The rows of this list correspond to the data type of what you will search, when you define the parameter pInterests.
Examplelist iResultList
12.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$queryObjects let you search for further attributes of an entity you already have some results from in pList. Another list pResults will hold the additional found records.
The number of rows in pResults will be equal to the number of rows in pList but pResults may contain empty rows.
For this method to run, you must supply 7 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pEntityName (Character)
The entity name as defined in the Force4 Modeler.
3.pList (Field reference -> List)
holds the objects for which you query further attributes.
4.pInterests (Field reference -> List)
holds the names of the additional attributes in a column of type Character. For querying relational attributes you have to use the dot notation relation.attribute (address.zip)
Examplelist iAddedInterestList
5.pKeptIDs (Boolean)
Set pKeptIds=kTrue if you have the primary keys as additional columns in your pList. Otherwise, set pKeptIds=kFalse if you have the primary keys as a regular column in your pList. Setting pKeptIds=kFalse not having any sort of primary key in your pList will return an empty list pResults.
6.pResults (Field reference -> List)
Your new list holding the additional objects.
Examplelist pList from a recent query
Examplelist pResults
-
8.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
Similar to $queryByFormat, $queryRelation let you perform a search within an entity, but this time on a relation of a given entity. You can refine the search with the help of some search clauses, which logically combine some rows of this entity or return only values which meet special conditions.
For this method to run, you must supply 8 parameters.
1.pSessionId(Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pEntityName (Character)
The entity name as defined in the Force4 Modeler.
3.pRelationName (Character)
The relation name as defined in the Force4 Modeler.
4.pSearchCriteria (Field reference -> List)
The search clauses are being passed as a list of the following columns (all of type Character):
AND/OR, Attribut, Condition,Value, Flag.
Preparation of these columns is analog the pSearchCriteria parameter in $queryByFormat.
5.pInterests (Field reference- > List)
Is a list with one column of type Character which will hold the attribute names you are interested in as the result of your search.
Preparation of these columns is analog the pSearchCriteria parameter in $queryByFormat.
6.pKeepIds (Boolean)
Setting pKeepIds=kTrue (what you normally should do) will tell the result list pList to add the columns holding the primary keys. These extra columns have a name starting with 3 underscores ('___'). You should not alter these columns.
7.pList (Field reference -> List)
This is the list of found records. The rows of this list correspond to the data type of what you will search, when you define the parameter pInterests.
8.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$updateObjects updates all objects in the O/R-Cache with the corresponding values in pList. Rows not having a primary key are being inserted, rows with primary keys are being updated.
For this method to run, you must supply 6 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pEntityName (Character)
The entity name as defined in the Force4 Modeler.
3.pList (Field reference -> List)
References the list of objects to be updated.
4.pApplyPKs (Boolean)
pApplyPKs will only come into play if if there objects to be inserted into the O/R-Cache.
Setting pApplyPKs=kTrue takes the primary key from the pList. The primary key can be manually created, but cannot be empty
Setting pApplyPKs=kFalse will tell the underlying O/R-Framework to automatically apply primary keys when $saveChanges is called.
This will only work, if there is a single primary key of numeric type. Alphanumeric or combined primary keys are not automatically being generated. You have to supply a function in Force4 Modeler for this to happen.
5.pKeptIds (Boolean)
You should set pKeptIds=kTrue if in the pList the additional columns with primary keys exist. if the primary keys exist as normal columns of the pList, you set pKeptIds=kFalse.
6.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$deleteObjects deletes the Objects in pList from the underlying O/R-Cache and the next call of $saveChanges will propagate those deletes to the database.
For this method to run, you must supply 5 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pEntityName (Character)
The entity name as defined in the Force4 Modeler.
3.pList (Field reference -> List)
References the list of objects to be deleted.
4.pKeptIds (Boolean)
You should set pKeptIds=kTrue if in the pList the additional columns with primary keys exist. if the primary keys exist as normal columns of the pList, you set pKeptIds=kFalse.
5.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$invalidateObject marks the objects in pList as invalid in the O/R-Cache. This forces a fresh fetch from the database the next time these objects are being accessed. Objects already altered since the last $saveChanges are not marked as invalid.
Keep in mind, that invalidating objects bears some performance decrease due to roundtrip to the database the next time you fetch objects.
For this method to run, you must supply 5 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pEntityName (Character)
The entity name as defined in the Force4 Modeler.
3.pList (Field reference -> List)
References the list of objects to be marked as invalid.
4.pKeptIds (Boolean)
You should set pKeptIds=kTrue if in the pList the additional columns with primary keys exist. if the primary keys exist as normal columns of the pList, you set pKeptIds=kFalse.
5.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$saveChanges applies the changes being made in this session to the O/R-Cache to the database. This is the only method that writes to the database.
The O/R-Cache will be marked with a time-stamp of the last save so that $revertChanges knows to which state the objects should be revertet.
Not respecting the referential integrity of the object model will cause error messages.
For this method to run, you must supply 2 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
Changes made to the objects of this session can be reverted with this method up to the point in time when the last $saveChanges call has been made.
For this method to run, you must supply 2 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$invalidateAllObject marks all objects as invalid in the O/R-Cache. This forces a fresh fetch from the database the next time these objects are being accessed. Objects already altered in this session are not marked as invalid.
Keep in mind, that invalidating objects bears some performance decrease due to roundtrip to the database the next time you fetch objects.
For this method to run, you must supply 2 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$resetCache deletes the whole O/R-Cache for this session.
Keep in mind, that resetting the O/R-Cache bears some performance decrease due to roundtrip to the database the next time you fetch objects.
For this method to run, you must supply 2 parameters.
1.pSessionId (Character)
The parameter pSessionId must be an unique character string. It will identify the client to the underlying O/R-Framework.
2.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$modelList asks the oEORun object for all opened models returning the names in the pList.
For this method to run, you must supply 2 parameters.
1.pList (Field reference -> List)
References the list of all opened models.
2.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$entityList asks the oEORun object for all entity names in a given model returning the names in the pList.
For this method to run, you must supply 3 parameters.
1.pModelName (Character)
The model name for which we want the entity names.
2.pList (Field reference -> List)
References the list of all entity names.
3.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
$attributeList asks the oEORun object for all attribute names in a given model returning the names in the pList.
For this method to run, you must supply 3 parameters.
1.pEntityName (Character)
The entity name for which we want the attribute names.
2.pList (Field reference -> List)
References the list of all attribute names.
3.pErrMsg (Field reference -> Character)
You will get a Boolean as a return value with kTrue for OK or kFalse in case of an error, which you will find in pErrMsg.
pList will contain 4 columns with the following details:
Column 1 (lpname)
the attribute name as defined in the Force4 Modeler.
Column 2 (lptype)
the type of the attribute. 'A' for attribute or 'R' for relation.
Column 3 (lpdetail)
shows the internal data type of that attribute when lptype=A or the name of the relation when lptype=R.
R = Real (Floating Point),
S = String,
T = Timestamp,
I = Integer,
D = Data (Binary)
Column 4 (lpsrc)
when lptype=R, lpsrc contains the attribute name that is the foreign key to that relation. address will be the name of the relation, addressId the foreign key to which tho Address object is bound to.
Examplelist iAttributeList of object Person