xmlload

Load data from an XML stream into occurrences drawn on the component.

xmlload{/incldefmap}{/noprofile}  XmlSource,DTDName  {,DTDMapping}

Example: xmlload MYSTREAM, "DTD:ABCDTD.ABC"

Qualifiers

Qualifiers
Qualifier Description
/incldefmap Uses the default DTD mapping defined in the DTD Editor.
/noprofile Does not convert escape sequences for profile characters and subfield separators to the corresponding profile character of subfield separator during xmlload.

Parameters

Parameters
Parameter Data Type

Description
XmlSource String

Name of the field, variable, or parameter containing the XML stream.

DTDName String

DTD used to validate the XML stream, in the following format:

{DTD:}Name.Model

  • DTD:—specifies that the XML stream is defined using a DTD (this is to ensure compatibility with future developments in the XML standard).
  • Name—name of the DTD as specified in the application model.
  • Model—name of the DTD"s application model.
DTDMappaing String Uniface list mapping XML elements to Uniface fields and entities

Return Values

Values returned in $status
Value Meaning
<0 An error occurred. $procerror contains the exact error.
0 XML stream successfully loaded
>0 XML stream loaded, but could not find all the field and entity names specified in the default and local mappings. For each field not found, $status is incremented by 1. More information is available in the message frame if the assignment setting $TEST_MODE_COMPONENTS is set.
Values commonly returned by $procerror for xmlload
Value Error constant Meaning
-1500 <UXMLERR_DTD_NOTFOUND> A DTD could not be located.
-1501 <UXMLERR_DTD_INVALID> There is a syntax error in the DTD.
-1502 <UXMLERR_GENERATION> An error occurred during generation of an XML stream.
-1503 <UXMLERR_PARSE> An error occurred during parsing of an XML stream.

Use

Allowed in all component types.

Description

xmlload transfers data from an XML stream into a component. The data is loaded directly into the component's data structure. xmlload does not interpret or initiate validation of data, so the data loaded by xmlload can include duplicates of occurrences already within the component, as well as occurrences marked for deletion.

All occurrences loaded from an XML stream (including occurrences marked for deletion) are displayed on forms and accessible in ProcScript.

Note:  Only database and non-database fields are allowed in XML streams. The value of a static field or control field cannot be loaded when using xmlload.

Reconnect Loaded Data

After every xmlload statement, you should use a reconnect or retrieve/reconnect statement to reconnect the loaded data with the data in the component and the database (if connected). The reconnect process removes duplicates of occurrences, removes occurrences marked for deletion from the component, and sets the appropriate modification flags. For more information, see Reconnect Process.

Note:  Use clear before data retrieved from a database is uploaded on the client, so all occurrences have the required initial (unmodified) state.

Triggers Fired by xmlload

The xmlload statement fires the following triggers that can be used to customize how an XML stream is loaded into a component:

  • trigger preDeserialize—fired immediately before an occurrence is loaded into a component. The new occurrence is not yet available and cannot be accessed.
  • trigger postDeserialize—fired immediately after an occurrence is loaded into a component, and after all error triggers caused by validation errors. The new occurrence is available and can be accessed. For example, use this trigger if an occurrence can be discarded, or the value for a derived field can be calculated.

The xmlload statement fires the error triggers, which can be used to display errors:

  • The entity-level error trigger is fired if the valerr attribute is present in an occurrence element of the XML stream. It is fired immediately after the occurrence is loaded. The new occurrence is available and can be accessed.

    $occproperties returns an associated list of occurrence properties, including the property with id errormsg which contains the validation error. The validation error can be used to display the error.

  • The field-level error trigger is fired if the valerr attribute is present in a field element of the XML stream. Ii is fired after the occurrence is loaded from the XML stream into the component and after any occurrence-level errors. The data of the field is available and can be accessed.

    $fieldproperties returns an associated list of field instance properties, including the property with id errormsg which contains the validation error. The validation error can be used to display the error.

For more information, see trigger error .

Receiving an XML Stream

The following code shows an operation that receives an XML stream, and loads the data from the XML into the component’s data structure. 

operation XMLIN
; This operation receives and
; reconnects an XML stream.

params
   xmlstream [DTD:ABCDTD.ABC] MYSTREAM : IN
endparams

clear
xmlload MYSTREAM, "DTD:ABCDTD.ABC"
retrieve/reconnect
...

Related Topics