GoFiler Legato Script Reference   Legato v 1.5d Application v 5.25a

Table of Contents	< < Previous	Next >>

 

Chapter Twenty-two — Conversion Functions (continued)

TranslateSetPreProcessHook Function

Overview

The TranslateSetPreProcessHook function sets a hook for pre processing on an import function.

Syntax/Parameters

Syntax

int = TranslateSetPreProcessHook ( string script, string function );

Parameters

script

An optional string that specifies the script that will service the translate. If empty, the script name from the script executing the function is used.

function

A string specifying the name of the entry function for translation. If the script and function strings are empty, the hook is reset.

Return Value

An int as ERROR_NONE (0) or a formatted error code on failure.

Remarks

A pre process hook can be used to perform refining or other functions prior to translation. The pre process does not presently run on Paste Special operations.

The script is run “cold” each time and as such, any variables set from execution to execution are discarded. Use the session data functions to store intermediate data. See section Section 4.15 Session Data for additional information.

This function allows the import and translate function to be extended or even replaced by pre processing. An example of adding a hook:

TranslateSetPreProcessHook("", "import_adjust");

Note that the script name parameter is an empty, thus the hook script is the source for the specified connection. The hook is normally defined during application startup. See Section 17.2 Application Startup for more information.

The script parameter is tested for existence on setting the hook. The function parameter is not tested. Neither the script’s syntax or functionality is tested while setting the hook. On hook execution, a script error will be added to the log and the script hook will be removed.

The hook entry point in the script must match the following template:

string pre_process_hook (string xl_type, string xl_src, string xl_dst,
                     string xl_dst_base, dword xl_flags, string xl_options);

Where

xl_type

A string contain the name of the conversion performed.

xl_src

A string containing a fully qualified source file. It can be a URI. The source should be used for reference purposes as it specifies the data that has already been converted.

xl_dst

A string containing a fully qualified destination file. The file can be in the application (user’s) temporary area. This is the file that can be opened and manipulated during the post process. In some cases, the destination can be empty. If the destination is not resolved within the hook, the user will be queried prior to translation.

xl_dst_base

A string containing a the base path for the destination. If image or other companion files must be created, they should be placed in this folder.

xl_flags 

A dword specifying various control bits.

xl_options

A string in the form of parameter: value pairs that may be passed with data from the API or other source and can be used by the script to set various options. These are override values from the default settings.

The xl_flags parameter tells the hook about the context and requested operations. These are bitwise items specified as follows:

	Definition			Bitwise		Comment/Description
	Shares with Options Settings
		XL_GLOBAL_FLAGS_MASK		0xFFFF0000		Global Import/Translate Options
		XL_MODULE_FLAGS_MASK		0x0000FFFF		Reserved Import/Translate Options
		XL_SUB_TYPE_MASK		0x0000000F		Sub Type of Conversion for Module
	General Flags
	Control
		XL_QUIET		0x00010000		Do Not Display Messages
		XL_PSG_FORMAT		0x00020000		Output in PSG Format (if possible)
		XL_NO_NEW_LINES		0x00040000		Output With 0x0D (not 0x0D/0x0A)
		XL_WANT_LOG		0x00080000		Output Errors to Translate Log
	Context
		XL_CONVERT_AS_INSERT		0x00100000		Treat as Inserting
		XL_MULTI_IMPORT		0x00200000		Importing Multiple Sheets
		XL_SOURCED_FROM_CLIPBOARD		0x00400000		Sourced from Clipboard
	Multiple Files
		XL_GROUP_IMPORT_MODE_MASK		0x03000000		Multiple File Mode (if supported)
		XL_GROUP_IMPORT_SINGLE		0x00000000		Import Single File
		XL_GROUP_IMPORT_MULTIPLE		0x01000000		Automatically Import Multiple
		XL_GROUP_IMPORT_QUERY		0x02000000		Query if Multiple

 

The default log for the script is imported back into the caller to the hook and then included into the Information View window.

The XL_SOURCED_FROM_CLIPBOARD flag will indicate whether the source data was retrieved from the clipboard. If the XL_QUIET, the hook should not display message boxes or dialog boxes.

A string is returned with optional override parameters. If a parameter is not placed in the array, the existing internal value is used. The parameter names are as follows:

	Return Parameter Name		Description
	Source		If present, the source filename is replaced with this name.
	Destination		If present, the destination filename is replaced with this name. If the incoming name is empty or an empty string is returned, the user will be queried regarding the destination.
	TranslateType		Replacement translate code or index. If not adjusted and the in/out format codes remain unspecified, the existing index passed as the xl_type incoming parameter value will be employed.
	InFormat		Adjusted input file type as code or value in hex. If a format is provided without a TranslateType, the translate processor will reevaluate which translate module to employ.
	OutFormat		Adjusted input file type as code or value in hex. If a format is provided without a TranslateType, the translate processor will reevaluate which translate module to employ.
	View		A destination view index, if appropriate.
	Flags		Replacement for xl_flags.
	ResultCode		Returned error code. Setting a formatted error code will abort the translation process. Setting this to any value will cause the translate to stop.

 

The ResultCode can be set to the value or string “ERROR_NONE” if the preprocess wants to terminate the process as if no error occurred. Other errors can also be returned in the ResultCode field which will be passed back up the calling chain.

The script should perform its own cleanup.

Related Functions

AddMessage — Adds a formatted message to the default or a specified log, or other object.

GetFileTypeCode — Gets file type by file content or extension and return type as code dword.

GetFileTypeString — Gets file type by file content or extension and return type as string.

LogAppendLog — Appends the contents of a specified log to another specified log or the default log.

LogIndent — Indents log messages for subsequent messages.

LogOutdent — Outdents log messages for subsequent messages.

LogSetMessageType — Sets the message type for the next message added.

TranslateGetPostProcessHook — Returns the name of the script and function for the post process hook.

TranslateGetPreProcessHook — Returns the name of the script and function for the pre process hook.

TranslateSetPostProcessHook — Sets a post process translate hook.

Platform Support

Go13, GoFiler Complete, GoFiler Corporate, GoFiler, GoXBRL

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 12/16/2024

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.