XMLSTART

Copyright © Cloud Software Group, Inc. All Rights Reserved

XMLSTART

Generates an XML document based on the passed data access arguments. (C)

Invocation

CALL XMLSTART(xmldocname, predicate, parm)

xmldocname

The name of the XML document to be generated.

predicate

The selection criteria for the table.

parm

The names of the table parameters, if any, for the data to be returned.

Usage Notes

•

In addition to its parameters, XMLSTART requires that you declare and initialize several variables within the scope of the rule to be invoked.

•

XMLSTART can output the generated XML document to one of the following:

−

Multiple rows of a particular table, inserting portions of the XML document into a particular field of the table

−

A data set or file

−

A region in memory

•

The values to assign the required variables depend on the destination of the generated XML document. See the examples for details.

Exceptions

ECTSERROR

An error occurred during the generation of the XML document.

Examples

Example 1: Populate rows of a table with portions of an XML document.

Here is the table definition in this example:

COMMAND==> TABLE DEFINITION

Table: XMLDATA Type: TEM Unit: USER40 IDgen: Y

Parameter Name Typ Syn Len Dec Class ' Event Rule Typ Acc

---------------- - -- --- -- - ' ---------------- - -

_ LOCATION I C 16 0 L ' _

_ ' _

Field Name Typ Syn Len Dec Key Ord Rqd Default Reference

---------------- - -- ----- -- - - - ---------------- ----------------

_ KEY I B 4 0 P

_ TEXT S V 60 0

_

The following generic rule populates the table:

RULE EDITOR ===> SCROLL: P

XML2TABLE(TABLESPEC, FIELDSPEC, XMLDOCNAME, PREDICATE, PARM);

_ LOCAL DOCOFFSET, ECTSMODE, WRITETOMEM, WRITETOEXP;

_ ---------------------------------------------------------------------------

_ ------------------------------------------------------------+--------------

_ CALL XMLSTARTSETDEST(TABLESPEC, FIELDSPEC); | 1

_ WRITETOMEM = 'N'; | 2

_ WRITETOEXP = 'N'; | 3

_ CALL ECTSNLSINIT; | 4

_ CALL XMLSTART(XMLDOCNAME, PREDICATE, PARM); | 5

_ ---------------------------------------------------------------------------

The following invokes the generic rule:

RULE EDITOR ===> SCROLL: P

T_XML2TABLE;

_

_ ---------------------------------------------------------------------------

_ ------------------------------------------------------------+--------------

_ CALL XML2TABLE('XMLDATA', 'TEXT', 'BOOKS', | 1

_ 'GENRE=''Science Fiction''', ''); |

_ FORALL XMLDATA : | 2

_ CALL MSGLOG(XMLDATA.TEXT); |

_ END; |

_ ---------------------------------------------------------------------------

The result from the session log is as follows:

<?xml version="1.0" ?>





<bookstore>

<book KEY="3">

<genre>Science Fiction</genre>

<bktitle>Stranger In A Strange Land</bktitle>

<author_ln>Heinlein</author_ln>

<author_fn>Robert A</author_fn>

<price>7.99</price>

</book>

<book KEY="4">

<genre>Science Fiction</genre>

<bktitle>I, Robot</bktitle>

<author_ln>Asimov</author_ln>

<author_fn>Isaac</author_fn>

<price>5.99</price>

</book>

</bookstore>

Example 2: Output an XML document to a file.

Here is a generic rule for outputting an XML document to a data set or file:

RULE EDITOR ===> SCROLL: P

XML2DATASET(DSN, XMLDOCNAME, PREDICATE, PARM);

_ LOCAL DOCOFFSET, ECTSMODE, WRITETOMEM, WRITETOEXP;

_ ---------------------------------------------------------------------------

_ ------------------------------------------------------------+--------------

_ WRITETOMEM = 'N'; | 1

_ WRITETOEXP = 'Y'; | 2

_ CALL ECTSNLSINIT; | 3

_ CALL @OPENDSN(DSN); | 4

_ CALL XMLSTART(XMLDOCNAME, PREDICATE, PARM); | 5

_ CALL @CLOSEDSN; | 6

_ ---------------------------------------------------------------------------

The following invokes the generic rule for generating the XML document in ASCII on an Open Systems platform:

RULE EDITOR ===> SCROLL: P

T_XML2DATASET;

_ LOCAL OLD_DSBIFTYPE;

_ ---------------------------------------------------------------------------

_ ------------------------------------------------------------+--------------

_ OLD_DSBIFTYPE = $GETOPT('DSBIFTYPE'); | 1

_ CALL $SETOPT('DSBIFTYPE', 'LINE_SEPARATED_ASCII'); | 2

_ CALL XML2DATASET('XML.BOOKS.OUTPUT', 'BOOKS', | 3

_ 'GENRE=''Science Fiction''', ''); |

_ CALL $SETOPT('DSBIFTYPE', OLD_DSBIFTYPE); | 4

_ ---------------------------------------------------------------------------

The contents of the resulting file XML.BOOKS.OUTPUT is the same as the contents of the session log in Example 1.

Example 3: Output an XML document to a region of memory.

Here is a generic rule for generating an XML document into memory:

RULE EDITOR ===> SCROLL: P

XML2MEMORY(ADDRESS, LENGTH, XMLDOCNAME, PREDICATE, PARM);

_ LOCAL DOCOFFSET, ECTSMODE, WRITETOMEM, WRITETOEXP, CURRENTPOINTER,

_ STORAGEEND, ENCODING, ITEMCOUNT;

_ ---------------------------------------------------------------------------

_ ------------------------------------------------------------+--------------

_ WRITETOMEM = 'Y'; | 1

_ WRITETOEXP = 'N'; | 2

_ CALL ECTSNLSINIT; | 3

_ CURRENTPOINTER = ADDRESS; | 4

_ STORAGEEND = ADDRESS + LENGTH; | 5

_ ENCODING = 'ASCII'; | 6

_ ITEMCOUNT = 0; | 7

_ ECTS_TOC.ITEMCOUNT = 0; | 8

_ CALL XMLSTART(XMLDOCNAME, PREDICATE, PARM); | 9

_ RETURN(ITEMCOUNT); | A

_ ---------------------------------------------------------------------------

The following shows the generic rule and retrieves and displays the generated XML document through a MAP table:

RULE EDITOR ===> SCROLL: P

T_XML2MEMORY;

_ LOCAL ITEMS, ADDRESS;

_ ---------------------------------------------------------------------------

_ ------------------------------------------------------------+--------------

_ @MAP.SIZE = 4096; | 1

_ INSERT @MAP('TRANSACTION'); | 2

_ ADDRESS = @MAP.ADDRESS; | 3

_ ITEMS = XML2MEMORY(ADDRESS, @MAP.SIZE, 'BOOKS', | 4

_ 'GENRE=''Science Fiction''', ''); |

_ UNTIL EQ : | 5

_ CALL @EQ(ITEMS, 0); |

_ GET XMLMEM(ADDRESS) WHERE KEY = 1; |

_ CALL MSGLOG(HEADSTRING(XMLMEM.TEXT, XMLMEM.LENGTH)); |

_ ADDRESS = ADDRESS + XMLMEM.LENGTH + 2; |

_ ITEMS = ITEMS - 1; |

_ END; |

_ ---------------------------------------------------------------------------

Here is the definition of the MAP table:

COMMAND==> TABLE DEFINITION

Table: XMLMEM Type: MAP Unit: USER40 IDgen: Y

Parameter Name Typ Syn Len Dc Cls Reference ' Event Rule Typ Acc

---------------- - -- --- -- - ---------------- ' ---------------- - -

_ ADDRESS B 4 0 A ' _

_ LOCATION I C 16 0 L ' _

_ ' _

------ EXTERNAL ------|---------- Metadata Definition ------

Field Name Xsyn Xlen Xdec Offset Key Typ Syn Len Dec Rqd Default

---------------- ---- ----- -- ------ - - -- ----- -- - -------------

_ KEY B 4 0 0 P I B 4 0

_ LENGTH B 2 0 0 B 2 0

_ TEXT J 80 0 2 V 80 0

_

The contents of the session log are the same as in Example 1.

xmldocname	The name of the XML document to be generated.
predicate	The selection criteria for the table.
parm	The names of the table parameters, if any, for the data to be returned.