put_buffer_in_document

The function put_buffer_in_document is always used in combination with the function open_buffer. These functions together save part of a result document to file while the saved part (as opposed to the put_in_document function) is also written to the result document.

This function will save all text from the location where the marker tag was registered upto 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 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 (ITP/Workstation)

The function put_buffer_in_document call has six parameters, separated by semicolons (;):

1. The parameter document_name, type TEXT. The name of the document that will contain the text fragment.
2. The parameter folder_name, type TEXT. Path and name of the folder where the file will be written.

   Note

   This folder must exist.

3. The parameter overwrite, type TEXT either Y or N. When you set this parameter to Y an already existing document is overwritten.
4. The parameter pagination, type TEXT, either Y or N. The value of this parameter is ignored but it must be present in the call.
5. The parameter process_includes, type TEXT, with accepted values Y or N. If this parameter is set to Y ITP will always include any post-include documents. If this parameter is set to N the global post-include configuration determines whether or not post-include documents are in cluded. Note that ITP/Server enables the lazy post-include feature by default. The model should use the @(inc(...)) construction to ensure that documents are included correctly. Refer to inc for more details.
6. The parameter 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 function 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 will remove the marker specified.

This function can only be used in combination with ITP/Server.

Example

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

In other words, part of the result text, starting with the marker "example", will be written to the file "document" that resides in the folder "folder". If the file already exists it will be overwritten. Pagination is not yet implemented; the parameter is ignored, and post-includes set with __INC will not be processed. After this, the marker 'example' is removed from the result document.