This function is provided when using Adelia Print Engine.
It is used to add data (any Adelia-type "DataValue" parameter) to a data model.
This data is referenced in the model with a key (Adelia ALPHA-type "KeyName" parameter).
A data model is a set of key/data pairs. This model is identified by a unique name ("ModelName" parameter). It is automatically created when a pair is first added.
Each time a pair is added, the Adelia type of the data to add must be specified ("AdeliaType" parameter).
In the case of an array variable, the underlying Adelia type needs to be specified.
The value encoding mode for Adelia IMAGE/DATE/TIME/TIMESTAMP types can be specified in the data model.
For example, "image ;convimg=0" indicates that the variable to add is IMAGE type and its value will be stored in the form of a byte array.
This encoding mode can also be added when adding a complex-type variable (REF_CLASS or LIST).
In this case, it is taken into account if the variable contains attributes (for the REF_CLASS type) or columns (for the LIST type) of IMAGE/DATE/TIME/TIMESTAMP type.
For example, "class ;convdts=1 ;convimg=1" indicates that the variable to add is REF_CLASS type and that, if this contains DATE/TIME/TIMESTAMP or IMAGE-type attributes, they will be stored in the form of numeric values (timestamp) and byte arrays respectively.
Remember: The VaToolBx dll must be loaded (LOAD_DLL instruction) when this function is called and must remain loaded when the VaToolBxAPEClearDataModel, VaToolBxAPEMergeDoc, VaToolBxAPETransformDoc or VaToolBxAPEMergeAndTransformDoc functions are called.
Application area
- Java client,
- Java server,
- Adelia Web client,
- Adelia Cloud client.
Parameters
ALPHA(n) |
ModelName |
Data model name. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
ALPHA(n) |
KeyName |
Name of the key used to access the added value |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
All types |
DataValue |
Value of the data to add |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
ALPHA(n) |
AdeliaType |
Name of DataValue Adelia type. The Adelia types must be specified as follows:
There is the option to add an Adelia IMAGE/DATE/TIME/TIMESTAMP-type value encoding type:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||
NUM_BIN_2 |
ReturnCode |
Operation return code: 0: Operation completed successfully. -1: The data model name cannot be empty. -2: Error when adding an Adelia LIST type to the data model. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
Data is added to the model by copying.
For example, an item of LIST-type data will be duplicated (by copying from the list), and the copy will be added to the model.
If two calls to this function use the same key value, the older data associated with this key (during the first call) will be replaced by the data passed during the second call.
Finally, a key/data pair cannot be individually deleted from the data model (but the data model can be cleared completely using the VaToolBxAPEClearDataModel function).
The same data model can be completed in the same program call string.
The data model created in this way is the FreeMarker data source (the "data-model"; click here for mode details) when a template is being processed by the VaToolBxAPEMergeDoc function.
The data model is a hash table (or associative array).
Each item of data added is only accessible with its key. A key can represent a single item of data only.
In the data source, we use the variable with the key value name to access a data model value in FreeMarker (N.B. it is case sensitive).
For example, if the ("name"/"Mary") pair is included in the data source, the FreeMarker ${name} expression will have the alphanumeric string "Mary".
Each variable from the data source has a FreeMarker type deduced from the Adelia type of the associated data:
| Simple types | |||
Adelia Type |
Java type in the data model |
FreeMarker type in the data source |
|
ALPHA / DS |
String |
String |
|
NUM_BIN_2 / NUM_BIN_4 / NUM_BIN_8 / NUM_E / NUM_P |
Short (NUM_BIN_2) / Integer (NUM_BIN_4) / Long (NUM_BIN_8) / Integer, Long, Double, BigDecimal (NUM_E, NUM_P) |
Number |
|
BOOL |
Boolean |
Boolean |
|
IMAGE |
byte[] / String |
Sequence / String |
|
DATE |
java.sql.Date / Long / String |
Date / Number / String |
|
TIME |
java.sql.Time / Long / String |
Time / Number / String |
|
TIMESTAMP |
java.sql.Timestamp / Long / String |
Date-time / Number / String |
|
Complex types |
|||
| Adelia Type | Java type in the data model | FreeMarker type in the data source | |
REF_CLASS |
Map<String, Object> |
Hash |
|
LIST |
List<Map<String, Object>> |
Sequence (of Hash-type objects) |
|
ARRAY |
LinkedList<Object> |
Sequence |
|
Simple ALPHA type
Example
Adelia 4GL | NUM_BIN_2 retCode |
FreeMarker expression | ${name} |
Result in template | Mary |
Simple NUM_E(4,2) type
Example
Adelia 4GL | NUM_BIN_2 retCode |
FreeMarker expression | ${key_price} |
Result in template | 12.56 |
Simple BOOL type
Example
Adelia 4GL | NUM_BIN_2 retCode |
FreeMarker expression | ${ IsArchive?c } |
Result in template | true |
Simple IMAGE type
When adding an Adelia IMAGE-type variable to the data model, the Java type used to store the data in the data model can be chosen:
AdeliaType parameter value |
Description |
Java type in the data model |
image |
By default, the Adelia IMAGE-type variable is stored in the form of an alphanumeric string representing the image content, encoded in Base64 format. |
String |
image;convimg=0 |
Identical to the default behavior: the Adelia IMAGE-type variable is stored in the form of an alphanumeric string representing the image content, encoded in Base64. |
String |
image;convimg=1 |
The Adelia IMAGE-type variable is stored in the form of a byte array |
byte[] |
Example
Adelia 4GL | NUM_BIN_2 retCode * the image is converted to a Base64-encoded string |
FreeMarker expression | ${ dot } |
Result in template | iVBORw0KGgoAAAANSUhEUgAAAAkAAAAJCAMAAADXT/YiAAAAGFBMVEX///9SUlKAgIDr6+uBgYFaWlp9fX1WVlZoulyHAAAAJklEQVQImWNgwAqYWVhZmMEsJkZGRjYwixXIYkcTY2ZiZWLGbgQADREASBTqq5EAAAAASUVORK5CYII= |
Simple DATE/TIME/TIMESTAMP types
When adding an Adelia DATE or TIME or TIMESTAMP-type variable to the data model, the Java type used to store the data in the data model can be chosen:
AdeliaType parameter value |
Description |
Java type in the data model |
date |
By default, the Adelia DATE-type variable is stored in the form of a Java Date object. |
java.sql.Date |
date;convdts=0 |
Identical to the default behavior: the Adelia DATE-type variable is stored in the form of a Java Date object. |
java.sql.Date |
date;convdts=1 |
The Adelia DATE-type variable is stored in the form of a timestamp in the form of a number corresponding to a duration (in milliseconds) from January 1, 1970 at 0 o'clock (UTC). |
Long (e.g. 1546214400000 for the date December 31, 2018 with a forced time of 00:00:00) |
date;convdts=2 |
The Adelia DATE-type variable is stored in the form of an alphanumeric string in ISO 8601 format. |
String (e.g. "2018-12-31" for the date December 31, 2018) |
time |
By default, the Adelia TIME-type variable is stored in the form of a Java Time object. |
java.sql.Time |
time;convdts=0 |
Identical to the default behavior: the Adelia TIME-type variable is stored in the form of a Java Time object. |
java.sql.Time |
time;convdts=1 |
The Adelia TIME-type variable is stored in the form of a timestamp in the form of a number corresponding to a duration (in milliseconds) from January 1, 1970 at 0 o'clock (UTC). |
Long (e.g. 51782000 for the time 15:23:02 with a forced date of January 1, 1970) |
time;convdts=2 |
The Adelia TIME-type variable is stored in the form of an alphanumeric string in ISO 8601 format. |
String (e.g. "15:23:02") |
timestamp |
By default, the Adelia TIMESTAMP-type variable is stored in the form of a Java Timestamp object. |
java.sql.Timestamp |
timestamp;convdts=0 |
Identical to the default behavior: the Adelia TIMESTAMP-type variable is stored in the form of a Java Timestamp object |
java.sql.Timestamp |
timestamp;convdts=1 |
The Adelia TIMESTAMP-type variable is stored in the form of a timestamp in the form of a number corresponding to a duration (in milliseconds) from January 1, 1970 at 0 o'clock (UTC). |
Long (e.g. 151400107765451782000 for the timestamp 2017-12-23 at 04:51:17 and 654 milliseconds) |
timestamp;convdts=2 |
The Adelia TIMESTAMP-type variable is stored in the form of an alphanumeric string in ISO 8601 format. |
String (e.g. "2017-12-23T04:51:17.654" for the timestamp 2017-12-23 at 04:51:17 and 654 milliseconds) |
Examples: Simple DATE type
Example 1
Adelia 4GL | NUM_BIN_2 retCode * orderDate is seen like a FreeMarker Date in template |
FreeMarker expression | ${ orderDate } |
Result in template | Oct 31 2018 |
Example 2
Adelia 4GL | NUM_BIN_2 retCode * orderDate is seen like a FreeMarker Number in template |
FreeMarker expression | ${ orderDate?number_to_date?date } |
Result in template | Oct 31 2018 |
Example 3
Adelia 4GL | NUM_BIN_2 retCode * orderDate is seen like a FreeMarker String (ISO 8601 format) in template |
FreeMarker expression | ${ orderDate?date.iso } |
Result in template | Oct 31 2018 |
The data model is a tree structure model: each key/data pair is added to a root called ".data_model".
The special FreeMarker .data_model variable represents the data source. It is Hash type (hash table) and references the "sub-variables" with the key value of each added pair as a name.
To differentiate between a FreeMarker variable from a template of a variable from the data source, it is preferable to use the ${.data_model.name} rather than ${name} expression.
If the variable is complex type (hash or sequence), it can be used to reference other "sub-variables" which could themselves be complex type (nested at several levels). ↑ Top of page
Complex REF_CLASS type
In the data model, an Adelia REF_CLASS-type item of data (Adelia CLASS object instance) is reference by a Freemarker Hash-type variable.
The values of attributes defined in the class are accessed via "sub-variables" of the same name as the attribute names.
The "sub-variables" type (simple or complex) will depend on the Adelia type of the associated class attribute.
When the key value is *BLANK, the sub-variables are added directly under the ".data_model" root.
Example 1
Adelia 4GL | Person CLASS: |
NUM_BIN_2 retCode | |
Data model |
|
FreeMarker expression | My name is ${ .data_model.client.name } ${ .data_model.client.lastName } |
Result in template | My name is Mary Smith |
Example 2
Adelia 4GL | Person CLASS: |
NUM_BIN_2 retCode | |
Data model |
|
FreeMarker expression | My name is ${ .data_model.name } ${ .data_model.lastName } |
Result in template | My name is Mary Smith |
Example 3
Adelia 4GL | Person CLASS: | Pair CLASS: |
NUM_BIN_2 retCode | ||
Data model |
| |
FreeMarker expression | ${ .data_model.weddingCouple.person1.name } ${ .data_model.weddingCouple.person1.lastName } and ${ .data_model.weddingCouple.person2.name } ${ .data_model.weddingCouple.person2.lastName } are just married! | |
Result in template | Mary Smith and Bob Starr are just married! | |
Taking into account the *SER_NAME annotations:
When an Adelia class instance is added to the data-model, it is possible to take into account the *SER_NAME-type annotations that are declared in the class, by setting the value of the "AdeliaType" parameter to "class;convcls=1". By default, if the "convcls" option is not specified (i.e. convcls=0), then *SER_NAME will not be taken into account.
- *SER_NAME used with a class attribute:
In this case, the name specified as the annotation's parameter is used as the "sub-variable"'s name, and allows the value of the class attribute to be accessed.
- *SER_NAME used with the *ATTRIBUTES keyword:
The annotation will only be taken into account if the key (KeyName parameter) is not set to *BLANK. In this case, the key's value is replaced by the value of the name defined as the annotation's parameter.
Exemple 4
Adelia 4GL | Person CLASS: { |
NUM_BIN_2 retCode | |
Data model |
|
Exemple 5
Adelia 4GL | Person CLASS: ALPHA(15) hisLastName *ser_name('lastName'); } *attributes *ser_name('person') |
NUM_BIN_2 retCode | |
Data model |
|
Exemple 6
Adelia 4GL | Person CLASS: |
NUM_BIN_2 retCode | |
Data model |
|
Complex LIST type
In the data model, an Adelia LIST-type item of data is referenced by a Sequence-type FreeMarker variable.
A FreeMarker Sequence is an ordered list of values.
In the case of an Adelia LIST, the variable is a sequence of Hash objects. Each Hash object contains the values of the LIST columns for each line.
The column values are accessed via "sub-variables" of the same name as the Adelia column names in the LIST (important: the column names are forced in lowercase).
The "sub-variables" type (simple or complex) will depend on the Adelia type of the associated column.
Example 1
Adelia 4GL | NUM_BIN_2 retCode |
Data model |
|
FreeMarker expression | Number of students: ${ .data_model.studentList?size} |
Result in the template | Number of students: 3 |
Example 2
Adelia 4GL | Person CLASS: |
NUM_BIN_2 retCode | |
Data model |
|
FreeMarker expression | Number of students: ${ .data_model.studentList?size} |
Result in the template | Number of students: 3 |
