XML C Technology for HP OpenVMS

XML C Technology for HP OpenVMS

Installation Guide and Release Notes

January 2005

Version 2.0-1, based on
Apache Xerces C Version 2.2.0 and
Apache Xalan C Version 1.5

Contents

Before Installing XML C Technology

Hardware Prerequisites

Software Prerequisites

Installing XML C Technology

Expanding the Kit

Installing the Kit

After Installing XML C Technology

Building XML C Sources

Release Notes

Support

Before Installing XML C Technology

Hardware Prerequisites

XML C Technology for OpenVMS is available on the Alpha and I64 platforms.

The XML C Technology for OpenVMS self-extracting ZIP file requires approximately 58,103 blocks (30 MB) of disk space for OpenVMS Alpha, and 124,283 blocks (62 MB) of disk space for OpenVMS I64. Expanding the ZIP file requires an additional 206,783 blocks for Alpha and 447,256 blocks for I64.

The installation procedure allows you to choose to install some or all of the XML components. The total disk space required is approximately 136,831 to 182,330 blocks for OpenVMS Alpha, and 334,577 to 397,546 blocks for OpenVMS I64, depending on the installation options you choose.

Software Prerequisites

For OpenVMS Alpha:

HP OpenVMS Alpha Version 7.3-2 (or higher)

Compaq C++ Version 6.5 (or higher) for OpenVMS Alpha

For OpenVMS I64:

HP OpenVMS I64 Evaluation Release 8.1 (or higher)

Compaq C++ Version 6.5 (or higher) for OpenVMS I64

Installing on an ODS-5 enabled disk is required. Because of long file names and directory depth issues, the installed code base and the accompanying documentation cannot be guaranteed to function properly in a non-ODS5 environment.

Installing XML C Technology

Removing the Previous Version

Before installing the current version of OpenVMS XML-C, you must remove any previous versions.

For example, to remove the previous version, invoke the uninstall procedure by entering the following command:

$ @XML-C$ROOT:[XML-C-2_0]UNINSTALL_XML-C-2_0

Expanding the Kit

To expand the XML C Technology for OpenVMS ZIP file, perform the following steps:

1. Set default to a directory on the ODS-5 disk where the installation files can be extracted. You can download and extract the files to either an ODS-2 or an ODS-5 disk. However, you must install the kit on an ODS-5 disk.

For example:

$ SET DEFAULT DISK:[EXTRACT]

2. Enter the following command to extract relevant files from the XML C kit. In this example, the ZIP file was downloaded to DISK:[DOWNLOADS].

$ RUN DISK:[DOWNLOADS]XML-C-2_0-1.EXE

The UNZIP command extracts INSTALL_XML-C-2_0.COM and a number of other files needed to complete the installation.

Installing the Kit

Note: This kit creates logicals in the system name table. Therefore, the SYSNAM privilege is required.

To install the XML C Technology for OpenVMS kit, enter the following command:

$ @[.XML-2_0.KIT]INSTALL_XML-C-2_0

Note that the installation directory name is case-sensitive. For example, ODS5_DISK$:[YourName.XMLC_Install]

The following is a log of a sample installation. Your log will look very similar depending on the platform and configuration settings.

Welcome to OpenVMS (TM) Alpha Operating System, Version V7.3-2

Username: system

Password:

Welcome to OpenVMS (TM) Alpha Operating System, Version V7.3-2 on node

Last interactive login on Friday, 2-MAY-2004 02:24:14.29

Last non-interactive login on Friday, 2-MAY-2004 02:24:15.76

$ SET DEF DISK:[EXTRACT]

$ UNZIP DISK:[DOWNLOADS]XML-C-2_0.ZIP

Archive: DISK:[DOWNLOADS]XML-C-2_0.ZIP

creating: [.XML-2_0]

creating: [.XML-2_0.DOCUMENTATION]

inflating: [.XML-2_0.DOCUMENTATION]xalan-c-docs-2_0.SAV

inflating: [.XML-2_0.DOCUMENTATION]xerces-c-docs-2_0.SAV

creating: [.XML-2_0.EXAMPLES]

inflating: [.XML-2_0.EXAMPLES]xalan-c-samples-2_0.SAV

inflating: [.XML-2_0.EXAMPLES]xerces-c-samples-2_0.SAV

creating: [.XML-2_0.KIT]

inflating: [.XML-2_0.KIT]BUILD_XML-C-2_0.COM

inflating: [.XML-2_0.KIT]DOC_DESCRIPS_XML-C-2_0.TXT

inflating: [.XML-2_0.KIT]INSTALL_XML-C-2_0.COM

inflating: [.XML-2_0.KIT]SRC_DESCRIPS_XML-C-2_0.TXT

inflating: [.XML-2_0.KIT]UNINSTALL_XML-C-2_0.COM

inflating: [.XML-2_0.KIT]xalan-c-bin-2_0.SAV

inflating: [.XML-2_0.KIT]XALAN_SAMPLES_XML-C-2_0.COM

inflating: [.XML-2_0.KIT]xerces-c-bin-2_0.SAV

inflating: [.XML-2_0.KIT]XERCES_SAMPLES_XML-C-2_0.COM

inflating: [.XML-2_0.KIT]XML-C-2_0-TP.COM

inflating: [.XML-2_0.KIT]XML-C-2_0_INDEX.HTML_TEMPLATE

inflating: [.XML-2_0.KIT]XML-C-2_0_INDEX.HTML_TEMPLATE2

creating: [.XML-2_0.SOURCES]

inflating: [.XML-2_0.SOURCES]xalan-c-src-2_0.SAV

inflating: [.XML-2_0.SOURCES]xerces-c-src-2_0.SAV

creating: [.XML-2_0.TOOLS]

$ @[.XML-2_0.KIT]INSTALL_XML-C-2_0

              XML-C V2.0 Installation Procedure

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

Before installing this kit, please make sure that the following prerequisites have been met.
If they have not been met, the installation procedure may be unable to complete and may terminate:

1) The installed operating system is OpenVMS Alpha V7.3-2 or later.

2) The installed version of Compaq C++ for OpenVMS Alpha Systems is V6.5 or higher.

3) An ODS-5 enabled disk is available and mounted.

        ***********************************************************

                                 Note

                Questions, where indicated, accept a response of

                 "H" to request additional Help and information.

        ***********************************************************

Please enter the ODS-5 target destination device and directory or logical name indicating the location
where you would like to install XML-C V2.0.

This location will become the base directory for XML-C V2.0: (H) [ODS5_DISK$:[XML]]: ODS5_DISK$:[XML]

  Sources

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

The sources are provided for those that may wish to build them in order to do development work in this area.

You can choose to install all of the sources, or none of it.

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

      1.    [ ]        Xerces V2.2.0                 ~ 27068 blocks

      2.    [ ]        Xalan  V1.5                   ~ 17265 blocks

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

            [x] = Selected,  [ ] = Not Selected

Enter:  1 through 2 - To toggle a selection

        A           - To select All sources

        N           - To select No  sources

        Y           - To proceed with the installation

A, N, 1-2, or Y : a

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

      1.    [x]        Xerces V2.2.0                 ~ 27068 blocks

      2.    [x]        Xalan  V1.5                   ~ 17265 blocks

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

            [x] = Selected,  [ ] = Not Selected

Enter:  1 through 2 - To toggle a selection

        A           - To select All sources

        N           - To select No  sources

        Y           - To proceed with the installation

A, N, 1-2, or Y : y

No further questions will be asked.

Installing binaries...

        Xerces-C-2_0...

        Xalan-C-2_0...

Installing examples...

        Xerces-C-2_0...

        Xalan-C-2_0...

Installing sources...

        Xerces-C-2_0...

        Xalan-C-2_0...

    XML-C V2.0 Installation complete.

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

XML-C$ROOT, XERCES-C$ROOT and XALAN-C$ROOT  have been defined.

The following lines must be added to SYS$MANAGER:SYLOGICALS.COM   so that it will be defined each time
the system is rebooted.

 $ define/sys/nolog/trans=concealed XML-C$ROOT ODS5_DISK:[XML.]

 $ define/sys/nolog/trans=concealed XERCES-C$ROOT ODS5_DISK:[XML.Xerces-C-2_0.]

 $ define/sys/nolog/trans=concealed XALAN-C$ROOT ODS5_DISK:[XML.Xalan-C-2_0.]

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

Press the <Enter> key to continue:

 Post Installation Checkout

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

Verification of the installation can be performed using the XML-C

Test Procedure.  To run the XML-C Test Procedure, enter the

following command:

    $ @XML-C$ROOT:[XML-C-2_0]XML-C-2_0-TP

Should you wish to remove XML-C V2.0, enter the following command:

    @XML-C$ROOT:[XML-C-2_0]UNINSTALL_XML-C-2_0

After Installing XML C Technology

After the installation is complete, perform the following tasks.

Add the following lines to SYS$MANAGER:SYLOGICALS.COM so that XML C Technology is defined each time the system is rebooted.

$ define/sys/nolog/trans=concealed XML-C$ROOT ODS5_DISK:[XML.]

$ define/sys/nolog/trans=concealed XERCES-C$ROOT ODS5_DISK:[XML.Xerces-C-2_0.]

$ define/sys/nolog/trans=concealed XALAN-C$ROOT ODS5_DISK:[XML.Xalan-C-2_0.]

Optionally run the XML C Test Procedure. To run the test procedure, enter the following command:

$ @XML-C$ROOT:[XML-C-2_0]XML-C-2_0-TP

Interpreting the results of the XML C Test Procedure

The XML Test Procedure compares the output from the tests with a set of benchmarks. Because of the nature of the tests, some differences between the results and the benchmarks are to be expected. The following describes the common differences which are expected to occur.

Many of the tests display the amount of time it takes to parse the document. For example, SAXCount will output:

personal.xml: 736 ms (37 elems, 12 attrs, 134 spaces, 134 chars)

The values are the parse time, and the count of elements, attributes, ignorable whitespaces, and characters appearing in the document. The parse time will vary based on a number of factors and is not likely to match the time in the benchmark, however, the element counts should match.

Note: The results produced by this and other similar programs should never be accepted as true performance measurements.

Following is a session log containing a run of the XML C Test Procedure followed by a section showing the differences between the run log and supplied benchmark. Your log should look very similar depending on the platform.

$ @XML-C$ROOT:[XML-C-2_0]XML-C-2_0-TP

No test specified. All applicable tests will be run.

Starting Xerces-C tests...

%DCL-S-SPAWNED, process SYSTEM _179 spawned

%DCL-S-ATTACHED, terminal now attached to process SYSTEM_179

%DCL-S-RETURNED, control returned to process _FTA55:

Starting Xalan-C tests...

%DCL-S-SPAWNED, process SYSTEM _14 spawned

%DCL-S-ATTACHED, terminal now attached to process SYSTEM _14

%DCL-S-RETURNED, control returned to process _FTA55:

Tests complete. Check XML-C$ROOT:[XML-C-2_0]XML-C-TP.LOG for errors.

$ type XML-C$ROOT:[XML-C-2_0]XML-C-TP.LOG

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

    6 96

    7 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

    6 126

    7 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

   20 33

   21 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

   20 34

   21 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

   34 24

   35 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

   34 19

   35 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

   48 29

   49 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

   48 31

   49 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

   62 29

   63 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

   62 30

   63 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

   76 28

   77 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

   76 23

   77 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

   93 78

   94 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

   93 82

   94 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

101 33

102 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

101 34

102 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

109 16

110 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

109 17

110 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

117 28

118 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

117 36

118 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

125 34

126 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

125 30

126 ms (

************

************

File XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1

133 32

134 ms (

******

File XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

133 35

134 ms (

************

Number of difference sections found: 12

Number of difference records found: 12

DIFFERENCES /IGNORE=()/MERGED=1-

    XML-C$ROOT:[Xerces-C-2_0.samples.RESULTS]XML-XERCES-TP.OUT;1-

    XML-C$ROOT:[Xerces-C-2_0.samples.BENCHMARKS]XML-XERCES-TP.BMK;2

Number of difference sections found: 0

Number of difference records found: 0

DIFFERENCES /IGNORE=()/MERGED=1-

    XML-C$ROOT:[Xalan-C-2_0.c.samples.RESULTS]XML-XALAN-TP.OUT;1-

    XML-C$ROOT:[Xalan-C-2_0.c.samples.BENCHMARKS]XML-XALAN-TP.BMK;3

In order to build and run all the samples provided, please refer to
XML-C$ROOT:[XML-C-2_0] BuildAllSamples_Readme.txt
For documentation on XML-C, please access the Apache website at the following URLs:
 
    http://xml.apache.org/xerces-c/
    http://xml.apache.org/xalan-c/

Removing XML C Technology for OpenVMS

Your log will appear very similar to the following, depending on the platform.

$ @XML-C$ROOT:[XML-C-2_0]UNINSTALL_XML-C-2_0

              XML-C V2.0 UnInstall Procedure

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

Please enter device and directory where XML-C is installed ODS5_DISK$:[XML.] :

                        ***** Warning *****

    This procedure will delete all files in the following directories

    and all subdirectories of the following directories. You may wish

    to preserve any changes and additions you have made before continuing

    with this procedure.

                ODS5_DISK$:[XML.Xerces-C-2_0...]

                ODS5_DISK$:[XML.Xalan-C-2_0...]

                ODS5_DISK$:[XML.XML-C-2_0...]

    Files modified by the XML-C installation procedure will be restored,

    provided there have been no additional modifications since XML-C was

    installed.

Would you like to continue this procedure? (Y, N [N]) y

   Removing Xerces-C-2_0...

   Removing Xalan-C-2_0...

   Removing XML-C-2_0...

XML-C V2.0 Un-Install complete.

                                Note

You may wish to delete the top level directory that the XML-C$ROOT

logical equates to (ODS5_DISK$:[XML.] ).

You may also wish to remove the XML-C$ROOT, XERCES-C$ROOT, and

XALAN-C$ROOT logical name definitions from SYS$MANAGER:SYLOGICALS.COM.

Building the XML C Sources

Building the XML-C sources is not required unless you plan to make modifications to the sources. Optionally, you can build a shareable image from the object files shipped in the object library.

If you do plan to modify the sources, it is recommended that you perform a full build of the existing code before you make any modifications. A full build will likely require several hours and is best submitted as a batch job to run overnight. To submit the build, modify the main build procedure BUILD_XML-C-2_0.COM found in XML-C$ROOT:[000000] to specify the batch queue to use (this procedure will submit additional procedures). Then submit the main procedure using the command:

$ submit/queue=<your-batch-queue> XML-C$ROOT:[XML-C-2_0]BUILD_XML-C-2_0

Further details are provided in the BUILD_XML-C-2_0.COM procedure.

You can also invoke the main build procedure interactively using the following command, in which case all build procedures will be run interactively:

$ @XML-C$ROOT:[XML-C-2_0]BUILD_XML-C-2_0

However, based on the length of time required, this method is not recommended. Using a batch job also has the added advantage of providing log files of any errors that may occur.

Note: XALAN-C$ROOT and XERCES-C$ROOT must be defined in order for the build procedures to work. These logicals are defined by the XML-C installation procedure, however they are defined only on the node in which XML-C was installed, not on all nodes in a cluster. Be sure they are defined on the node which will be executing the batch jobs. You should either manually define them on the nodes on which you will be executing the batch jobs (assuming they point to a cluster accessible disk), or you should restrict which nodes execute the batch jobs.

Partial Builds

Once the full build has completed, subsequent builds will only recompile the sources that you modify or any sources that failed to produce an object file in the previous build. The determination as to which sources to build is based on modification dates of the sources and objects, so modifying a source will mean that the source is newer than the object and cause that object to be rebuilt. Note that if you then delete the modified source in an attempt to restore the original version, you must also delete the corresponding object to force the object to be rebuilt.

Note that modifying the source will also cause shareable images to be rebuilt, which can also be a lengthy process. It may be possible to modify the build procedure to reduce the length of time it takes to create the shareable image when only minor modifications to the sources are being made. Doing so is beyond the scope of this document. It is recommended that you disable the creation of the shareable image and/or the related options files and link against the object libraries until you are satisfied with the source changes.

Additional Parameters

You can force a full build using the CLEAN parameter. When specified, all objects, libraries, and shareables are deleted, then all sources are compiled and the object libraries and shareable images will be recreated. Samples images will be relinked.

You can compile and link with the debugger using the DEBUG parameter. When specified, any sources that are compiled will be compiled with the /DEBUG/NOOPTIMIZE qualifiers. Any images that are relinked will be relinked /DEBUG.

For example:

$ submit/queue=MY_QUEUE/PARAM=CLEAN XML-C$ROOT:[000000]BUILD_XML-C-2_0

$ submit/queue=MY_QUEUE/PARAM=(CLEAN,DEBUG) –

_$ XML-C$ROOT:[000000]BUILD_XML-C-2_0

Additional Build Options

There are additional build options contained within the XALAN-C$ROOT:[000000]BUILD_XALAN.COM and XERCES-C$ROOT:[000000]BUILD_XERCES.COM procedures which will control the actions of the procedures and the amount of information output. These are described in the procedures themselves.

Shareable Images

For information about creating Xerces and Xalan shareable images, refer to:

XML-C$ROOT:[XML-C-2_0]create_shareable_readme.txt

XERCES_SHR contains only Xerces code. XML_SHR contains both Xerces and Xalan code. To link against these shareables, specify /OPTIONS on the LINK command, and specify the Xerces shareable file spec with the /SHARE qualifier when working with Xerces code. When working with Xalan code, specify both the Xerces and XML shareable file specs with the /SHARE qualifier. For example:

$ LINK -

<objects>,-

SYS$INPUT/OPTIONS,-

XERCES-C$ROOT:[BIN]XERCES_SHR.EXE_ALPHA/SHARE

XALAN-C$ROOT:[BIN]XML_SHR.EXE_ALPHA/SHARE

To use the shareable images, you must define XERCES_SHR and XML_SHR. For example:

$ DEFINE/JOB XERCES_SHR XERCES-C$ROOT:[BIN]XERCES_SHR.EXE_ALPHA

$ DEFINE/JOB XML_SHR XALAN-C$ROOT:[BIN]XML_SHR.EXE_ALPHA

Note: Using shareable images typically provides several advantages. For example, your images will be smaller than if you link them against the object libraries. They also provide entry vectors which typically do not change from build to build. This would normally mean that you would not need to relink your images for a subsequent release of XML-C. However, because XML-C is produced from open source code, and because of the large number of entry points in the shareables, HP cannot guarantee that you would not need to relink your images.

These instructions are similar in building shareable images for I64.

Object Libraries

Two object libraries are provided:

XERCES-C$ROOT:[LIB]XERCES.OLD
XALAN-C$ROOT:[C.LIB]XALAN.OLB

If you choose to link against these object libraries, you should specify XERCES.OLB when working with Xerces code and both XERCES.OLB and XALAN.OLB when working with Xalan code. For example:

$ LINK -

<objects>,-

XERCES-C$ROOT:[LIB]XERCES.OLB/LIB,-

XALAN-C$ROOT:[C.LIB]XALAN.OLB/LIB

Sample Images

Sample images for Xerces and Xalan are provided in the XERCES-C$ROOT:[bin] and XALAN-C$ROOT:[c.bin] directories. These images have been linked against the sharable images. If desired, they can be linked against the object libraries by changing the LINK_W_SHARE option in the build procedures. These images are executed as part of the XML-C$ROOT:[XML-C-2_0]XML-C-2_0-TP.COM procedure. The sources for these images can be found in XERCES-C$ROOT:[samples...] and XALAN-C$ROOT:[c.samples...].

Release Notes for XML C Version 2.0-1

The following are the changes from Version 2.0 to Version 2.0-1.

· The XML-C Documentation has been removed from the kit. For documentation on XML C, see the following URLs:
            http://xml.apache.org/xerces-c/
            http://xml.apache.org/xalan-c/
·          Separate kits are available for Alpha and I64 platforms.

·       This kit now ships Xerces and Xalan object libraries (.OLB) instead of the shareable images.

            See the file create_shareable_readme.txt if you want to build Xerces and Xalan
            shareable images.

·          Two Xerces samples and one Xalan sample are included in the kit.

            See the file BuildAllSamples_Readme.txt if you want to build all samples.

·          Removed requirement for C compiler.

·          Removed requirement for the HP Secure Web Server for OpenVMS.

Support

V2.0-1 Customer Release Version

Support for XML C Technology for OpenVMS Alpha is provided by the Hewlett-Packard Company under existing OpenVMS service agreements through standard support channels.

See HP support for worldwide support center telephone numbers.

If you do not have a support contract and are not interested in acquiring one, you can informally exchange information with other users in the OpenVMS newsgroup comp.os.vms.

For technical feedback to the XML C Technology for OpenVMS engineering team, please send mail to OpenVMS.eBusiness@hp.com.