Previous Topic Next topic Print topic


MF 

XML Syntax - WRITE Statement

The WRITE statement in XML syntax writes an XML document to an I/O stream or add an XML element to the in-memory representation of the XML document.

Format


XML Syntax - WRITE statement

Syntax Rules:

  1. Record-name-1 is the name of an 01 level group item defined in an XD record declaration within the Data Division .
  2. Data-name-1 can be qualified, and references a data item whose declaration includes an IDENTIFIED BY clause and is included in the XD record declarations for file-name-1.

General Rules:

  1. WRITE without KEY IS takes the record specified, creates a new internal representation (if one does not exist already) and then writes that internal representation to the stream.
  2. If the following conditions are met when an XML file is opened I-O:
    • an internal representation is created by a READ statement
    • the internal representation is modified by any combination of WRITE, REWRITE, or DELETE KEY statements
    • WRITE without the KEY IS clause is performed
    The current contents of the record specified are ignored; instead, the internal representation as established by the READ and modified by the WRITE, REWRITE, or DELETE KEY statements, is written to the stream.
  3. WRITE KEY IS PLAIN-TEXT, data-name-2 or literal-1 is a string value which contains plain text to be output to the XML stream.
  4. WRITE KEY IS PLAIN-TEXT can be decoration such as "Content-type: text/xml."
  5. No stream I/O is actually performed by the WRITE KEY IS statement.
  6. AT END and INVALID KEY are not supported. Use the XML file status variable instead.
  7. WRITE KEY IS adds the node specified to the internal representation of the XML document immediately after the current position. If any containing nodes are required for the node specified, these are also created in the internal representation.
  8. If ALL is specified, any contained nodes are also added to the internal representation of the XML document. Otherwise only the specific node and its attributes and data are added. No stream I/O is performed.
  9. WRITE KEY IS PROCESSING-INSTRUCTION causes an XML processing-instruction node to be added immediately after the current position. When using sequential I/O, where your other WRITE statements have no usage of the KEY clause, a processing instruction is either written before or after the entire XML record, depending on order of execution. When using random I/O, you can write a processing instruction immediately before or after any pre-existing node, using the following sequence:
    START  xml_file_record KEY IS xml_file_node
        IF write-after
           READ xml_file_record NEXT KEY IS xml_file_node
        END-IF
        WRITE  xml_file_record KEY IS PROCESSING-INSTRUCTION 'processing-id processing-data'

    For example, this technique is useful when dealing with the root node and the processing instruction 'xml version="1.0"'.

  10. When using WRITE KEY IS PROCESSING-INSTRUCTION:
    • Data-name-2 is a defined level 78 or a simple data name.
    • Literal-1 is a string value which contains an XML-specific processing instruction. Upon output, this string is decorated with the XML delimiters '<? 'and '?>'.
  11. WRITE KEY IS PLAIN-TEXT adds a plain text node immediately after the current position. When using sequential I/O, where your other WRITE statements have no usage of the KEY clause, plain text will either be written before or after the entire XML record, depending on order of execution. When using random I/O, you can write plain text immediately before or after any pre-existing node, using the following sequence:
    START  xml_file_record KEY IS xml_file_node
        IF write-after
           READ xml_file_record NEXT KEY IS xml_file_node
        END-IF
        WRITE  xml_file_record KEY IS PLAIN-TEXT  'processing-id processing-data'

    This technique is useful when your XML program needs to 'decorate' an XML record with plain text data, for example, specifying "Content-type: text/xml" when operating in a CGI context.

  12. If the internal representation of the XML document is modified through the use of WRITE KEY, REWRITE KEY, or DELETE KEY, and the internal representation is cleared with either a CLOSE or READ (no key) statement, then the CLOSE or READ statement returns a status of -10, indicating the operation succeeded but no write was done.
Previous Topic Next topic Print topic