XMLTRANSFORM

Transform an XML stream using an XSLT style sheet. 

        operation XMLTRANSFORM
params
  string InputXMLStream       : IN
  string XSLTFileName 	 : IN
  string AdditionalArguments	 : IN
  string OutputStream         : OUT
  numeric Status              : OUT
  string MoreInformation 	 : OUT
endparams

AdditionalArguments can contain a string of arguments in the following format:

{-VALIDATE {"ValidationFile"}}{ -TEXT }{ -HTML } {-PARAM {ParamNameParamValue} 1...n }

Parameters

  • InputXMLStream—XML stream to be transformed.
  • XSLTFileName—file containing the required XSLT stylesheet. The file name can be specified with or without a path. If no path is specified, Uniface uses the default file location specified in the assignment file. For more information, see Syntax of File and Directory Names.
  • AdditionalArguments—string of arguments that determine whether InputXMLStream is validated and the format of the OutputStream
    • -VALIDATE—report validation errors for InputXMLStream as an error in the Status parameter.
    • -TEXT—after transformation, output as text (strip all element tags and attributes, and replace all entities with their replacement texts).
    • -HTML—after transformation, output as HTML (entities are not replaced by their replacement texts, and an XML declaration is not added at the beginning of the output stream).
    • -PARAM—supply parameters to the specified stylesheet. For example: 
      $EXTRA_ARGUMENTS$ = "-PARAM param1 %%"hello ... %%" -PARAM param2 %%"world%%""
  • ValidationFile—DTD to use in validation. If specified, the DOCTYPE declaration in InputXMLStream is removed, and a reference to the specified validation file is added. This enables you to override the DTD declared by the input XML stream.
  • OutputStream—output of the XSLT transformation. It can contain XML, HTML, or text depending on the AdditionalArguments. It is empty if transformation fails with Status in a range from -1 to -5.
  • Status—value indicating the success or failure or the operation.
  • MoreInformation—additional information about errors from the XSLT processor

Return Values

The following values are returned in Status:

Value Description
0 Success
-1 XSLT file name was not specified
-2 XSLT file could not be located or is not a syntactically correct XSLT stylesheet
-3

Transformation error. Details are returned in MoreInformation.

-4

Platform not supported. For more information on supported platforms, see USYSXSLT.

-5 Java Runtime not found.
-6 Transformation successful, but InputXMLStream is not valid. This error is only reported if the argument -VALIDATE is specified.
-7 Transformation successful, but the validation file could not be located. This error is reported when the ValidationFile specified for the -VALIDATE argument cannot be located.

Description

XMLTRANSFORM is an operation of component USYSXSLT.

XMLTRANSFORM modifies the structure and content of an InputXMLStream using the instructions and rules contained in an XSLT file specified in XSLTFileName. The output stream OutputStream produced by XMLTRANSFORM can have a different structure from the input stream. It is also possible for the output stream to be plain text, HTML, or any other character-based output type specified in the XSLT file.

Validation and Transformation

The DTD for the InputXMLStream is not required in the Repository because the data type is string, not XML Stream. To validate InputXMLStream, the DTD, or a file reference to the DTD must be embedded in the XML stream.

When creating the XML stream on a Uniface component, you can include the DTD in the stream by using the xmlsave/dtd statement. Uniface always produces valid XML, but this technique can be useful if you are modifying the XML stream in ProcScript using string handling functions.

The InputXMLStream is validated if it includes a DTD or a file reference to a DTD. If the input XML stream does not indicate a DTD, the stream is assumed to be valid.

Note:  Validation and transformation are separate processes. It is possible for transformation to succeed even if validation has failed. However, if both validation and transformation fail, USYSXSLT returns information about the transformation failure, and does not return validation error information.

The following values are returned in Status if a validation error occurs, but the transformation is successful:

  • 0—if -VALIDATE is not specified
  • -6—if -VALIDATE is specified

Memory Management

When transforming large documents, the application may stop when without an error message, or with the following error message: 

3458 - Validation failed.

xmlvalidate
 ERROR = -1504
 MNEM = <UXMLERR_VALIDATE>
 DESCRIPTION = An error occurred during validation of an XML stream
 ADDITIONAL = Xml validation error: Unknown element 'dsml:dsml'. Line 2, Position 50

XSL translation from Uniface XML failed.
XSL Transformation error.
Return information:

(Location of error unknown)XSLT Error (java.lang.OutOfMemoryError): null
Application exiting abnormally: -3

This can occur when there is not enough memory available to the Java Virtual Machine. To increase the amount of memory available, set the JVM_OPTIONS logical in the [LOGICALS] section of the application's assignment file. For example:

[LOGICALS]
JVM_OPTIONS = -Xmx512m

To call this operation, activate the USYSXSLT component as follows:

activate "USYSXSLT".XMLTRANSFORM ("%%$MYXMLSTREAM$%%%", "std.xsl", %\
"-VALIDATE %%"mydtd.dtd%%"", $MYXMLSTREAM$, $STATUS$, $I_STATUSCONTEXT$)

For more information, see Examples of XSLT .

Related Topics