FIELDSETs are variables which contain a number of fields. Model developers can work with the FIELDSET as a whole or manipulate fields in the FIELDSET as separate TEXT variables.
Note
It's possible to create ÍTP Models that use this functionality with ITP/Workstation, but it's impossible to run them. In order to do this, ITP/Server or ITP/OnLine Server is needed.
Note
Earlier versions of ITP used the deprecated keyword FLDSET to declare a FIELDSET variable.
The ITP/MDK Repository contains Field Sets which are used in Text Blocks and Forms. Every time a model uses a Text Block or Form that refers to a Field Set it must declare a FIELDSET variable with the same name. The contents of this FIELDSET variable are used wherever fields from the Field Set are used. Refer to Inserting a Text Block for more information on using Text Blocks in ITP Model Documents.
It is possible to declare FIELDSET variables which do not have a corresponding Field Set in the ITP/MDK Repository. It is also possible to add fields to a FIELDSET which are not defined in the corresponding Field Set.
FIELDSET variables can be declared anywhere in an ITP model document. FIELDSET names are case sensitive and must match the same conventions as entry names. The names of fields in the FIELDSET must match the same conventions as entry field names.
Example
FIELDSET FieldSet_x
This declares the FIELDSET FieldSet_x. Its contents will be used whenever a Form or Text Block refers to the Field Set FieldSet_x in the ITP/MDK Repository.
You can initialize the FIELDSET during declaration. The possible assignments are described below.
Example
FIELDSET NewFieldSet := ExistingFieldSet (* Another FIELDSET *)
FIELDSET NewFieldSet := text_map (* MAP TEXT *)
FIELDSET NewFieldSet := X0 (* An entry (within a FORALL/WITH loop) *)
FIELDSET NewFieldSet := EXP.Customer (* A specific record *)
WHERE PAR(1) = "1002"
Assigning a FIELDSET to another FIELDSET will first clear the content of the destination FIELDSET before copying all fields from the source FIELDSET.
Example
ASSIGN DestinationFieldSet := SourceFieldSet
The +:= operator can be used to merge the contents of a FIELDSET into another FIELDSET.
Example
ASSIGN DestinationFieldSet +:= SourceFieldSet
If a field exists in both the source and destination FIELDSETs it will be overwritten with the value of the source FIELDSET.
Every field from the Field Set in the ITP/MDK Repository needs to be assigned a value before it can be used in a Text Block. Use <name of the FIELDSET>.<name of the field> to refer to a field and to assign a value to a field. For example, FieldSet_x.Field1 refers for example to field Field1 in FIELDSET FieldSet_x. Assigning a value to a field in a FIELDSET is done in the same way as assigning a value to a variable.
The values assigned to a field in a FIELDSET must be type TEXT.
Example
ASSIGN FieldSet_x.Field1 := "This is the value of Field1"
Note
The new value is assigned to the field Field1 in FIELDSET FieldSet_x. Every occurence of FieldSet_x.Field1 in a Text Block is replaced by "This is the value of Field1" when that Text Block is inserted in the result document.
A FIELDSET can be filled with all database fields from an entry in a single ITP statement by assigning this entry to the FIELDSET. This assignment will first clear the FIELDSET and then create a field in the FIELDSET for each database field in the entry. Numerical database fields are converted to TEXT using the function number. These numbers are always represented with two decimals.
There are two possible ways to assign an entry to a FIELDSET. First, assign an entry using the identification within a FORALL/WITH loop. Second, assign a specific record directly to the FIELDSET using a WHERE clause.
Example 1
FORALL X0 IN EXP.Customers DO
FIELDSET Customer := X0
OD
This example loops through the records in the EXP.Customers entry and assigns the fields from each EXP.Customer record to the Fieldset Customer during the loop. This construction can be used with both singular and plural entries.
Example 2
ASSIGN FieldSet_x := EXP.Customer WHERE PAR(1) = 1002
This example retrieves the entry Customer for customer 1002. If a record is retrieved successfully it creates a field for each database field in this entry in the FIELDSET FieldSet_x and fills it with the value from the record. Only singular entries can be assigned to a FIELDSET using the WHERE clause.
Note
FIELDSET assignments are generated during the compilation of the ITP Model. If the entry changes in the DID at any time the model has to be recompiled to reflect these changes.
A TEXT MAP can be assigned directly to a FIELDSET. This assignment will clear the FIELDSET and then create a field in the FIELDSET for each key in the TEXT MAP.
Example
MAP TEXT text_map
ASSIGN text_map [ "A" ] := "B"
ASSIGN FieldSet := text_map
This example will clear the FIELDSET FieldSet and then create the field FieldSet.A with value "B".
The +:= operator can be used to merge the contents of a TEXT MAP into a FIELDSET without deleting existing fields.
Example
ASSIGN FieldSet +:= text_map
This example adds the contents from text_map to the FIELDSET FieldSet. If the TEXT MAP contains a key that already exists as a field in FieldSet it will overwrite this field with the value from the TEXT MAP.
A FIELDSET can be assigned directly to a TEXT MAP. This assignment will clear the TEXT MAP and then create an entry in the TEXT MAP for each field in the FIELDSET. The field name in the FIELDSET is used as the key for this entry.
Example
FIELDSET FieldSet
ASSIGN FieldSet.A := "B"
ASSIGN text_map := FieldSet
This example will clear the TEXT MAP text_map and then create the value text_map["A"] with value "B".
A field from a FIELDSET can be used anywhere in the model document where ITP expects a value with type TEXT.
Example
ASSIGN FieldSet.Field := "42"
ASSIGN address_line[3] := FieldSet.ZIPCode + " " + FieldSet.City
ASSIGN variable := lookup_map [ FieldSet.Key ]
#@(FieldSet.Field)#
If a field is used that is not in the FIELDSET it will be treated as if the field was assigned an empty TEXT value.
The function clear_fieldset can be used to clear all fields from a FIELDSET. The result of this function is of type BOOL; if the FIELDSET was cleared successfully the function returns TRUE, otherwise it will return FALSE.
Example
BOOL success := clear_fieldset(FieldSet)
The ITP/MDK Repository version 3.2.0 introduced a WYSIWYG Form Editor for Forms. These Forms are not included into an ITP model during compilation but retrieved by ITP/Server from the ITP/MDK Repository database each time a model is run.
FIELDSET variables are used to dynamically change the content of these Forms and to receive the answers provided by the end user. Refer to FORM for more information on dynamic Forms. Any references to fields in fixed text on the forms are inserted directly from the FIELDSETs.
The following table shows the format used to pass defaults and answers between the model and the dynamic Forms. Because FIELDSET values always have type TEXT some values must be encoded.
|
Content |
Sample content |
|---|---|---|
Text Question |
Any text. |
"The Quick Brown Fox Jumps Over The Lazy Dog" |
Date Question |
A date in "YYYYMMDD" format. |
"20080229" |
Choice Question |
One or more values in comma-separated format. |
"first value,second value,third value,last value" |
Checkbox Question |
"Y" for checked, "N" for unchecked. |
"Y" |
Number Question |
A number, formatted in the active output language. |
"3.1415" |