6. Macro tags for Corbit

Special macro that will return a single comma character ','.

Special macro that will return a single percent character '%'.

The name of the action in the current context where the macro is evaluated.

This macro will return a Portfolio asset ID. The returned ID is from the current asset in the handling scope, see the section Assets in scope for more details.

This will get the field named key from the current asset in the handling scope, see the section Assets in scope for more details.
If, for example the field Filename is wanted the macro %ASSET[Filename]% should be used. The key is case sensitive.

This macro is similar to the ASSET macro above. The difference is that the ASSET_LIST macro is used when the value of the field key may have multiple values, for example the field Keywords.
The delimiter is the character sequence that will be used to separate the values and create the result text.

Example: If we have an asset with the field Keywords set to Apple and Banana, the macro %ASSET_LIST[Keywords,#]% would result in Apple#Banana.

This macro will return a XML structure for the current asset in the handling scope, see the section Assets in scope for more details.
The XML output will have the following structure;

 

<asset id="[id]" [field name]="[value]" ...>

<[field name]>[value]</[field name]>

<[field name]-list>

<[field name]>[value]</[field name]>

</[field name]-list>

...

</asset>

 

Each key in the asset that is of type boolean,datetime,decimal,number or url will be in the root asset parameter list along with the asset ID.
Fields of type geojson, geopoint, picture, string or textblocks will have their own tags (the tag name is the field name).
Other fields that may have multiple values will be added in their own tags that are named as the field name with an added '-list'.
This tag then contains all separate values in tags that are named as the field name.

For example, if an asset has the field Keywords with values Apple and Banana the output would be

 

<asset id="12345" ...>

<Keywords-list>

<Keywords>Apple</Keywords>

<Keywords>Banana</Keywords>

</Keywords-list>

...

</asset>

From this ASSET_XML macro XPATH macro may be used to fetch specific values.

Will return the catalog-ID that belongs to the current Portfolio Asset. This macro is only useful if there is such an asset in the current scope.
This is available in the scope if you e.g. have a Portfolio Source or if you have a “for-each-asset-action”

This macro is mainly for internal use.

In the container of the running application, servlet or applet there are some internal parameters which may be called with this macro. The parameter key differs for each container.

This will take a text and make a base64 encoded text from it. The optional encoding may be used if the source text is in a specific format.

This macro is the opposite to BASE64. The macro will handle a BASE64 coded text and decode it.
As an example: using %BASE64_DECODE[%BASE64[this is a text]%]% will give the result ”this is a text”, (First it will be coded as BASE64, and then it will be decoded.

This will take a file and put create a Base64 encoded string from the content. The path argument is the full path to the file to encode.

Gets a value from the object's bucket (i.e. the object that is currently being handled). This can for example be useful in an action to get a value from another action that has been invoked before the current action.

The <key> is the key that previous action has used to put the value in the bucket. See the documentation for different actions to see what they put in the bucket.

Note that the Workflow itself also puts some values in this bucket before any action is executed.

Note that this bucket is different from the Workflow bucket which may be used with the macro %Workflow_BUCKET[...]%.

Read more about the different buckets in chapter 2.

This will return the number of files that are present in the object bucket with the key <key>. If <onlyFiles> is equal to 'true' then the count will only include the files, if 'false' the count will include files and folders. The value in the bucket has to be a list of files (see different actions for more information what they put into the bucket).

This will return the names of files that are present in the object bucket with the key <key>. If <onlyFiles> is equal to 'true' then the names will only include the files, if 'false' the names will include files and folders. The value in the bucket has to be a list of files (see different actions for more information what they put into the bucket).

The returned list is a comma separated list of file names.

This is a macro that will join a list to a single string with a certain delimiter.

This macro will take a bucket value, regard this value as a list of items (for example from the special -list bucket key created in the database action) and join these items with the specified delimiter.

Example: If the bucket key paper-list contains a result list from database action and has the following items: news, sports, ads. Using the macro %BUCKET_LIST[paper-list,#]% will result in the following string: news#sports#ads

NB! If a comma (,) is wanted as the delimiter, the comma must be preceeded with a percent sign (%,).

This macro will work on a bucket list (e.g. a value from a database call). The macro will not return anything, it will only remove all the duplicate entries in the given bucket value.

Example: If the bucket key paper-list contains a result list from database action and has the following items: news, sports, news, ads. Using the macro %BUCKET_LIST_REMOVE_DUPLCIATES[paper-list]% will change the items in the bucket, resulting in the following items: news, sports, ads

This macro is evaluating a condition and will return different values depending on the condition result.

The paramater <exp> which is evaluated must be a valid expression, see below.

If the expression is evaluated to true, the <t> text (which may contain other macros) is parsed and returned. If the expression is false the <f> text is parsed and returned.

The expression <exp> must contain one (the first occurance is taken) of the following mathematical expression

Will return the character that has the unicode decimal number <no>.

path may be empty, then the current file will be used as source, otherwise the path is used as source for which file to be analyzed. bucket specifies which bucket value should be set.
The bucket values will be a list (where you as an example later may use %BUCKET_LIST…%) with the name of all clipping paths that an image file contains.

This macro is similar to %SEPARATE_BY_ROW[…]% but will expect CSV structured text that will handle quotes etc.

Parameters:

This macro is used to separate a single row of a CSV formatted text. This macro is normally used within the handling parameter of the macro %CSV_PARSE_ROWS[…]%.

Parameters:

Simple form

In the simple form, returns the current date in the format yyyy-MM-dd.

Variant [<format>]

If <format> is specified the result will be in the specified format. The format may contain special characters such as dot (.), comma (,) (note! if a comma is to be used as separator it must be escaped with a '%' in order to be handled correctly) and hyphen (-). The characters below shows how to get a certain format. The number of each character decide the result date string, e.g. in the year 2006, yyyy would result in 2006 while yy gives 06.

Variant[+<d>,<format>] or [-<d>,<format>]

If the first parameter starts with a plus sign or minus sign the specified <d> number of days will be added or withdrawn respectively from the current date before the result is calculated. The <format> is as described above.

This macro will use a date/time and will then add (or subtract if a negative number is used) and return the new date/time.
sourcedate is the input date/time
sourceformat is the format of how the sourcedate is specified.
unit indicates one of the following (day, hour, minute, second) and is then the unit to be changed.
amount indicates how many of a given unit that should be added (or subtracted if a negative number is used)
outputformat specifies the desired final format of the time output.

Example: %DATE_CHANGE[2022-05-04,yyyy-MM-dd,day,7,ww]% Will return the week number if 7 days is added to the date 2022-05-04, so the result would be “19”

This macro will compare two dates and return the difference in seconds between them.

The parameter date1 and date2 are strings representing dates. Each of them should conform to the date1 format and date2 format (see macro %D% for more information about the formats).

The returned value is the difference between the two dates in seconds. If the dates are the same 0 is returned. If date1 is before date2 a negative number is returned.

This macro is only used in actions where a destination file is created. This macro will have no effect if the file that is created does not exists. If the file being created exists this macro will determin how a new name will be created. Note that the special macro %FREE_INDEX% may be used in this macro's text parameter.

In most cases where this macro may be used there is a checkbox in the setup allowing the file to be overwritten. This checkbox has no effect if this macro is used in the action.

This macro replaces the setup in Corbit version 5 and older where the user could specify a prefix to add to the file name if the result file existed. With this macro the file name may be changed in more ways than just a prefix.

NB! This macro can not currently be used in the FTP send action!

 

 

Note that this macro is only useful in the context where a single file is referred.

File name suffix (dot included) if any. If the file does not have any suffix an empty string is the result.

Gets the eml content of the email in scope (must be used with an email source in the workflow).

Note that the eml content may be large so preferrably the variants are used to write a file.

Output (index 1) is the path to a file where the result will be written to.

If output is used, the result from the macro itself will be empty, all content is written to the output file.

Simple form

If the object being handled is an email this will return the body of the email. If the email contains more than one body the returned text will primarly be the plain text body, secondly the html coded body will be returned.

Variant [<mime>]

This will primarly return the email body in the special mime format <mime>. If the email does not contain any body in the specified mime format an empty string is returned. Example of mime types: text/plain or text/html

This will, if the object being handled is an email, return the email's received date.

This macro works as the date macro %D% with all the variants of parameters.

If the object being handled is an email, this will return the sender's email address.

If the object being handled is an email, this will return the sender's full name.

This will, if the object being handled is an email, return the email's sent date.

This macro works as the date macro %D% with all the variants of parameters.

If the object being handled is an email, this will return the email's subject text.

Similar to the macro EMAIL_SENDER_ADDRESS (that will fetch the address that an email was sent from).
EMAIL_TO will return the address of which the current email is sent to. If the email is sent to multiple recipients all the addresses will be received with a comma in between.

If the object being handled is an image with EXIF information, this will return the EXIF information found in EXIF field number <no>.

Note that this macro is only useful in the context where a single file is referred.

Simple form
The file name stem (i.e the file name but without the file name suffix and belonging dot).

Variant [<s>,<e>]

Part of the file name stem. Start at index <s> (the first character has index 1) and end at index <e>. If <s> is not specified, 1 is used. If <e> is missing the last character index is used. Note that the comma characters must be present even if either <s> or <e> is left out.

Variant [O,<ch]>

The first parameter is the letter 'O'. This gives a part of the file name stem starting at the first character and take all characters before the first occurance of <ch>. If <ch> is not found in the file name the result is the same as %F%.

Variant [O,<ch>,<no>,<l>]

The first parameter is the letter 'O'. This gives a part of the file name stem starting at the first occurance of <ch>. Then move <no> steps (a minus sign may preceed <no> to go backwards). This is now the start position and <l> number of characters are read. If <l> is missing the rest of the file name stem is read. Note that the last comma must be present even if <l> is left out.

Variant[OI,<index>,<no>,<l>]

The first parameter is the letters 'O' and 'I'. This gives part of the file name stem starting at character <index> (first character is index 1, if the last character is wanted then use -1). Then <no> (number) steps will be taken (minus sign may preceed <no> to go backwards). This is the start and from here <l> number of characters are read. If <l> is missing the rest of the file name stem is read. Note that the last comma must be present even if <l> is left out.

Reading the file with path <file> (the path is depending on the environment from which this macro is called) and returns the content in the file in the selected text format <format>.

If the format is omitted, 'UTF-8' is used as default format. Note that the comma must be present even if <format> is left out.

Optionally the <start> and <end> parameters may be used. These will indicate the start and end location to get a portion of the file content. The start and end parameters are the byte location. The first location in the file is zero (0).

The simple macro without any parameters will get the content of the file currently in the scope of the macro.

When using parameters the <file> parameter may be empty in which case the file currently in scope will be used, e.g. %FILE_CONTENT[,ISO-8859-1]%

This macro is only useful in contexts where a file is present.

This will get the file dimensions in mm. The returned value will be the width followed by a ' x ' (space, x and then another space) followed by the height value.

The first parameter is the number of decimals to use, if this parameter is missing the default value is set to zero (0) decimals.

The second parameter is only useful when the file is a PDF file. This is then the PDF box to use when getting the dimension. If this is left out the default order will be trimBox,mediaBox,cropBox,bleedBox,artBox.

Also see macro FILE_DIMENSION_W and FILE_DIMENSION_H for more information.

This macro is similar to FILE_DIMENSION but will only get the height value.

This macro is similar to FILE_DIMENSION but will only get the width value.

Checks if a certain file (with the path <path>) exists. This will return "true" if the file exists and "false" otherwise. The path that is given must be availalbe from the Corbit server. See also %SOURCE_FILE_EXISTS[...]%.

Returns the count of pages in the file. Teh default macro without any parameter will check the current file in context. If the parameter is present this will be taken as the path to the file to check.

Only PDF files will be calculated with their real page count, other files will return 1.

XXxx

Possible parameters for FILE_LIST

Note that this macro is only useful in the context where a single file is referred.

The current file's parent folder path.

Note that this macro is only useful in the context where a single file is referred.

The full path to the current file.

This will fill the <text> with a certain <filler>. The first parameter is either start or end depending on whether you want the filler to precede or append the text. The max length

parameter is the max number of characters that the result will have.

Example) Using %FILL[start,12345,0,10]% will result in 0000012345

The name of the filter in the current context where the macro is evaluated.

This macro will check a certain folder (disc folder available from the Corbit server), count all the files in that folder and return the count.

The result is the number of non-hidden files (excluding folders) found directly in the folder.

This macro will check a certain folder (disc folder available from the Corbit server), count the number of bytes of all files, including subfolders and return the count.

The result is the byte size of all non-hidden files (including subfolders) found in the folder.

This macro will act on each item in a bucket list.

The key parameter is the bucket key that currently holds a list of values (for example from a database search).

The parameter tmpKey can be any value and this will be used to place each entry in the bucket list to perform whatever is set in the macro parameter. Make sure that you use a unique value for the tmpKey parameter.

The last parameter, macro, can be any other macro or static text. Each entry in the bucket list will be set to the result of this macro parameter.

 

This macro is used to convert a text from one date format to another. For the different pattern characters, see the %D% macro.

The <text> is the source date specified in the <from> format. The result is the same date specified in the <to> format.

This macro is a special macro only used within the macro %DUPLICATE_FILE_EXTRA[...]%

This macro will return the first free index in a duplicate file scenario.

Returns a HTML formated text based on the <text>. Entities such as ä will be used instead of ä and so on.

Returns the image height of the currently handled image file (if any). The format parameter is optional and may be either mm or px resulting in the image height specified in millimeters and pixels. If the format parameter is not present (using %IMAGE_HEIGHT%) the height is returned in pixels.

Returns the image width of the currently handled image file (if any). The format parameter is optional and may be either mm or px resulting in the image width specified in millimeters and pixels. If the format parameter is not present (using %IMAGE_WIDTH%) the width is returned in pixels.

Special macro used in PDF split action where the current index of the split PDF could be used in for example the resulting file name.

The text <s> is searched and the index of the first occurance of <t> is returned. The index is zero based meaning that if <s> starts with <t> the returned index is '0'. If the <t> is not found in <s> -1 will be returned.

Both <s> and <t> might contain macro text themselves.

If the optional <start> parameter is present this is the start index in the text from which the search starts. Any occurance of <t> before this index is not counted. The <start> index is zero-based meaning that the first character in <s> has the index 0 (zero).

If the object being handled is an image with IPTC information, this will return the IPTC information found in IPTC field number <no>.

NB This will only read from the regular IPTC information, not the XMP information. For XMP data use the XMP macro.

The text <s> is searched and the index of the last occurance of <t> is returned. The index is zero based meaning that if <s> starts with <t> the returned index is '0'. If the <t> is not found in <s> -1 will be returned.

Both <s> and <t> might contain macro text themselves.

If the optional <start> parameter is present this is the index in the text from which the search starts (seen from the end). Any occurance of <t> after this index is not counted. The <start> index is zero-based meaning that the first character in <s> has the index 0 (zero).

Returns the length of the <text>. The number of characters in <text> is counted and returned.

This macro may be very useful used for example in an expression, see macro CASE for more information.

The returned value is <text> where each character is in lower case in the returned value.

This will invoke the mathematical expression <math command> on the <leftExpression> and <rightExpression>. The returned number will have the maximum decimal count that is expressed in the parameter <decimals>. The <leftExpression> and <rightExpression> may contain numbers (possibly from other macros).

The <decimals> parameter is optional. If <decimals> is left out the last comma should also be left out.

The <math command> may be any of the following;

Note that this macro is only useful in the context where a single file is referred.

The macro will return the modification time for the current referenced file. The variants for the macro follow the D macro where more information may be found for the different parameters.

Gets the modification time of a file in milliseconds.

The default version will get the modification time from the current file in scope. The alternative is to pass a file path as parameter which will get the modification time of that file.

If the object being handled contains ID3 tags the value from the album tag is returned.

If the object being handled contains ID3 tags the value from the artist tag is returned.

If the object being handled contains ID3 tags the value from the comment tag is returned.

If the object being handled contains ID3 tags the value from the genre tag is returned.

If the object being handled contains ID3 tags the value from the title tag is returned.

If the object being handled contains ID3 tags the value from the track tag is returned.

If the object being handled contains ID3 tags the value from the track count tag is returned.

If the object being handled contains ID3 tags the value from the year tag is returned.

The returned value is <text> where each carriage return and line feed is removed. The carriage return is replaced with a space character if there is no space preceeding the carriage return. This means that even if there are multiple carriage returns immediately following eachother in the original text, they will only be replaced by maximum one space character.

Note that this macro is only useful in the context where a file is referred.

This macro is similar to the F macro but the name is taken from the parent folder. All variants of the macro that are applicable to the F macro are also available to this macro.

Returns a modified version of <s> where all the occurancies of <source> are replaced with <target>.

type may be "object", "workflow" or "system" (“object” is default, ie the macro variant without type means that "object" is used as type.)
key is the "key", and value is the "value". This macro will then set a bucket-value (similar to a bucket-action)

This macro will separate a source text (the source must be structured with one or more delimiters).

Parameters:

Very similar to %SEPARATE[…]% but this macro will work with multiple rows. Each handling will take place on each row and column and macros such as %SEPROWNUM% may be used.

Parameters:

This macro will return the current row number (the first row has row number 1). This is only useful when present within the handling of %SEPARATE_BY_ROW[…]% or %CSV_PARSE_ROWS[…]%.
If the separation macros are nested the name parameter may be used to get the data from that specifically named separation.

This macro will return the current column number (the first column has column number 1). This is only useful when present within the handling of %SEPARATE_BY_ROW[…]% or %CSV_PARSE_ROWS[…]%.
If the separation macros are nested the name parameter may be used to get the data from that specifically named separation.

This macro will return the current value in the scope.. This is only useful when present within the handling of %SEPARATE_BY_ROW[…]% or %CSV_PARSE_ROWS[…]%.
If the separation macros are nested the name parameter may be used to get the data from that specifically named separation.

This macro will return a header value (the name of the header if headers are present). Using the macro without parameters will return the current column's header value.
If the parameter column index is present, the header for that particular column's (the columns are numbered started from 1) header will be returned. If the separation macros are nested the name parameter may be used to get the data from that specifically named separation.

This macro is similar to %SEPVALUE[…]% but this macro will return the value of any given column index at the current row. This macro may be useful if the handling of the current column is dependent of another value in the same row.

Parameters:

This macro is similar to %SEPVALUE[…]% but this macro will return the value of any given header at the current row. This macro may be useful if the handling of the current column is dependent of another value in the same row.

Parameters:

Safe File Name - This will return the <text> where all occurancies of the following characters are replaced with underscore (_);

This macro may be used to check if a certain file exists. The macro will use the specific source in the scoop of the macro to find the file. If this source is a FTP source the FTP server will be checked for the file wanted.

Compared to the macro %FILE_EXISTS[...]%, this macro may also be used in a FTP source context to check if a certain file exists on the FTP server.

This macro will check a certain folder found on the source, count all the files in that folder and return the count.

The result is the number of non-hidden files (excluding folders) found directly in the folder. The macro will use the specific source in the scoop of the macro to find the file. If this source is a FTP source the FTP server will be checked for the file wanted.

Compared to the macro %FOLDER_FILE_COUNT[...]%, this macro may also be used in a FTP source context to get the count from the FTP server.

The name of the source which is the invoking source of the object in the current context where the macro is evaluated.

Gets a value from the current Workflow's bucket. Teh Workflow bucket is a static bucket which holds information that will remain in the Workflow as long as the Workflow exists. This bucket is different than the object bucket which is used with the macro %BUCKET[...]%.

Read more about the different buckets in chapter 2.

The name of the Workflow within which context the macro is evaluated.

Special macro that will replace all characters except the ones in the list below with a underscore (_)

Characters that will remain unchanged are:

. (dot)

- (dash)

_ (underscore)

0-9 (numbers)

a-z (character a to z)

A-Z (character A to Z)

Returns a portion of the soruce string <s>. The portion is taken from index <start> (included) and ends at index <end> (not included). If <end> is missing the rest of the string is taken from the start. If <start> is missing the substring will be taken from the start. The index are zero-based meaning that the first character in <s> is having number 0.

Note that if <start> and/or <end> is left out the commas still need to be present.

Returns a modified version of <text>. The return value is specialized to fit in XML documents where characters are replaced with entities, e.g. 'å' is replaced with '&aring;'. Characters with UTF character number more than 128 are replaced with the entity '&#<no>;' where <no> represents the UTF value of the character.

The string <text> may contain macros.

The result from this macro is the text parameter without any space characters before and after the actual text. Space characters that will be removed includes space, tab, carriage return and line feed.

This new macro is adopted to our macro version 2 where all the parameters inside the brackets are either indexed or named.

If you use the naming convention you may put the parameters in any order as long as you name them (name=value).

For example the TEXT_CONTENT macro has a parameter named format so you may write the macro

%TEXT_CONTENT[format=text,…]%

The possible parameters for TEXT_CONTENT are;

• input
Defaults to the current file in scope

• format
Can be either 'text' or 'html' (without the quotes). Defaults to text.

• output
Optional path to an output file to write to. If this parameter is present the macro itself will not return anything but the result will be written to the output file.
If this parameter is not present, the macro will return the result text (for example if the macro is used in a text file action, you do not want to use this output parameter but you want the output in the text where the macro is present).

• output_encoding
Optional if the output parameter is present to specify the output text encoding,. Defaults to UTF-8

• output_append
Only if output parameter is present, this may be 'true' or 'false'. Defaults to 'false'. If true the output will be appended with this new result.

The returned value is <text> where each character is in upper case in the returned value.

The returned value is a unique ID.

The XMP data from the file isread and the value from the specified xmpID is returned.

The xmpID is an identifier which is unique for each XMP data. The default XMP data fields' identifiers may be seen as tooltip in the special XMP popup menues that are available in the setup. Customized XMP data has their own identifier specified when created chosen by the user. The xmpID is the XMP prefix followed by a colon and then the property field name, e.g. tiff:Compression

The value returned is always a string representation even if the value may be a date or another object.

If no filePath parameter is given, the file currently in scope of the macro will be read, otherwise the file given by the filePath.

This macro will calculate an XPath expression from the given string (XML format). The returned result is a string representing the result of the XPath expression.

The parameter string is the XML string on which the XPath expression will be calculated.

Only the string and xpath expression parameters are compulsory, the rest of the parameters are optional and if exists they should all have the following structure: prefix=URI. These parameters are used to identify namespaces in the XML string, the prefix is the namespace prefix and the URI is the namespace URI. For example the IPTC core namespace would have the following value: Iptc4xmpCore=http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/

For more information about valid XPath expressions, see http://docs.oracle.com/javase/tutorial/jaxp/xslt/xpath.html

Very similar to the XPATH macro. The result from this XPath expression will be taken as a node value and the result will be this node as XML compared to the XPATH macro which will force the result to a string value.

The parameters are the same as the XPATH macro.

For more information about valid XPath expressions, see http://docs.oracle.com/javase/tutorial/jaxp/xslt/xpath.html

This macro will calculate an XPath expression from the given string (XML format). The returned result is a list of values and will be saved in the current bucket with the given bucket key.

The parameter string is the XML string on which the XPath expression will be calculated.

Only the string, xpath expression and bucket key parameters are compulsory, the rest of the parameters are optional and if exists they should all have the following structure: prefix=URI. These parameters are used to identify namespaces in the XML string, the prefix is the namespace prefix and the URI is the namespace URI. For example the IPTC core namespace would have the following value: Iptc4xmpCore=http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/

The list which is placed in the bucket key may be used in other special macros handling lists, e.g. %BUCKET_LIST[...]%.

For more information about valid XPath expressions, see http://docs.oracle.com/javase/tutorial/jaxp/xslt/xpath.html

Note that this macro is only useful in the context where a zip file is referred.

This macro is similar to the F macro but the name is taken from the zip file (e.g. in the unzip action where %F% will give the unzipped file name but %ZIPF% will give the original zipped file name). All variants of the macro that are applicable to the F macro are also available to this macro.

This will get the value from the system bucket named 'key'

date: original date / time to expire, eg 2017-12-13
format: The format that 'date' has, like yyyy-MM-dd, see% D% for all formats
unit: one of the following: 'day', 'hour', 'minute' or 'second'
amount: number of 'unit' to be added or deducted
resultFormat: The format you want for the final date / time
ex% DATE_CHANGE [2017-12-13, yyyy-MM-dd, day, 11, dd / MM-yyyy]% will give '24 / 12-2017 '

Parses a Json text to get a property. json: A json formatted text wanted: the wanted property from the json

This will remove any Byte Order Mark (BOM) character from the 'text' parameter.

Replaces the 'text' parameter with 'replacement' where there is a character not suitable for a file name. The following characters are removed:
All characters with ASCII code <32
char 34 (")
char 38 (& )
char 39 (')
char 42 (* )
char 47 (/)
char 58 (: )
char 59 (; )
char 60 (<)
char 62 (>)
char 63 (?)
char 92 (\)
char 124 (|)
any char between 57344 and 63743
char 65533 (unicode replacement character)
+ any other character that is undefined

Note that if replacement is missing, the default replacement will be empty (ie. the illegal characters will be removed and not have any replacement character).

Translates 'text' into application/x-www-form-urlencoded format. Any '+' characters will also be encoded to '%20'

Very similar to XPATHLIST. The result bucketKey will be populated with a list instead of text. So using list macros after this macro is possible, for example BUCKET_LIST.