SET-OUTPUT-DESTINATION( ) method

Specifies the target for an XML document that a SAX-writer object creates.

Return type: LOGICAL

Applies to: SAX-writer object handle

Syntax

SET-OUTPUT-DESTINATION ( mode 
  , { file | stream | stream-handle | memptr | longchar } )

mode

A character expression that evaluates to one of the following: "FILE", "STREAM", "STREAM-HANDLE", "MEMPTR", or "LONGCHAR". The mode indicates whether the XML target is a file, a stream, a MEMPTR, or a LONGCHAR variable.

file

A CHARACTER expression that indicates the name of a file to which the XML document is to be written. This can be a relative pathname, an absolute pathname, or an HTTP URL. Any relative pathname is relative to the current working directory. The pathname can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.

stream

A character expression that represents the name of an ABL stream. If stream is "", the AVM saves the document to the unnamed stream of the ABL session.

stream-handle

A character expression that represents a stream object handle.

memptr

A MEMPTR variable to which the XML document is to be written. The MEMPTR will be overwritten and the new size of the MEMPTR variable will match the size of the XML text.

longchar

A LONGCHAR variable to which the XML document is to be written. The LONGCHAR will be overwritten and the new size of the LONGCHAR variable will match the size of the XML text.

When writing an XML document to a LONGCHAR variable, the AVM writes the LONGCHAR variable in the code page of the XML document as determined by the XML document's ENCODING attribute. If the ENCODING attribute is not set, the LONGCHAR variable is saved in UTF-8.

If the LONGCHAR variable's code page is fixed (that is, set using the FIX-CODEPAGE statement), the code page must be equivalent to the encoding specified in the XML document's ENCODING attribute. If not, the START-DOCUMENT( ) method returns an error and the XML document is not saved to the LONGCHAR variable.

Use this method to set the output destination, which is where the object will write the XML document. This method must be called before you call any of the writing methods or they will raise errors. You can only call this method when the object's WRITE-STATUS property is SAX-WRITE-IDLE or SAX-WRITE-COMPLETE. In other words, you cannot set a new output destination while the SAX-writer object is currently writing XML. This method fails and generates an error message if it is called while writing.

The SET-OUTPUT-DESTINATION method does not check if the specified destination is valid. If does not check whether a MEMPTR or LONGCHAR variable is usable, and it does not check whether a file location or stream is accessible. This destination is checked at run time by the START-DOCUMENT method.

When writing to a MEMPTR or LONGCHAR, the method deletes the previous contents and allocates new memory. For example, writing to a MEMPTR is the logical equivalent of using SET-SIZE based upon the document size after calling END-DOCUMENT. This is the same way that the X-document object handles memory.