Products Downloads


French version


 

 

 

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:

"alpha"

Adelia ALPHA or ALPHA array type

"bool"

Adelia BOOL or BOOL array type. 

"num_bin_2"

Adelia NUM_BIN_2 or NUM_BIN_2 array type. 

"num_bin_4"

Adelia NUM_BIN_4 or NUM_BIN_4 array type. 

"num_bin_8"

Adelia NUM_BIN_8 or NUM_BIN_8 array type.

"num_e"

Adelia NUM_E or NUM_E array type.

"num_p"

Adelia NUM_P or NUM_P array type.

"date"

Adelia DATE or DATE array type.

"time"

Adelia TIME or TIME array type.

"timestamp"

Adelia TIMESTAMP or TIMESTAMP array type.

"list"

Adelia LIST type

"class"

Adelia REF_CLASS or REF_CLASS array type.

"image"

Adelia IMAGE or IMAGE array type.

"ds"

Adelia DS type

 

There is the option to add an Adelia IMAGE/DATE/TIME/TIMESTAMP-type value encoding type:

"image;convimg=0"

Base64-encoded bytes.

"image;convimg=1"

Byte array.

"date;convdts=0"

Date object.

"date;convdts=1"

Timestamp in the form of a number corresponding to a duration (in milliseconds) from January 1, 1970 at 0 o'clock (UTC).

"date;convdts=2"

Alphanumeric string in ISO 8601 format

"time;convdts=0"

Time object.

"time;convdts=1"

Timestamp in the form of a number corresponding to a duration (in milliseconds) from January 1, 1970 at 0 o'clock (UTC).

"time;convdts=2"

Alphanumeric string in ISO 8601 format

"timestamp;convdts=0"

Timestamp object.

"timestamp;convdts=1"

Timestamp in the form of a number corresponding to a duration (in milliseconds) from January 1, 1970 at 0 o'clock (UTC).

"timestamp;convdts=2"

Alphanumeric string in ISO 8601 format

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. 
-3: The KeyName value can only be empty if the associated value to add (DataValue) has the Adelia REF_CLASS type.
-4: The name of the Adelia DataValue type (AdeliaType) is not valid.

     
 

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

 

Click here for more information. 

 


Simple ALPHA type

Example

Adelia 4GL

NUM_BIN_2 retCode
ALPHA(15) name
name = 'Mary'
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'name' name 'alpha' retCode

FreeMarker expression

${name}

Result in template

Mary

 

 

Simple NUM_E(4,2) type

Example

Adelia 4GL

NUM_BIN_2 retCode
NUM_E(4,2) price
price = 12.56
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'key_price' price 'num_e' retCode

FreeMarker expression

${key_price}

Result in template

12.56

 


Simple BOOL type

Example

Adelia 4GL

NUM_BIN_2 retCode
BOOL is_archive
is_archive = *TRUE
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'IsArchive' is_archive 'bool' retCode

FreeMarker expression

${ IsArchive?c }

Result in template

true

↑ Top of page

 

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
IMAGE dot
call_class 'vatoolbx.dll' 'VaToolBxFileToImage' 'c:/dot.png' dot retCode

* the image is converted to a Base64-encoded string
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'dotImg' dot 'image ;convimg=1' retCode

FreeMarker expression

${ dot }

Result in template

iVBORw0KGgoAAAANSUhEUgAAAAkAAAAJCAMAAADXT/YiAAAAGFBMVEX///9SUlKAgIDr6+uBgYFaWlp9fX1WVlZoulyHAAAAJklEQVQImWNgwAqYWVhZmMEsJkZGRjYwixXIYkcTY2ZiZWLGbgQADREASBTqq5EAAAAASUVORK5CYII=

↑ Top of page

 

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
DATE orderDate
orderDate = &ALPHA_TO_DATE('*ISO';'2018-10-31')
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'orderDate' orderDate 'date' 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
DATE orderDate
orderDate = &ALPHA_TO_DATE('*ISO';'2018-10-31')
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'orderDate' orderDate 'date ;convdts=1' 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
DATE orderDate
orderDate = &ALPHA_TO_DATE('*ISO';'2018-10-31')
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'orderDate' orderDate 'date ;convdts=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:
{
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
} *attributes

 

NUM_BIN_2 codeRet
REF_CLASS(Person) aPerson
aPerson = new Person()
aPerson.setname('Mary')
aPerson.setlastName('Smith')
aPerson.setage(18)
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'client' aPerson 'class' retCode

Data model

FreeMarker expression

My name is ${ .data_model.client.name } ${ .data_model.client.lastName }
My name is ${ client.name } ${ client.lastName }

Result in template

My name is Mary Smith
My name is Mary Smith

 

 

Example 2

Adelia 4GL

Person CLASS:
{
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
} *attributes

 

NUM_BIN_2 codeRet
REF_CLASS(Person) aPerson
aPerson = new Person()
aPerson.setname('Mary')
aPerson.setlastName('Smith')
aPerson.setage(18)
call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' *BLANK aPerson 'class' retCode

Data model

FreeMarker expression

My name is ${ .data_model.name } ${ .data_model.lastName }
My name is ${ name } ${ lastName }

Result in template

My name is Mary Smith
My name is Mary Smith

 

 

Example 3

 

Adelia 4GL

Person CLASS:
{
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
} *attributes

Pair CLASS:
{
REF_CLASS(Person) person1 ;
REF_CLASS(Person) person2;
} *attributes

 

NUM_BIN_2 retCode
REF_CLASS(Couple) aCouple
REF_CLASS(Person) aPerson
aCouple = new Couple()
aPerson = new Person()
aPerson.setname('Mary')
aPerson.setlastName('Smith')
aPerson.setage(18)
aCouple.setperson1(aPerson)

aPerson = new Person()
aPerson.setname('Bob')
aPerson.setlastName('Starr')
aPerson.setage(20)
aCouple.setperson2(aPerson)

call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'weddingCouple' aCouple 'class' 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!

 

↑ Top of page

 

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
ALPHA(30) NAME
NUM_BIN_2 Age
LIST studentList NAME Age

NAME = 'Franck Hunter'
Age = 18
Insert_elt studentList
NAME = 'Theresa Black'
Age = 17
Insert_elt studentList
NAME = 'Alexander Faye'
Age = 19
Insert_elt studentList

call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'studentList' studentList 'list' retCode

Data model

FreeMarker expression

Number of students: ${ .data_model.studentList?size}
First student: ${ .data_model.studentList[0].name} , ${ .data_model.studentList[0].age}
Second student: ${ .data_model.studentList[1].name} , ${ .data_model.studentList[1].age}
Third student: ${ .data_model.studentList[2].name} , ${ .data_model.studentList[2].age}

Result in the template

Number of students: 3
First student: Franck Hunter, 18
Second student: Theresa Black, 17
Third student: Alexander Faye, 19


Example 2

Adelia 4GL

Person CLASS:
{
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
} *attributes

 

NUM_BIN_2 retCode
REF_CLASS(Person) aPerson
NUM_P(4,2) avgGrade
LIST studentList aPerson avgGrade

aPerson = new Person()
aPerson.setname('Franck')
aPerson.setlastName('Hunter')
aPerson.setage(18)
avgGrade = 9.8
Insert_elt studentList

aPerson = new Person()
aPerson.setname('Theresa')
aPerson.setlastName('Black')
aPerson.setage(17)
avgGrade = 12.05
Insert_elt studentList

aPerson = new Person()
aPerson.setname('Alexander')
aPerson.setlastName('Faye')
aPerson.setage(19)
avgGrade = 14
Insert_elt studentList

call_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'studentList' studentList 'list' retCode

Data model

FreeMarker expression

Number of students: ${ .data_model.studentList?size}
First student: ${ .data_model.studentList[0].aperson.name} ${ .data_model.studentList[0].aperson.lastName} , ${ .data_model.studentList[0].aperson.age}; ${ .data_model.studentList[0].avggrade}
Second student: ${ .data_model.studentList[1].aperson.name} ${ .data_model.studentList[1].aperson.lastName} , ${ .data_model.studentList[1].aperson.age}; ${ .data_model.studentList[1].avggrade}
Third student: ${ .data_model.studentList[2].aperson.name} ${ .data_model.studentList[2].aperson.lastName} , ${ .data_model.studentList[2].aperson.age}; ${ .data_model.studentList[2].avggrade}

Result in the template

Number of students: 3
First student: Franck Hunter, 18; 9.8
Second student: Theresa Black, 17; 12.05
Third student: Alexander Faye, 19; 14

↑ Top of page

  • Aucune étiquette