› KCM Template Scripting Developer's Guide › Functions › Control functions › put_buffer_in_document

put_buffer_in_document

The put_buffer_in_document function is always used in combination with the open_buffer function (see open_buffer). This function can only be used in combination with KCM Core.

These functions together save parts of a result document to a location on the file system while the saved part is also written to the result document, as opposed to the put_in_document function (see put_in_document).

The put_buffer_in_document function saves all text from the location where the marker tag was registered up to the call to this function. Markers are registered using the function open_buffer. 

put_buffer_in_document ( document_name;folder_name;overwrite_Y/N;
                         pagination_Y/N;process_includes_Y/N;marker_name )

The result of the function is of type BOOL. The function yields TRUE if the result document could be written. The function yields FALSE if the file could not be written or if the function is not supported.

This function affects only Word output.

The function put_buffer_in_document call has six parameters separated by semicolons:

  • document_name, type TEXT. This is the name of the document that will contain the text fragment.
  • folder_name, type TEXT. Path and name of the folder that the file is written to. This folder must exist.
  • overwrite, Y or N, type TEXT. When you set this parameter to Y, the existing document is overwritten.
  • pagination, Y or N, type TEXT. The value of the option is ignored, but the parameter must be provided. Enter N.
  • process_includes, type TEXT, with accepted values Y or N. If this parameter is set to Y, KCM always includes post-includes. If this parameter is set to N, the global post-include configuration determines whether or not post-includes are included. KCM Core enables the lazy post-include feature by default. The Master Template should use the @(inc(...)) construction to ensure that documents are included correctly. For more information, see inc.
  • marker_name, type TEXT. The name of the marker from where the result text has to be saved. This marker must have been placed with the open_buffer function (see open_buffer).

The function put_buffer_in_document fails if one of the following conditions is met:

  • The name of the buffer is invalid (empty).
  • The buffer has not been opened with the function open_buffer.
  • The document cannot be written.
  • The document already exists and the overwrite parameter is not set to Y.

Calling the function put_buffer_in_document removes the marker specified.

An example is provided here. 

 BOOL ok2 := put_buffer_in_document( "document";
"folder"; "Y"; "Y"; "N"; "example" )

Part of the result text starting with the marker example is written to the file document that resides in the folder folder. If the file already exists, it is overwritten. pagination is not yet implemented and post-includes set with __INC are not processed. After this, the marker example is removed from the result document.