xmlsave
Place component data in an XML stream.
xmlsave{/mod}{/one}{/dtd | /ref}{/incldefmap}{/root} XmlTarget,DTDname {,DTDmapping}
Example: xmlsave MYSTREAM, "DTD:ABCDTD.ABC"
Qualifiers
| Qualifier | Description |
|---|---|
| /mod | Includes only modified occurrences in the XML stream |
| /one | Includes only current outer occurrence (with all inner occurrences) in the XML stream |
| /dtd | Includes the DTD in the XML stream |
| /ref | Includes the URI location of the DTD in the XML stream |
| /incldefmap | Uses the default DTD mapping defined in the DTD Editor |
| /root | Excludes the XML version declaration from the saved output |
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| XmlTarget | String | Field, variable, or parameter for the XML stream |
| DTDName | String | DTD used for the XML stream, in the
following format: {DTD:}Name.Model
|
| DTDMapping | String | Uniface list mapping XML elements to Uniface fields and entities |
Return Values
| Value | Meaning |
|---|---|
<0 |
An error occurred. $procerror contains the exact error. |
0
|
XML stream successfully created |
>0 |
XML stream created, 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. |
| 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. |
-1504
|
<UXMLERR_VALIDATE>
|
An error occurred during validation of an XML stream. |
-1505
|
<UXMLERR_TRANSFORM>
|
An error occurred during transformation of an XML stream. |
-1506
|
<UXMLERR_FIELD_NOTAVAIL>
|
A mandatory field is not available in the field list of the entity. In the DTD, such fields must be followed by a question mark (?). |
Use
Allowed in all component types.
Description
The xmlsave statement writes all occurrences on the component (connected or disconnected) to an XML stream. The stream is built from the complete hitlist, including occurrences currently marked for deletion. Occurrences and fields are selected from the data based on the mapping and switches used by the xmlsave statement.
Note: Only database and non-database fields are allowed in XML streams. The value of a static field or control field cannot be included into an XML stream when using xmlsave.
For more information, see Occurrence Metadata for Reconnect .
State Information Generated by xmlsave
xmlsave adds data processing information to the data as XML attributes. When loading XML data into the component (using xmlload), Uniface extracts the processing information and saves it as attributes of disconnected occurrences and fields.
xmlsave generates the following state information:
| $occstatus | $occmod | $storetype | $occdel |
XML state attribute
|
Remarks |
|---|---|---|---|---|---|
""
|
0
|
0
|
0
|
"est"
|
No modified existing occurrence, reconnected |
""
|
1
|
0
|
0
|
"mod"
|
Modified existing occurrence, reconnected |
""
|
1
|
1
|
0
|
"new"
|
New occurrence, always not reconnected |
""
|
X
|
X
|
1
|
"del"
|
Deleted occurrence, reconnected |
"est"
|
1
|
1
|
0
|
"mod"
|
Existing occurrence, no reconnect. XML
state attribute changes to "mod" |
"mod"
|
1
|
1
|
0
|
"mod"
|
Modified occurrence, no reconnect. XML
state attribute stays "mod" |
"new"
|
1
|
1
|
0
|
"new"
|
New occurrence, no reconnect. XML
state attribute stays "new" |
"del"
|
1
|
1
|
0
|
"del"
|
Deleted occurrence, no reconnect. XML
state attribute stays "del" |
"est"
|
X
|
X
|
1
|
"del"
|
Deleted occurrence which was Existing, no
reconnect. XML state attribute changes to "del" |
"mod"
|
X
|
X
|
1
|
"del"
|
Deleted occurrence which was Modified, no
reconnect. XML state attribute changes to "del" |
"new"
|
X
|
X
|
1
|
—
|
Deleted occurrence which was New, no
reconnect. XML state attribute can be removed |
"del"
|
X
|
X
|
1
|
"del"
|
Deleted occurrence which was already
deleted, no reconnect --> state attribute stays deleted
|
Note: If $occstatus is not empty,
this could mean that the occurrence is not reconnected . To be compatible, disconnected occurrences
with a status "est" will be changed into "mod", to force
reconnection with database.
Triggers Fired by xmlsave
The following triggers are fired by the xmlsave statement and can be used to customize the process of saving a component into an XML stream:
- trigger preSerialize—fired immediately before an occurrence is saved from a component into a disconnected record set. The occurrence is available and can be examined. For example, an occurrence can be excluded from the save, or the value for a derived field can be calculated.
- trigger postSerialize—fired immediately after an occurrence is saved from a component into a disconnected record set.
Mapping Data Between Elements and Fields and Entities
The structure of the XML stream is defined by the DTD specified in DTDName. Uniface maps field values to XML elements in the stream using a combination of the local and default mapping and name matching. For more information, see Mapping Between Uniface and XML Streams.
| Rule | Uniface item | XML stream item | Example element |
|---|---|---|---|
| Entity | Entity | Entity.Model | <UCDTYP.DICT>
|
| Field | Field | Field | <UDESCR>
|
| Non-unique field | Non-unique field | Field.Entity.Model | <UDESCR.UFORM.DICT>
|
Uniface applies the non-unique field naming rule when two or more entities in the same DTD have fields with identical names. In these cases, the first field added to the stream is generated using the field rule, subsequent fields using the same name in other entities are generated using the non-unique field rule .
store/complete before xmlsave
If you use store prior to
xmlsave, the hitlist is truncated and the saved XML stream can contain empty
new occurrences. When the data is subsequently stored in the database (using
xmlload and reconnect, this causes a Key not
complete or Subfields are required error.
To prevent the hitlist being truncated, use either store/complete or use clear then retrieve.
Creating and Sending an XML Stream
The following operation creates an XML stream
from a component's data structure, and sends the XML stream as an OUT parameter.
operation XMLOUT ; This operation saves data to XML. params xmlstream [DTD:ABCDTD.ABC] MYSTREAM : OUT endparams clear retrieve xmlsave MYSTREAM, "DTD:ABCDTD.ABC" ...
