A : The most likely cause of this error is that the original document in UTF-8 had an XML declaration statement that looked something like this:

<?xml version="1.0" encoding="IBM-1026"?>

When you convert this from UTF-8 to IBM-1026 the double quote does not convert to a quotation mark that can be understood by the parser when it is trying to determine the encoding of the document from the XML declaration statement.

In order for this to work you must change the double quotes to single quotes on the XML declaration statement and then convert the file to IBM-1026. The single quotes are needed on the XML declaration statement so the parser can figure out the encoding of the document. The rest of the document may have double quotes because they will be understood once the parser is able to determine the encoding the document is in.

If you have a document that is in IBM-1026 and you did not convert it from another encoding you should try to edit it and change the XML declaration statement to something like this:

<?xml version='1.0' encoding='IBM-1026'?>

The single quotes should work and only need to be put on the XML declaration statement. The rest of the document can be left unchanged.

This problem may also be seen when using the IBM-1155 codepage.

A : The most likely cause is that your XML declaration statement looks like this:

<?xml version="1.0" standalone="no" encoding="ibm-1047"?>

You must change this so that the "encoding" follows the "version" and looks like this:

<?xml version="1.0" encoding="ibm-1047" standalone="no"?>

A : gmake is used to build the samples. It is not required if you determine the parameters and environment variables and invoke c89 by command. The Toolkit provides the lib and include directories which can readily be included using any UNIX build mechanism just as with any other api. However, all our instructions and files we ship assume that the developer will use gmake.

A : The XML Parser for z/OS, Java Edition is able to run with IBM's enterprise transaction processing platforms, such as CICS 2.2. Both parser editions can run be used in the IMS environment.

Additionally, the XML Parser for z/OS, Java Edition can run under WebSphere Application Server for OS/390. Use of the IBM Common Connector Framework, which is supported by WebSphere Application Server, also provides interoperability with IBM's enterprise transaction processing platforms.

The XML Parser for z/OS, C++ Edition can be invoked by most programs that can access C++ code running under z/OS's Language Environment^(R). It can also be invoked from a C or C++ DB2 stored procedure.

The XML Parser for z/OS, C++ Edition supports invocation under Unix System Services. It also supports invocation from programs running in native/batch MVS environments, with either posix=on or posix=off, but in the native/batch environment, it does not support multi-threading. CICS TS 3.1 and higher is supported.

A : See the components page for a full listing of supported specifications.

A : It is still possible to use a different version of the Java XML Parser or XSLT Processor than the one shipped with the SDK. You may specify a "java.endorsed.dirs" system property on the java command to specify a directory to look in before any others. For example :

 
      java -Djava.endorsed.dirs=/usr/lpp/ixm/IBM/xml4j-4_2 org.apache.xerces.impl.Version

would return "XML4J 4.2.6", the latest level of service, which is the version that ships in that subdirectory. If you entered :

      java org.apache.xerces.impl.Version

this would return the version in the SDK. To run the sax.Counter sample in Toolkit V1.6 you would enter the following :

      java -Djava.endorsed.dirs=/usr/lpp/ixm/IBM/xml4j-4_2 sax.Counter personal.xml

For more information on XML and the Java 1.4 SDK, see the additional FAQ.

A : First consider the built-in support for XML parsing in the Enterprise COBOL and PL/I parsers. This support has some limitations (for example, it does not support document validation) and only supports a SAX-like API model (not a DOM model), but it does provide high performance native language XML parsing. (Note: this compiler support is not associated in any way with the XML Toolkit.) If this support does not meet your requirements, you will need to do some integration work by processing the XML data stream in either a C++ or Java program which then communicates with your COBOL or PL/I program. Note that the C++ parser and XSLT processor in the XML Toolkit is not supported on CICS TS releases prior to CICS TS 3.1.

A : The challenge of interlanguage communication (PL/I and C++, in your case) is error handling. The errors documented in the parser APIs thrown by the parser are expected to be handled by the application and you might not be able to catch them in the PL/I program. An option to get around this problem is for your PL/I program to call a C++ "XML processor" which will invoke the parser. The "XML processor" would be able to catch exceptions thrown by the parser before returning to PL/I caller. You must set the Fixed-point-overflow mask bit in the PSW (bit 20) on before the call to the parser is made and then have them reset the mask bit after the parser is done but before returning to PL/I. Failure to set and reset this bit will result in an ABEND0C8 Fixed-point-overflow exception. Refer to Language Environment Writing Interlanguage Communication Applications for more information.

A : IBM recommends using the V2R10 C++ compiler. Changes were made between versions and releases of compilers. If your application does not compile with the z/OS 1.2.0 C++ compiler, it may be a migration problem, or an error in your program that surfaces as result of a new feature added in the compiler. See the appropriate version of C/C++ Compiler and Run-Time Migration Guide for the Application Programmer for the release of z/OS you are using for more information.

export _CXX_CVERSION="0x220a0000"

A : Yes, but you need to use the V2R10 compiler.

A :The java support is no longer included because it is part of the SDK 1.4. In answer to the second part of the question, current applications that depend on the Java support in prior Toolkit releases will continue to run without change, because those releases are not removed by installing Toolkit V1.8 or V1.7.

A : The "XMLParserAPIs.jar" file has been deprecated and is being replaced by the "xml-apis.jar" file. You should start using "xml-apis.jar" on your CLASSPATH.

A : XML Parser for z/OS, Java Edition V1.4, V1.5 and V1.6 have been tested to validate and run on Java 1.3.1. XML Parser for z/OS, Java Edition has been tested to validate and run on Java 1.4 for all active editions.

A : If you are on Java 1.3.1, you can try issuing the following command :

   java org.apache.xerces.impl.Version    

If you are not using the correct parser you need to update your CLASSPATH environment variable. If you are on Java 1.4, refer to the relevant question earlier.

A : You have to use the Java parser in the earlier CICS environment (before TS 3.1). The Java parser in Toolkit V1.2 can run under CICS TS 1.3. The java parsers in Toolkit V1.3 and V1.4 can only run in the CICS TS 2.2 or later product due to those parsers' dependencies on Java SDK 1.3.1 which is not supported in CICS TS 1.3.

A : The only warranty is that the parse method of the parser is reentrant. You can run the parser, DOM, etc from separate threads, but we do not synchronize every method call on the parser.

To make the Java XML parser 100% thread safe parser would require a significant performance degradation. Therefore, synchronization is left to the XML application developer.

A : Before converting your application to use the new z/OS specific parser classes, you need to carefully read the section in Chapter 1 of the XML Toolkit for z/OS User's Guide on the z/OS specific parser classes. These new classes mimic the behavior of the existing SAX2 and DOM interfaces but there are some differences in behavior that you need to consider before making the decision to use these.

A : The DLL that the XML Toolkit Parser, C++ Edition uses to interface with XML System Services is an XPLINK DLL. Therefore, if your first module called is not compiled with the XPLINK option, you need to add the following to the _CEE_RUNOPTS environment variable:

“XPLINK(ON)”

A : The new support for the z/OS specific parser classes requires the following z/OS XML System Services PTFs be installed:

• z/OS 1.7 - PTF UA38681
• z/OS 1.8 - PTF UA38682
• z/OS 1.9 - PTF UA38762

A : When using the z/OS specific parser classes, part of the parse is done by z/OS XML System Services. This enables us to take advantage of lower cost zAAP speciality engines (if present). The error detection in this scenario is done by z/OS XML System Services in most cases, and the XML Parser, C++ Edition displays an error message that contains the z/OS XML System Services return and reason codes. The z/OS XML System Services User’s Guide (SA23-1350) provides an explanation of these error codes.

A : When the z/OS specific parser classes are used, z/OS XML System Services does a portion of the parsing operation. When it detects an error, it returns the offset of the error from the beginning of the document of the character in error. It does not take into account line feeds or new lines and calculates a line and column number like is done when not using the z/OS specific parser classes.

A : The following link provides detailed instructions on how to build your samples using JCL: Building XML Parser, C++ Edition Samples for Native MVS using JCL Note that the instructions are for Toolkit V1.8, but can be applied to any supported release, with minor adjustments for release specific file names, directory paths, etc.

A : In V1.8, the Deprecated DOM support has been removed from the main XML Parser DLL and is now in a separate DLL. You need to also specify the side-deck of the new Deprecated DOM DLL when you bind your code. If you are building a non-XPLINK application, you need to bind with "libxerces-depdom2_6_0.x". If your application is XPLINK, then use "libxerces-depdom2_6_0.xplink.x".

A : It appears that on the bind step you specified the side-deck for the XPLINK version of the parser, however the code that is calling this is compiled non-XPLINK. The best way to fix this is to compile your code XPLINK since mixing and matching XPLINK and non-XPLINK code degrades performance signifcantly. Or if you don't want to compile your code XPLINK, then you can get around this by specifying the "XPLINK(ON)" option to the _CEE_RUNOPTS environment variable.

A : To use the XLC compiler utility, you need to specify the "export cxxflags='-O2'" option in your build process.

A : To fix this, you will need to add the following statements to your XLC config file:

cxxsuffix_host=SIXMEXP
cxxsuffix=cpp

A : The V1.8 version of the C++ Parser (and also the C++ XSLT Processor) now provide a set of DLLs that support XPLINK in addition the the non-XPLINK ones that have been provided in previous releases.

Also, the Deprecated DOM support in the XML C++ Parser main DLL has been moved to a separate DLL to reduce the footprint of the main DLL.

A : The XPLINK DLLs and side-decks are in the same "lib" directory as the non-XPLINK DLLs and side-decks. When you bind your code with the C++ Parser, you specify the XPLINK side-deck "libxerces-c2_6_0.xplink.x". This will cause your code to invoke the "libxercesc-2_6_0.xplink.dll" at runtime.

When using the XPLINK version of the C++ Parser you should also be building your application XPLINK.

A : A multithreaded application must guarantee that only one thread has entered either the XMLPlatformUtils::Initialize or XMLPlatformUtils::Terminate methods at any one time. The best solution is to do a single Init/Term pair in your main routine that creates the threads. Otherwise you need to serialize the calls to these routines.

A : You could be running into problems where all objects must be deleted before the XMLPlatformUtils::Terminate method is called. Here is a simple example that illustrates a problem:

{  
  XMLPlatformUtils::Initialize();
  SAXParser parser;
  XMLPlatformUtils::Terminate(); 
}

This code used to work on earlier versions of the parser. With the implementation of the plugable memory manager it now abends. This is because the dynamic memory for the SAXParser object is now owned by XMLPlatformUtils. When the XMLPlatformUtils::Terminate is called it frees the storage for the SAXParser object and any objects it creates. However the SAXParser object goes out of scope after the XMLPlatformUtils::Terminate and its destructor is called and tries to delete objects already deleted.
This code will work if changed as follows:

{  
  XMLPlatformUtils::Initialize();
  {
    SAXParser parser;
  }
  XMLPlatformUtils::Terminate(); 
}

You must either explicitly scope the parser object inside the calls to XMLPlatformUtils::Initialize and XMLPlatformUtils::Terminate as the above example illustrates. Or you could dynamically allocate the parser object and delete it explicitly before the call to XMLPlatformUtils::Terminate.

A : In Toolkit V1.6 and above, the XML Parser, C++ Edition implements C++ namespace support. Therefore applications must namespace qualify all of the XML4C classes/data/variables with "xercesc::" or add the "using namespace xercesc" clause. An example of this is as follows:

   // indicate using XML4C namespace in general
   using namespace xercesc;

   // need to properly scope any forward declarations
   namespace xercesc {
   class AttributeList;
   }

   // or namespace qualifier the forward declarations
   xercesc::ErrorHandler; 

There are also macros defined that simplify this:

   #define XERCES_CPP_NAMESPACE_BEGIN namespace xercesc_2_2 {
   #define XERCES_CPP_NAMESPACE_END }
   #define XERCES_CPP_NAMESPACE_USE using namespace xercesc_2_2;
   #define XERCES_CPP_NAMESPACE_QUALIFIER xercesc_2_2::

"xercesc" can be used in place of "xercesc_2_2". It is a generic namespace which will be updated in each release.

Using these macros your code would look like this:

   // indicate using XML4C namespace in general
   XERCES_CPP_NAMESPACE_USE

   // need to properly scope any forward declarations
   XERCES_CPP_NAMESPACE_BEGIN
   class AttributeList;
   XERCES_CPP_NAMESPACE_END

   // or namespace qualifier the forward declarations
   class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;

A : The requirement to copy the entire directory tree has been removed in V1.6 and above. You just need to copy the "samples" directory and set a new environment variable to point to the directory that contains the "samples" directory. You can then build the samples in this directory. For more information refer to v1.6 usage.

A : We no longer include the DLLs and sidedecks in the HFS. If you want to install the MVS Native DLLs and sidedecks the sample JCL in the "xml4c-5_2/lib/IBM/JCLIN" directory has been updated to link-edit the HFS copy of the DLLs into a PDSE. The sidedecks from the "xml4c-5_2/lib" directory can be copied to a PDS. Instructions for doing this can be found at C++ Edition Installation.

A : Since V1.5 has a prerequisite of z/OS 1.2 a couple of changes are necessary to the way the samples are compiled :

1. You must remove the following "export" :

    
        export _CXX_CVERSION="0x220a0000"
   

2. The "export CXXFLAGS=-2" must be changed to the following (V1.5 and V1.6 only) :

        export CXXFLAGS="-2 -Wc,staticinline"
   

A : There was a directory tree reorganization done in V1.5. In V1.4 the [full path to the C++ Parser]/include directory was the root directory for all include files. On V1.5 and above this has been changed to [full path to the C++ Parser]/include/xercesc.

The best thing to do would be to update your code as follows :

     V1.4:            #include <util/XMLString.hpp>          // old way
     V1.5 and above:  #include <xercesc/util/XMLString.hpp>  // new way

You may also add another "-I" parameter in your Makefiles to point to the [full path to the C++ Parser]/include/xercesc subdirectory.

A : The experimental IDOM APIs have been renamed are now the recommended DOM C++ binding in V1.5 and above. In order to use the former IDOM as the recommended DOM binding you will have to update your code. The following changes have been made to the IDOM APIs :

• class names are renamed from IDOM_XXXX to DOMXXXX, for example IDOM_Document to DOMDocument
• header files are renamed from IDOM_XXXX.hpp to DOMXXXX.hpp and are moved to the "src/xercesc/dom" subdirectory
• the IDOMParser is renamed to XercesDOMParser and its header file is renamed as well

The following code samples illustrates these changes :

   //old code
      #include <xercesc/idom/IDOM.hpp>
      #include <xercesc/idom/IDOM_Document.hpp>
      #include <xercesc/parsers/IDOMParser.hpp>

            void test(char* xmlFile) {
                      IDOMParser parser;
                      parser.parse(xmlFile);
                      IDOM_Document* doc = parser.getDocument();
                      :
                      return;
            }


   //new code
      #include <xercesc/dom/DOM.hpp>                  //<==== change this include line
      #include <xercesc/dom/DOMDocument.hpp>          //<==== change this include line
      #include <xercesc/parsers/XercesDOMParser.hpp>  //<==== change this include line

             void test(char* xmlFile) {
                       XercesDOMParser parser;                  //<==== rename the IDOMParser
                       parser.parse(xmlFile);
                       DOMDocument* doc = parser.getDocument(); //<==== rename the IDOM_XXXX
                       :
                       return;
             }

For more information refer to the documentation in the "doc" subdirectory that ships with the product in the "Migration Guide" section.

A : Yes, this migration may require significant code changes.

A : Yes, the "old" DOM is still part of V1.5 however you will have to change your code slightly to pick it up from a different subdirectory :

    //old code                 
    #include <xercesc/dom/DOM.hpp>                  
    #include <xercesc/dom/DOM_Document.hpp>                 
    #include <xercesc/parsers/DOMParser.hpp>

    //new code                 
    #include <xercesc/dom/deprecated/DOM.hpp>                  
    #include <xercesc/dom/deprecated/DOM_Document.hpp>                 
    #include <xercesc/parsers/deprecated/DOMParser.hpp> 

For more information refer to the documentation in the "doc" subdirectory that ships with the product in the "Migration Guide" section.

A : V1.5 extends the "Reuse Grammar" support by replacing it with a new feature called "Grammar Caching" which provides more flexibility in reusing grammars. For more information refer to the documentation in the "doc" subdirectory that ships with the product in the "Migration Guide" section.

A : No. A subset of ICU4C needed by XML4C and XSLT4C is included in the XML Toolkit solely for their own internal use. The included support has not been tested for general external use by other programs and is not supported by IBM for such use. For more information on ICU, please consult the ICU Web site at http://www.ibm.com/software/globalization/icu

A : The XML Parser for z/OS, C++ Edition V1.8 has been tested with ICU version 3.2.0. The required ICU level is packaged with the corresponding parser level. IBM does not recommend using different ICU versions.

A : The XML Parser for z/OS, C++ Edition V1.7 has been tested with ICU version 2.6.1. The required ICU level is packaged with the corresponding parser level. IBM does not recommend using different ICU versions.

A : The XML Parser for z/OS, C++ Edition V1.6 has been tested with ICU version 2.4. The required ICU level is packaged with the corresponding parser level. IBM does not recommend using different ICU versions. The required ICU level is packaged with the corresponding parser and Xalan level.

A : The XML Parser for z/OS and OS/390, C++ Edition V1.4 has been tested with ICU version 2.0.2. IBM does not recommend using different ICU versions. The required ICU level is packaged with the corresponding parser and Xalan level.

A : V1.8 See the XML Toolkit for z/OS User's Guide for information on the V1.8 shared libraries.

A : V1.7 contains FIVE shared libraries :

• libicudata26.1.dll
• libicudata_stub26.1.dll
• libicui18n26.1.dll
• libicuuc26.1.dll
• libxerces-c2_4_0.dll

A : V1.6 contains FIVE shared libraries :

• libicudata24.0.dll
• libicudata_stub24.0.dll
• libicuil8n24.0.dll
• libicuuc24.0.dll
• libxerces-c2_2_0.dll

V1.5 contains FOUR shared libraries :

• libicudata22.0.dll
• libicudata_stub22.0.dll
• libicuuc22.0.dll
• libxerces-c2_1_0.dll

V1.4 contains FIVE shared libraries :

• libicudt20e.dll
• libicudt20e_390.dll
• libicui18n.20.2.dll
• libicuuc.20.2.dll
• libxerces-c1_6_0.dll

Ensure that these dlls are in your LIBPATH environment variable. The library names for the UNIX platforms are different and are explained in details in the documentation bundled with the product.

A : The V1.4, V1.5, V1.6 XML C++ Parsers require the "ICU_DATA" environment variable to be set to the path where the XML and ICU dlls reside. Add one of the following commands to your ".profile" file depending on your version :

   export ICU_DATA=/usr/lpp/ixm/IBM/xml4c-5_2/lib"    [for V1.6]
   export ICU_DATA=/usr/lpp/ixm/IBM/xml4c-5_0/lib"    [for V1.5]
   export ICU_DATA=/usr/lpp/ixm/IBM/xml4c-4_0/lib"    [for V1.4]

This will give you access the the iso-8859-2 encoding (this is not required for V1.7).

A : Yes, XML Parser for z/OS and OS/390, C++ Edition utilizes the latest IBM's International Components for Unicode (ICU) for code page conversion. A detailed list of supported code pages is given in the FAQ bundled with the SMP/E product package. Starting in V1.5, z/OS Unicode Services may also be used by the parser for certain code page conversions.

A : You may use the following command to determine this for Java 1.3 only (for Java 1.4, see the earlier FAQ on the override mechanism) :

    -  java org.apache.xalan.Version

A : The following link provides detailed instructions on how to build your samples using JCL: Building XSLT Processor, C++ Edition Samples for Native MVS using JCL Note that the instructions are for Toolkit V1.8, but can be applied to any supported release, with minor adjustments for release specific file names, directory paths, etc.

A : V1.6 and above is thread-safe.

A : To use the XLC compiler utility, you need to specify the "export cxxflags='-O2'" option in your build process.

A : To fix this, you will need to add the following statements to your XLC config file:

cxxsuffix_host=SIXMEXP
cxxsuffix=cpp

A : Since V1.6, the XSLT Processor, C++ Edition no longer requires the STLPort. Instead it depends on the standard template library support in the compiler. However, if you are using the non-XPLINK version of of the XSLT Processor, C++ Edition, then you need to have the PTF for APAR PQ75251 installed on your system.

A : Yes. In order to use an MVS sequential dataset you need to prefix it with two slashes. This will cause the APIs to look for an MVS dataset instead of looking for a file in the HFS. So if you had an MVS sequential dataset named "xml.data" and you wanted to run SAXCount against it you would enter the following:

SAXCount "//'xml.data'"

By putting the single quote right after the two slashes it will prevent MVS from adding your userid as a high-level qualifier for the dataset name. If you needed your userid prefixed to the dataset name you could do one of the following:

SAXCount '//myxml.data'
SAXCount "//'[userid].myxml.data'"

In the first example you could use a single quote around the whole name since you didn't need to use it to prevent your userid from being added. In the second example, the userid is explicitly specified on the dataset name so you don't want it added. So in this case you need the single quote after the slash and a double quote around the entire name.

If you had a PDS called "xmlpds.data" with a member "personal" you would invoke SAXCount as follows:

SAXCount "//'xmlpds.data(personal)'"

If you had a PDS called "[userid].myxmlpds.data" with a member "personal" you could use either of the following:

SAXCount "//'[userid].myxmlpds.data(personal)'"
SAXCount '//myxmlpds.data(personal)'

A : The answer to this is a little complicated. First we need to explain a little background information on the differences between absolute and relative URIs. An absolute URI is one that has the "file:/" protocol in front of it. For example, this is an absolute URI dealing with an HFS file:

'file:///u/xml/personal.xml'

A relative URI is one that does not have the "file:/" protocol preceding it. This is a relative URI dealing with an HFS file:

/u/xml/personal.xml

However since it starts with a slash it is an absolute path. If it did not start with a slash then it would be relative URI with a relative path. Relative paths are not supported in absolute URIs.

If you are addressing an MVS dataset as follows then you are using an absolute URI:

SAXCount "file:////'xmlpds.data(personal)'"
SAXCount "file:////'[userid].myxmlpds.data(personal)'"

If you are addressing an MVS dataset as follows then you are using a relative URI:

SAXCount //'xmlpds.data(personal)'

Now that we've explained absolute and relative URIs here is what the XSLT processor supports:

• The output parameter on the samples only supports relative URIs.
• The input parameters on the samples (for the XML and XSL files) support the following:
  • For MVS datasets only absolute URIs are supported.
  • For HFS files both absolute and relative URIs are supported

So, for example, to run the Xalan command with the inputs in datasets and with the output written to a dataset, you must do the following:

Xalan -o "//sample.xml(fooout)" "file:////sample.xml(fooxml)" "file:////sample.xml(fooxsl)"

A : No.The Java version of these products only supports files that reside in the HFS.

A : Yes you may write to MVS sequential datasets and PDSs. The following parameters may be specified when creating a new dataset :

• recfm=
• lrecl=
• blksize=
• space=
• type=
• byteseek
• noseek

These parameters are passed in as part of the URI. You put a ";" after the file name and then specify the parameters. For example :

    file:////'user1.personal.xml';lrecl=80,blksize=800,recfm=fb
    //'user1.personal.xml';lrecl=80,blksize=800,recfm=fb,type=record

These parameters may also be specified when reading files however the only meaningful one is "type=record". If you write the dataset using this parameter you should also specify this when reading it. If you specify any other parameters such as recfm, blksize, etc. you should use the same value as the file was created with. However it is actually easier to just leave these off as they default to the values of the datasets.

Refer to the fopen API documentation in the "z/OS C/C++ Programming Guide" for more details on these parameters.