put_in_document

The function put_in_document places produced text in a document. The text placed in a document in this way does not appear in the result document. All result text produced up to the function call is placed in the document specified in the function call. You can call the function several times in a Master Template. Each time the text produced up to the call is placed in a new document.

put_in_document ("document_to_be_produced"; 
                 "path/folder_of_the_document";
                 "overwrite Y/N"; "pagination (ignored)";
                 "process_includes Y/N")

The function returns a TEXT.

This function has no effect on the AiaDocXML and HTML output.

put_in_document has five parameters:

document_to_be_produced, type TEXT. This is the name of the document.
path/folder_of_the_document, type TEXT. This is the path and name of the folder or a folder that the document is written to.
overwrite, type TEXT, Y or N. When you set this parameter to Y, the existing document is overwritten; when you set this parameter to N, the end user is prompted to specify an alternative file name or folder. Interactivity is not possible in a KCM Core environment.
pagination, type TEXT, Y or N. The value of this parameter is ignored but must be present.
process_includes, type TEXT, Y or N. When set to Y, KCM resolves __INC post-includes in the result document. In KCM Core, this setting is enabled by default.

The function put_in_document writes the KCM output to a document and does not create a copy. Once written to a document, the output is no longer available for a Template script and does not appear in the result document. The reason for this is that KCM stores produced text in an internal buffer. When you call the put_in_document function, KCM writes the content of the buffer to the document, which clears the internal buffer.

To create multiple files from one output, you can use the open buffer mechanism (see open_buffer).

Documents that KCM produces through the put_in_document( ) function are directly available for opening after the function has been successfully completed.

An example is provided here.

#
This line will be stored in the document 'document.doc' on c:\temp, and will not appear in the result document.
#
TEXT doc := put_in_document("document.doc"; "c:\temp"; "Y"; "N"; "N")
#
The document produced is @(doc). 
These lines will appear in the result document because they are produced after the put_in_document call above.
You could also write these lines to a second document by calling put_in_document again.
#

If you call the function put_in_document in a Microsoft Word DOCX Master Template, you should be aware that the text part you produce by calling the function must end with a paragraph ending.

You cannot place the text from repeated calls to put_in_document( ) in the same document. To retrieve the text from several calls in one document, use the add_to_output function. To leave the result document intact, you can use the open buffer mechanism (see open_buffer).