XCIDATADEF - Data Definition

#### Search Results

Search

# XCIDATADEF - Data Definition

With an XCIDATADEF control, you can define data structures that are exchanged between a page and its adapter, but which are not visually represented on the page. Examples are Natural control variables, which can be assigned to controls on a page after they have been defined in an XCIDATADEF control. They are not visually represented on the page, but can be evaluated by the application to control the modification status of the page and its controls.

The XCIDATADEF control allows the definition of scalar variables, structures, arrays, structures of arrays and arrays of structures. When an adapter is generated from a page that contains one or more XCIDATADEF controls, corresponding Natural data structures are generated into the parameter data area of the adapter.

The following topics are covered below:

- Example

- Properties

## Example

The following example shows several field controls and a grid control. It uses XCIDATADEF controls to define control variables and assigns these in various ways to the fields and grid elements of the page.

The XML layout definition is:

    <?xml version="1.0" encoding="UTF-8"?>
    <natpage hotkeys="13;onEnter" natsource="CTRCV-A" natsinglebyte="true" natcv="cv-page"
      xmlns:njx="http://www.softwareag.com/njx/njxMapConverter">
        <titlebar name="Control Variable Samples">
        </titlebar>
        <pagebody takefullheight="true">
            <rowarea name="Simple Field With Control Variable">
                <itr>
                    <label name="First Name:" width="80">
                    </label>
                    <field valueprop="firstname" width="200" njx:natcv="cv-firstname">
                    </field>
                    <hdist width="50">
                    </hdist>
                </itr>
                <itr>
                    <label name="Last Name:" width="80">
                    </label>
                    <field valueprop="lastname" width="200" njx:natcv="cv-lastname">
                    </field>
                </itr>
            </rowarea>
            <rowarea name="Grid With Control Variables">
                <rowtablearea2 griddataprop="persons" rowcount="4" width="100%">
                    <tr>
                        <gridcolheader width="30" propref="selected">
                        </gridcolheader>
                        <gridcolheader name="ID" width="25%" propref="id">
                        </gridcolheader>
                        <gridcolheader name="Last Name" width="40%" propref="last">
                        </gridcolheader>
                        <gridcolheader name="First Name" width="35%" propref="first">
                        </gridcolheader>
                    </tr>
                    <repeat>
                        <str valueprop="selected">
                            <selector valueprop="selected" singleselect="true">
                            </selector>
                            <field valueprop="id" width="25%" noborder="true"
                              transparentbackground="true">
                            </field>
                            <field valueprop="last" width="40%" noborder="true"
                              transparentbackground="true" njx:natcv="persons(*).cv-last">
                            </field>
                            <xcidatadef dataprop="cv-last" datatype="C">
                            </xcidatadef>
                            <field valueprop="first" width="35%" noborder="true"
                              transparentbackground="true" njx:natcv="cv-first(*)">
                            </field>
                        </str>
                    </repeat>
                </rowtablearea2>
            </rowarea>
            <rowarea name="Description" height="100%">
                <itr takefullwidth="true" height="100%">
                    <subpage valueprop="infopagename" height="100%" width="100%">
                    </subpage>
                </itr>
            </rowarea>
        </pagebody>
        <statusbar withdistance="false">
        </statusbar>
        <xcidatadef dataprop="cv-firstname" datatype="C">
        </xcidatadef>
        <xcidatadef dataprop="cv-lastname" datatype="C">
        </xcidatadef>
        <xcidatadef dataprop="cv-first" datatype="C" array="true">
        </xcidatadef>
    </natpage>

The above example shows various ways in which control variables can be defined and assigned to controls:

- `cv-page` is a scalar control variable that is assigned to the page as a whole. In the application, it reflects the modification status of the entire page.

- `cv-firstname` and `cv-lastname` are scalar control variables that are assigned to the FIELD controls `firstname` and `lastname`. They reflect the modification status of the respective controls.

- `cv-last` is a control variable that is defined as an element of the grid `persons`. Consequently, it is implicitly an array and is assigned to the element `last` as `persons(*).cv-last`. Each occurrence of `persons(*).cv-last` reflects the modification status of the corresponding occurrence of `persons.last`.

- `cv-first` is an array of control variables that is defined outside the grid `persons`. Consequently, it is assigned to the element `first` as `cv-first(*)`. Each occurrence of `cv-first(*)` reflects the modification status of the corresponding occurrence of `persons.first`. Note the difference to the previous case: because `cv-first(*)` is defined outside the grid `persons`, it is not automatically resized together with `persons.first`. Resizing `cv-first(*)` appropriately is in the responsibility of the application program.

The corresponding adapter code looks as follows:

    DEFINE DATA PARAMETER
    /*( PARAMETER
    1 CV-FIRST (C/1:*)
    1 CV-FIRSTNAME (C)
    1 CV-LASTNAME (C)
    1 CV-PAGE (C)
    1 FIRSTNAME (A) DYNAMIC
    1 INFOPAGENAME (A) DYNAMIC
    1 LASTNAME (A) DYNAMIC
    1 PERSONS (1:*)
    2 CV-LAST (C)
    2 FIRST (A) DYNAMIC
    2 ID (A) DYNAMIC
    2 LAST (A) DYNAMIC
    2 SELECTED (L)
    /*) END-PARAMETER
    END-DEFINE
    ...
    /*( PROCESS PAGE
    PROCESS PAGE (CV=CV-PAGE) U'/njxdemos/ctrlcontrolvar' WITH
    PARAMETERS
     NAME U'firstname'
      VALUE FIRSTNAME (CV=CV-FIRSTNAME)
     NAME U'infopagename'
      VALUE INFOPAGENAME
     NAME U'lastname'
      VALUE LASTNAME (CV=CV-LASTNAME)
     NAME U'persons(*).first'
      VALUE PERSONS.FIRST(*) (CV=CV-FIRST(*))
     NAME U'persons(*).id'
      VALUE PERSONS.ID(*)
     NAME U'persons(*).last'
      VALUE PERSONS.LAST(*) (CV=PERSONS.CV-LAST(*))
     NAME U'persons(*).selected'
      VALUE PERSONS.SELECTED(*) (EM='false'/'true')
    END-PARAMETERS
    /*) END-PROCESS
    ...

The example code is contained in the Natural for Ajax demos as program `CTRCV-P`.

## Properties

Basic
datatype | Data type of the data element. One of the list of valid values. Using the reserved word "type" you can nest multiple XCIDATADEF structures. | Optional | type xs:string xs:int xs:float xs:decimal xs:double xs:date xs:dateTime xs:time xs:byte xs:short xs:boolean ------------------------ N n.n P n.n string n C L
array | If set to true, the XCIDATADEF will be an array. | Optional | true false
arraydimension | If ARRAY is set to TRUE you can specify the array dimension here. Supported values are "1" and "2". The default is "1". | Optional | 1 2
clientdata | Default is false. If set to true then the data is also send to the browser. Usually applications use the default setting. Only set this to true for small data that is really rendered in the browser. | Optional | true false
Natural
njx:natname | If a Natural variable with a name not valid for Application Designer (for instance #FIELD1) shall be bound to the control, a different name (for instance HFIELD1) can be bound instead. If the original name (in this case #FIELD1) is then specified in this attribute, the original name is generated into the parameter data area of the Natural adapter and a mapping between the two names is generated into the PROCESS PAGE statement of the Natural adapter. This mapping must not break a once defined group structure. If for instance a grid control that is bound to a name of GRID1 contains fields that are bound to FIELD1 and FIELD2 respectively, the corresponding njx:natname values may be #GRID1.#FIELD1 and #GRID1.#FIELD2, but not #GRID1.#FIELD1 and #MYGRID1.#FIELD2. | Optional |
njx:natsysvar | If the control shall be bound to a Natural system variable, this attribute specifies the name of the system variable. | Optional |
njx:natsysio | If the control shall be bound to a Natural system variable with the attribute njx:natsysvar, this attribute indicates if the system variable is modifiable. The default is false. | Optional |
njx:natstringtype | If the control shall be bound to a Natural system variable of string format with the attribute njx:natsysvar, this attribute indicates the format of the string, A (code page) or U (Unicode). The default is A. | Optional |
njx:natcv | Name of a Natural control variable that shall be assigned to the control. | Optional |
njx:natcomment | The value of this attribute is generated as comment line into the parameter data area of the Natural adapter, before the field name. The Map Converter, for instance, uses this attributes to indicate a generated statusprop variable to which field the statusprop belongs. | Optional |

### On this page

- Example
- Properties