Skip to main content

xSuite Interface Windows Prism 5.x – Online Help

Functions

A function consists of the name of the function followed by round brackets with a comma-separated list of parameters:

{function name}({parameter1}, ..., {parameterN})

Even if the parameter list is completely empty, always use round brackets to syntactically identify the function as such. Some functions have parameters whose specification is optional; however, since the parameters are not identified by a name (but only by the order in the parameter list), if a parameter is omitted, then the separator must still be listed if there are other parameter values following it. For example, in a Test() function with 3 parameters, the last two of which are optional, Test(Param1, , Param3) or Test(Param1) would be correct, but Test(Param1, Param3) would not.

Depending on what type it is, a function may or may not return a result value. Independent of this, some functions have special parameters for (additional) return values, but only indirectly in the form of a field name, not a field variable. The function parameters serve exclusively as input parameters. Thus, in the case of a variable @fieldname, a value of this field changed in the macro is not written directly back to the variable. Instead, specify the "field name" as a parameter value. Through this value, the macro will then identify the field in the document and will change the value of this field.

The available functions and the specific parameters required in each case can be found at Macro Functions.

Macro functions differ in their basic tasks and operations, and can be broken down into the following four types:

Field Macros

A field macro function returns a single execution result, usually assigned to a field; however, macro expressions of this type can also be used in other contexts, in particular as subfunctions that calculate a parameter value for one of the other macro functions, and for dynamically generating values of certain configuration properties.

A field macro is not only an expression in the syntax of a function, but any macro expression that produces a result value. This could be an operator with its operands, a single variable, or a constant value.

Document Macros

A document macro function usually performs content changes directly on the data of the currently active document where the macro function is called. Macro expressions of this type will not return a value as a result of the function execution.

Document macros are mostly used to make changes to the document's index data that go beyond a single field value.

Since there is no return value, document macros cannot be combined with other macro elements and are therefore usually at the top level of a macro expression. Document macros can only be included in special functions which serve the conditional execution of a subexpression (e.g., in the function If()).

File Macros

For a file macro function, basically the same applies as for a document macro. However, for a file macro, the adjustments to the document content refer to the file attachments of the document and not to the index data. Typically, these adjustments mean converting the file attachments to another file format required for further processing or by an output system. However, there are also file macros that do not perform any conversion but perform other actions based on the file attachments (e.g., extracting embedded files or generating new attachments).

In all cases, the source files that are used as the basis for an action are retained as file attachments to the document. For example, during a conversion, the source file is not directly replaced by the target file in the new format, but an additional file attachment in the target format is added to the document. Where necessary, configure which alternative format of a single file is to be used in downstream work steps. For this, use file name filters. For the transfer to an output system, for example, this would be the OutputSystem[].FileFilter property.

The parameter list for file macros follows a fixed schema. The first two parameters are identical for all macros of this type. Only from the third position do the individual parameters of the respective macro follow.

  1. The purpose of the first default parameter is to define the name filter for the existing file attachments which are to serve as the source for the function execution. If this parameter is not specified, a default value matching the respective function will take effect (e.g., *.pdf for a function which is to process PDF source files). Basically, the function will sequentially process all found file attachments which match the specified pattern. If there are ambiguities (e.g., if multiple PDF file attachments are present), the name filter may need to be formulated more specifically (e.g., including parts of the file name instead of just the file extension).

    The processing sequence of the source files can be influenced by the order in which multiple sub-filters are defined. With a filter of the form A*.pdf | B*.pdf | *.pdf, for example, all PDF source files starting with A will be processed first, then all files starting with B, and finally all other PDF source files. Only the defined positive filters will be relevant. Negative partial filters with NOT(...) can be used, but have no influence on the sequence.

  2. As a second default parameter, you can define a name or name pattern for naming the created target file(s). File variables can be used as dynamic components in this configuration value (see file variables in Variables).

    Example: A function performs a format conversion from PDF to TIFF. %FileBaseName%.tiff" is specified as the parameter value. This parameter value gives the target file the same base name as that of the source file, but with a different extension. For functions that convert to a target format that is different from the source format, this type of naming is the default if the parameter is left empty. However, if the source format, the target format and, as a result, the file extension are identical, the target files are given a base name suffix such as .split or .extracted. This base name suffix matches the respective function by default, differentiating it from the source file. In principle, multiple file attachments can have identical names. However, for a targeted selection of attachments in subsequent processing steps, take care to ensure that the naming is unique.

Global Macros

Global macros are primarily meant for use in schedule worker tasks (i.e., for global actions that are executed independently of a processing scenario).

This macro function is not executed in the context of a document, so neither can the document content be modified nor the document-specific variables accessed. Furthermore, instead of returning a result value, this function only generates a log entry regarding the execution result.

Usually a global macro is configured as a stand-alone function call and is not linked to other macro elements. Only a reference to general system and environment variables is possible (e.g., to control a conditional execution of the macro).

Global macros can also be used as part of a processing scenario, even if this is not their primary purpose. The restrictions mentioned above then largely apply, and their use is the same as that of document macros. The only difference is that the global macro functions available are not designed to make changes to the document content.

In this section: