ADELIA |
VADELIA |
SADELIA |
WADELIA |
MADELIA |
(I/B) |
(I/B) (C/S) |
(B) (S) |
(I/B) (C/S) |
(I) (C/S) |
Section for use
All.
Syntax
XML_OPEN XmlIdentifierName OpenMode XmlDocument version encoding DocType Verification Standalone
OpenMode |
→ |
*READ|*WRITE|*READ_WRITE |
XmlDocument |
→ |
XMLFileName | DocumentVariable |
version |
→ |
*VERSION(<alpha cst> | <alpha variable>) | None |
encoding |
→ |
*FILE_ENCODING(<alpha cst> | <alpha variable>) | *CONV_UTF8 | None |
DocType |
→ |
*DOCTYPE(SystemDtdName | PublicDtdName Public_Dtd_URI) | None |
Verification |
→ |
*CHECK | *CHECK(<Alpha cst> | <Alpha variable>) | None |
SystemDtdName |
→ |
<Alpha cst> | <Alpha variable> |
XMLFileName |
→ |
<Alpha cst> | <Alpha variable> |
DocumentVariable |
→ |
*DOC_VAR(<AlphaVariable>|<ImageVariable>) | <ImageVariable> |
Autonomous |
→ |
*STANDALONE | None |
Description
Opens the XML file whose name is contained in an alphanumerical constant or variable. If *DOC_VAR or an IMAGE variable is specified, the instruction does not relate to a file - it is the IMAGE variable or the alphanumerical variable that contains the XML document.
In read and read/write modes you must specify variable names for the optional parameters *VERSION, *FILE_ENCODING and *DOCTYPE, into which the XML document's version, coding and type definition (DTD) will be loaded.
In write mode, the file is created if it does not already exist, or reinitialized if it does. The version (*VERSION parameter), encoding (*FILE_ENCODING parameter) and document type definition (Dtd: *DOCTYPE parameter) can be specified, using alphanumerical constants or variables. If *CHECK is specified, the check will be performed when the XML file is closed. The validation will be performed relative to the dtd file if one has been specified, or by schema if not.
The default encoding system is UTF-8.
The *CONV_UTF8 encoding parameter can only be used if the XML document is contained in an alphanumeric variable (*DOC_VAR (<Alpha variable>)). With this parameter, in reading mode, the content of the AlphaVariable "XML document" variable is converted from the local code page into UTF-8 encoding before being sent to the XML parser which will analyse it as an XML document encoded in UTF-8. In writing mode, the document is managed as an UTF8-encoded document, but at closure the XML document converted from UTF-8 to local code page is retrieved in AlphaVariable.
If the XML identifier is a *SEQ identifier, the only permitted mode is *READ, the *VERIFY option is unavailable and it is not possible to set an image variable as a document to open.
The *STANDALONE parameter allows to force the declaration standalone="yes" in the XML document. It is used to specify that the document is autonomous (if the XML document has a DTD and the standalone="yes" is used, the DTD is used only for validation.
Note:
For DTD files and XML schemas referenced by a simple file name:
- On Windows platforms, the DTD file referenced in the DOCTYPE, or the XML schema referenced in either of the noNamespaceSchemaLocation or schemaLocation attributes must be present in the current directory or in the same directory as the XML file.
- On Java platforms:
- the DTD file referenced in the DOCTYPE must be in the user's current directory,
- the XML schema file referenced in either of the noNamespaceSchemaLocation or schemaLocation attributes must be present in the user's current directory, or in the same directory as the XML file.
When this instruction is executed, the *RETURN_CODE reserved word can take the following values:
0 (*NORMAL) |
File opened successfully. |
1 |
Error: File already open. |
2 |
File not found or non-compliant with XML syntax. On Java platforms, this error may also occur when the DTD file specified in the file or in the instruction was not found. |
9 |
Error: File does not comply with the specified Dtd file's rules. |
12 |
Error: The Dtd file specified in the file or instruction was not found (Windows platforms). |
20 |
The file was opened but was not checked despite *CHECK being specified, because the file does not have a DOCTYPE section or has no schema. |
21 |
Error: the schema file specified in the XML file could not be found or is incorrect. |
22 |
Validating the XML file based on its schema generated errors. |
Example
XML_OPEN Xml1 *READ 'C:\temp\MyFile.xml' VERSION(WVERSION)
FILE = 'c:\tmp\debugjca.xml'
XML_OPEN xml1 *WRITE FILE *VERSION('1.0') - *DOCTYPE('AdelDBG.dtd') *CHECK
ALPHA(2000) XML_DOC
XML_OPEN Xml1 *READ *DOC_VAR(XML_DOC) *VERSION(WVERSION)
Other example:
File XML 'c:\temp\Myfile.xml', comprising:
<?xml version="1.0" ?>
<root xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation="control.xsd">
...
</root>
XML_OPEN Xml1 *READ 'c:\temp\Myfile.xml' *CHECK
In order for the verification on the control.xsd XML schema file to be successfully completed, this file must be located:
- either in the application's current directory (or the user's current directory in Java; user.dir system property),
- or in the c:\temp directory (i.e. the directory containing the Myfile.xml file).
Alternatives are possible to precisely specify the location of the XSD schema file:
(1) Using an absolute path
Example:
xsi:noNamespaceSchemaLocation="c:\myxsd\control.xsd"
(2) Using a URL
Example:
xsi:noNamespaceSchemaLocation="http://mydomain/myxsd/control.xsd"
(3) Specifying the path directly in the program
Example:
XML_OPEN Xml1 *READ 'c:\temp\Myfile.xml' *CHECK( 'http://mydomain/myxsd/control.xsd ')
In this case, you can override the Myfile.xml tags (if any) to force verification in relation to the specified XSD file.