You can use the following functions when working with XQuery in Process Designer or in any field that uses a formula to set a value.
For information about XQuery functions that are available in the Expression Editor but are not described below, see http://www.xqueryfunctions.com/xq/alpha.html. Note that Application Integration doesn't support all functions documented in the URL.
Note: Application Integration does not support inline functions in the Expression Editor. The Expression Editor comes with powerful functions that can invoke operating system features. You must review the contents passed into the functions before using them.
Atomic Values of All Types
You can use the following functions in processes and service connectors:
•boolean
•empty
•exists
•false
•nilled
•not
•number
•string
•true
Attachments for Processes
The functions described in the following table are available for handling attachments in processes.
In case of a process, the $cid value in the attachment functions refers to the process field (Input, Output or Temp). For example, if the input parameter is called customerPhoto (of type attachment), to get the attachment size, use:
sff:GetAttachmentSize($input.customerPhoto)
Note: Be sure that your field names do not have spaces so they can be easily referenced in XQuery.
For more examples of using the attachment functions, see Attachments.
Function
Syntax
Description
createAttachmentFromBase64
sff:createAttachmentFromBase64($contentName as xs:string, $encodedContent as xs:string, $mimeType as xs:string)
Creates an attachment from the base64-encoded content.
getAttachmentContentType
sff:getAttachmentContentType($cid as xs:string?)
Returns the content-type.
getAttachmentCount
sff:getAttachmentCount($cid as xs:long)
Returns the number of attachments.
getAttachmentName
sff:getAttachmentName($cid as xs:string?)
Returns the attachment (file) name if available.
getAttachmentProperty
sff:getAttachmentProperty($cid as xs:string?, $attribute as xs:string)
Returns the attachment attribute, given the mime header name such as 'content-type'.
getAttachmentSize
sff:getAttachmentSize($cid as xs:long)
Returns the attachment size in bytes.
getBase64FromAttachment
sff:getBase64FromAttachment($cid as xs:string)
Returns base64-encoded attachment content from the variable, which has the attachment type.
hasAttachment
sff:hasAttachment($cid as xs:boolean)
Checks if an attachment exists.
setAttachmentContentType
sff:setAttachmentContentType($cid as xs:string, $val as xs:string)
Sets the attachment content-type.
setAttachmentName
sff:setAttachmentName($cid as xs:string, $val as xs:string)
Sets the attachment name.
setAttachmentProperty
sff:setAttachmentProperty($cid as xs:string, $attribute as xs:string, $val as xs:string)
Adds a specified amount to one part of a datetime value, and returns a date in the same format as the date you pass to the function. For more information, see addToDate.
adjust-date-to-timezone
fn:adjust-date-to-timezone(arg, timezone)
Adjusts a date value to a specific time zone, or removes the time zone component from the date value. For more information, see adjust-date-to-timezone.
adjust-dateTime-to-timezone
fn:adjust-dateTime-to-timezone(arg, timezone)
Adjusts a dateTime value to a specific time zone, or removes the time zone component from the dateTime value. For more information, see adjust-dateTime-to-timezone.
adjust-time-to-timezone
fn:adjust-time-to-timezone(arg, timezone)
Adjusts a time value to a specific time zone, or removes the time zone component from the date value. For more information, see adjust-time-to-timezone.
current-date
fn:current-date()
Returns the current date. For more information, see current-date.
current-dateTime
fn:current-dateTime()
Returns the current dateTime with time zone. For more information, see current-dateTime.
current-time
fn:current-time()
Returns the current time. For more information, see current-time.
dateDiff
date:dateDiff(date, date, format)
Returns the length of time between two dates in the format specified. For more information, see dateDiff.
dateTime
fn:dateTime(arg1, arg2)
Constructs a dateTime from a date and time. For more information, see dateTime.
dateToMillis
date:dateToMillis($date)
Converts the time to milliseconds.
day-from-date
fn:day-from-date(arg)
Returns the day portion of a date. For more information, see day-from-date.
day-from-dateTime
fn:day-from-dateTime(arg)
Returns the day portion of a date/time. For more information, see day-from-dateTime.
days-from-duration
fn:days-from-duration(arg)
Returns the number of days in a duration. For more information, see days-from-duration.
getDatePart
date:getDatePart(date, format)
Returns the specified part of a date as an integer value. For more information, see getDatePart.
getLocale
date:getLocale()
Returns a string representing the current locale the process is running in. For more information, see getLocale.
getTimeZone
date:getTimeZone()
Returns a string that specifies the timezone ID where the process is running or where the user is running it. For more information, see getTimeZone.
hours-from-dateTime
fn:hours-from-dateTime(arg)
Returns the hour portion of a date/time. For more information, see hours-from-dateTime.
hours-from-duration
fn:hours-from-duration(arg)
Returns the hours in a duration. For more information, see hours-from-duration.
hours-from-time
fn:hours-from-time(arg)
Returns the hour portion of a time. For more information, see hours-from-time.
implicit-timezone
fn:implicit-timezone()
Returns the value of the implicit timezone property. For more information, see implicit-timezone.
lastDay
date:lastDay(date)
Passes the date for which you want to return the last day of the month. You can enter any valid expression that evaluates to a date. For more information, see lastDay.
toDate
date:toDate(date, format)
Converts a character string to a Date data type. You use the toDate format strings to specify the format of the source strings. For more information, see toDate.
millisToDate
date:millisToDate($millis)
Converts the current time from milliseconds. For more information, see millisToDate.
minutes-from-dateTime
fn:minutes-from-dateTime(arg)
Returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the localized value of $arg. For more information, see minutes-from-dateTime.
minutes-from-duration
fn:minutes-from-duration(arg)
Returns an xs:integer representing the minutes component in the value of $arg. For more information, see minutes-from-duration.
minutes-from-time
fn:minutes-from-time(arg)
Returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the localized value of $arg. For more information, see minutes-from-time.
month-from-date
fn:month-from-date(arg)
Returns an xs:integer between 1 and 12, both inclusive, representing the month component in the localized value of $arg. For more information, see month-from-date.
month-from-dateTime
fn:month-from-dateTime(arg)
Returns an xs:integer between 1 and 12, both inclusive, representing the month component in the localized value of $arg. For more information, see month-from-dateTime.
months-from-duration
fn:months-from-duration(arg)
Returns an xs:integer representing the minutes component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration. For more information, see months-from-duration.
now
date:now()
Returns the current time in milliseconds.
seconds-from-duration
fn:seconds-from-duration(arg)
Returns an xs:decimal representing the seconds component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration. For more information, see seconds-from-duration.
seconds-from-dateTime
fn:seconds-from-dateTime(arg)
Returns an xs:decimal value greater than or equal to 0 and less than 60, representing the seconds and fractional seconds in the localized value of $arg. For more information, see seconds-from-dateTime.
seconds-from-time
fn:seconds-from-time(arg)
Returns an xs:decimal value greater than or equal to 0 and less than 60, representing the seconds and fractional seconds in the localized value of $arg. For more information, see seconds-from-time.
timezone-from-date
fn:timezone-from-date(arg)
Returns the timezone component of $arg, if any. For more information, see timezone-from-date .
timezone-from-dateTime
fn:timezone-from-dateTime(arg)
Returns the timezone component of an xs:dateTime. For more information, see timezone-from-dateTime.
timezone-from-time
fn:timezone-from-time(arg)
Returns the timezone component of an xs:time. For more information, see timezone-from-time.
toChar
date:toChar(date, format)
Converts the date passed to a string based on the specified format string. For more information, see toChar.
trunc
date:trunc(xs:dateTime('date'), 'format')
Truncates dates to a specific year, month, day, hour, minute, second, or millisecond. For more information, see trunc (Dates).
year-from-date
fn:year-from-date(arg)
Returns an xs:integer representing the year in the localized value of $arg. The value might be negative. For more information, see year-from-date.
year-from-dateTime
fn:year-from-dateTime(arg)
Returns an xs:integer representing the year component in the localized value of $arg. For more information see year-from-dateTime.
years-from-duration
fn:years-from-duration(arg)
Returns an xs:integer representing the years component in the value of $arg. The result is obtained by casting $arg to an xs:yearMonthDuration. For more information, see years-from-duration.
Digital Signatures
The functions described in the following sections are available for use in digital signatures.
HMAC Functions
The following functions enable you to generate a digital signature by calculating a keyed-hash message authentication code (HMAC):
Function
Syntax
Description
hmacSignature
dsig:hmacSignature($data as xs:string, $key as xs:string, $algorithm as xs:string, $encoding as xs:string, $keyCharset as xs:string?) as xs:string
Generates an HMAC signature using the specified algorithm such as HMACSHA256 or HMACSHA512 and the optional encoding where $encoding is one of the following values:
- Base64 (default)
- Base64Url
- Hex
- Hex64
You can use the optional keyCharset parameter to specify the character set of the secret key that you pass as an argument in the function. The keyCharset is set to UTF-8 by default.
hmacSHA1signature
dsig:hmacSHA1signature($data as xs:string, $key as xs:string, $encoding as xs:string, $keyCharset as xs:string?) as xs:string
Calculates an HMAC using the SHA1 algorithm and the optional encoding where$encoding is one of the following values:
- Base64 (default)
- Base64Url
- Hex
- Hex64
$data consist of four parts, including a JSON string in base64 encoding.
To ensure that you get hex binary and not base64 when you use the hash:hash function on the payload, use the following expression:
let $md5hex := hash:hash($jsonPayload,"MD5") return xs:base64Binary(xs:hexBinary($md5hex))
You can use the optional keyCharset parameter to specify the character set of the secret key that you pass as an argument in the function. The keyCharset is set to UTF-8 by default.
hmacSHA256signature
dsig:hmacSHA256signature($data as xs:string, $key as xs:string, $encoding as xs:string, $keyCharset as xs:string?) as xs:string
Calculates an HMAC using the SHA256 algorithm and the optional encoding where $encoding is one of the following values:
- Base64 (default)
- Base64Url
- Hex
- Hex64
You can use the optional keyCharset parameter to specify the character set of the secret key that you pass as an argument in the function. The keyCharset is set to UTF-8 by default.
hmacSHA512signature
dsig:hmacSHA512signature($data as xs:string, $key as xs:string, $encoding as xs:string, $keyCharset as xs:string?) as xs:string
Generates an HMAC SHA512 signature using the optional encoding where $encoding is one of the following values:
- Base64 (default)
- Base64Url
- Hex
- Hex64
You can use the optional keyCharset parameter to specify the character set of the secret key that you pass as an argument in the function. The keyCharset is set to UTF-8 by default.
hmacSHA256signatureForList
dsig:hmacSHA256signatureForList($data as xs:string, @delimiter as xs:string, $key as xs:string, $encoding as xs:string, $keyCharset as xs:string?) as xs:string
Generates an HMAC SHA512 signature using the optional encoding where $encoding is one of the following values:
The following functions enable you to generate digital signatures based on private keys:
Function
Syntax
Description
signWithKeyFile
dsig:signWithKeyFile($messageToSign as xs:string, $pathToKey as xs:string, $encryptionAlgorithm as xs:string, $digestAlgorithm as xs:string, $encoding as xs:string) as xs:string
Generates a signature using an asymmetric algorithm and a private key, specified in a PKCS8 file.
Arguments:
- $digestAlgorithm: SHA1 or SHA256
- $encryptionAlgorithm: RSA (common) or DSA (if using SHA1 for $digestAlgorithm).
- $pathToKey: The PKCS8 certificate as a Base64-encoded string (-----BEGIN PRIVATE KEY----- ..... n-----END PRIVATE KEY-----\n) or a binary private key file.
- $encoding(optional), which may be:
- Base64 (default)
- Hex64
- Base64Url
signWithKeyString
dsig:signWithKeyString($messageToSign as xs:string, $key as xs:string, $encryptionAlgorithm as xs:string, $digestAlgorithm as xs:string, $encoding as xs:string) as xs:string
Generates a signature using an asymmetric algorithm and a private key, specified in a PKCS8 certificate encoded string.
Arguments:
- $digestAlgorithm: SHA1 or SHA256
- $encryptionAlgorithm: RSA (common) or ECDSA.
- $key: The PKCS8 certificate as a Base64-encoded string (-----BEGIN PRIVATE KEY----- ..... n-----END PRIVATE KEY-----\n) or a binary private key.
- $encoding(optional), which can be one of the following values:
- Base64 (default)
- Hex64
- Base64Url
Note: When you use Base64Url encoding to sign any data, you receive extra periods at the end. You must replace the period (.) with an empty string (“) using the replace function:
fn:replace(input, pattern, replacement, flags)
signWithCertificate
dsig:signWithCertificate($messageToSign as xs:string, $pathToCertificate as xs:string, $keyRecoveryPassword as xs:string, $encryptionAlgorithm as xs:string, $digestAlgorithm as xs:string, $encoding as xs:string $keyStorePassword as xs:string, $aliasName as xs:string, $keyStoreType as xs:string) as xs:string
Generates a signature using a PKCS12 certificate.
Arguments:
- $pathToCertificate: File location on the agent that contains either a PKCS12 or JKS (Java keystore) certificate.
- $keyRecoveryPassword: Password to access the key in the certificate.
- $keyStorePassword: Password to open the key store. If empty, assumes the keystore is not password-protected.
- $aliasName: Optional. Alias of entry in the keystore on the Secure Agent which contains the key. If the alias is not supplied (or empty), the first entry is used.
- $keyStoreType: Type of keystore, which may be:
- PKCS12 (default)
- JKS (Java keystore)
Hashing Functions
The following functions enable you to generate a message hash string:
Function
Syntax
Description
hash
hash:hash($string, $alg)
Generates a hash string for a message using the specified algorithm (optional), where $alg is one of the following:
- MD5 (default)
- SHA1
- SHA256
List Functions
The list functions support only the native Saxon functions. The following functions allow you to work with lists:
Function
Syntax
Description
append
list:append($objectlist, $newItem)
Appends a new item to a list.
count
list:count($objectlist)
Counts the items in a list.
head
list:head($objectlist)
Returns the first item in a list.
list
list:list($sequence)
Converts a sequence of IDs into a semicolon-separated list of IDs for an object list.
remove
list:remove($objectlist, $position)
Removes the item at the specified position from the list.
replace
list:replace($objectlist, $position, $newItem)
Replaces an existing item in a list with a new value.
sequence
list:sequence($objectlistFieldName)
Converts a semicolon-separated list to a sequence.
When an object list field is inserted into formula and content, the field is wrapped in the list:sequence(object_field_name) XQuery function. For object lists in hosted objects, this converts the semicolon-separated list of IDs in the object list into a sequence. For object lists for process objects, the value is already a sequence and the function returns the list unchanged.
tail
list:tail($objectlist)
Return all items from the list with the exception of the first item.
List Function Examples
Perhaps the most common example of using the list functions is to get an object from a list each time a step is invoked, possibly from within a repeated Process or Service step. For example:
let mylist.Current:=list:head(mylist.List) let mylist.List:=list:tail(mylist.List)
The following example converts an object list in a semicolon-separated list, then iterates over each item:
for $objectid in list:sequence($objectlist) ...
The following example converts a sequence of IDs into a semicolon-separated list of IDs for an object list for hosted objects. For an object list for process objects, it returns a sequence of values:
let $mergedObjectLists := ( as:sequence($objectlist1), as:sequence($objectlist2) ) return list:list($mergedObjectLists)
The following miscellaneous functions are available:
Function
Syntax
Description
aesEncryption
util:aesEncryption(key, dataToEncrypt)
Encrypts the specified data with the provided key using the Advanced Encryption Standard (AES) algorithm. For more information about the function, see aesEncryption.
aesDecryption
util:aesDecryption(key, dataToDecrypt)
Decrypts the specified data with the provided key using the Advanced Encryption Standard (AES) algorithm. You must use the same key that you had used for encrypting the data in the aesEncryption function. For more information about the function, see aesDecryption.
base64Decode
util:base64Decode(data, charSet)
Returns the base64-decoded version of the input string provided based on the character set specified in the charSet argument. This function is typically used for attachments.
Application Integration supports the character sets that Azul JDK supports for encoding. For example, US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, and UTF-16.
Default for the charSet argument is UTF-8.
base64Encode
util:base64Encode(data, charSet)
Returns the base64-encoded version of the input string provided based on the character set specified in the charSet argument.
Application Integration supports the character sets that Azul JDK supports for encoding. For example, US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, and UTF-16.
Default for the charSet argument is UTF-8.
base64EncodeURL
util:base64EncodeUrl(str, charSet)
Returns a base64-encoded version of the string provided, safe to use in a URL.
Any "+" and "/" characters are replaced with "-" and "_". Any "=" characters are removed.
Searches a field for the specified value. For more information, see decode.
error
fn:error(error, description, error-object)
Raises a custom error.
escapeJsonString
util:escapeJsonString(str)
Escapes special characters in the provided string to make it valid for usage in JSON. See JSON standard for details. For more information about the function, see escape-Json-String .
exactly-one
fn:exactly-one(arg)
Returns a sequence if it contains exactly one item, otherwise returns errors.
- timezoneId: Optional. The time zone ID. If you do not use a stored value (typically returned by a call to date:getTimeZone()), you can omit this argument as Process Designer will call date:getTimeZone().
- locale: Optional. The locale. If you do not use a stored value (typically returned by a call to date:getLocale()), you can omit this argument as Process Designer will call date:getLocale().
If you use a locale argument but do not use a timezoneId argument, you must add the comma that would follow timezoneId. For example:
util:format("789","##00.00","",date:getLocale())
If the pattern argument contains a date, use lowercase letters to denote the year format yyyy. For example, use util:format("2024-12-29T06:16:02.536Z", "yyyy-MM-dd HH:mm:ss"). If you use uppercase letters, you might receive an incorrect year or errors might occur.
generate-random-string
util:generate-random-string(length as xs:integer)
Generates a random string of the specified length.
generateUUID
util:generateUUID()
Generates a universally unique identifier.
getAssetLocation
util:getAssetLocation()
Returns the location where the process or the guide that uses the function is stored. For more information, see getAssetLocation.
getAssetName
util:getAssetName()
Returns the name of the process or the guide that uses the function. For more information, see getAssetName.
getCatalogResource
util:getCatalogResource()
Returns the resource based on a catalog location URL within the organization. Takes any catalog resource in the Informatica Cloud organization as its parameter and returns an element node.
To display the element data, add a wrapper function. For example:
Returns the start time of the running instance of the specified process or guide. For more information, see getInstanceStartTime.
getOrganizationId
util:getOrganizationId()
Returns a string that is the organization Id of the context of the currently executing process. For more information, see getOrganizationId.
getOrganizationName
util:getOrganizationName()
Returns the organization name in the context of the executing process, guide, service connector, or data access service connector. For more information, see getOrganizationName.
getProcessId
util:getProcessId()
Returns the process Id of the currently executing or completed process.
getUserName
util:getUserName()
Returns a string that is the login name or ID of the authenticated User running the process .
getUserSystem
util:getUserSystem()
Returns a string that is the name of the system that authenticated the user running the process.
iif
util:iif(condition, val1, val2)
Returns val1 if the condition is true. Else, returns val2. For more information, see iif.
in
util:in(valueToSearch, values, caseFlag)
Matches input data with a list of values. By default, the match is case sensitive. For more information, see in.
isNull
util:isNull(value)
Checks whether the input passed is empty. For more information, see isNull.
one-or-more
fn:one-or-more
Returns a sequence if it contains one or more items, otherwise returns errors.
parseJSON
util:parseJSON(jsonStr)
Parses the provided JSON string and converts it to XML elements.
parseXML
util:parseXML(xmlStr)
Parses the provided XML string and converts it to an XML element.
random
util:random()
Returns a random number from 0 to 1.
resolveURN
util:resolveURN()
Retrieves the URN mapping for an organization.
safeNumber
util:safeNumber()
Holds a number value safely so it cannot be changed.
toDecimal
util:toDecimal(value, scale)
Converts a string or numeric value to a decimal value. For more information, see toDecimal.
toInteger
util:toInteger(value, flag)
Converts a string or numeric value to a decimal value. For more information, see toInteger.
setProcessTitle
ipd:setProcessTitle()
Sets the title of the process.
Note: Use this function only in Informatica Process Designer.
simplifyXml
util:simplifyXml(undefined)
Utility function that is used to remove all namespaces and convert attributes into child elements. For more information, see simplifyXml.
toJSON
util:toJSON(elements)
Converts the provided list of XML elements to a JSON string.
toXML
util:toXML(element)
Converts the provided XML element to an XML string.
trace
util:trunc(arg, precision)
Provides an execution trace to be used in debugging queries. For more information, see trace.
trunc
util:trunc(arg, precision)
Truncates numbers to a specific digit based on the number of decimal places specified by the precision. For more information, see trunc (Numbers).
zero-or-one
fn:zero-or-one(arg)
Returns a sequence if it contains zero or one items, otherwise returns an error.
Numbers
The following number functions are available in the Expression Editor:
•abs
•avg
•ceiling
•floor
•max
•min
•round
•round-half-to-even
•sum
Sequences
The following sequences functions are available in the Expression Editor:
•count
•distinct-values
•index-of
•insert-before
•last
•position
•remove
•reverse
•subsequence
•unordered
String
The following string functions are available in the Expression Editor:
•codepoint-equal
•codepoints-to-string
•compare
•concat
•contains
•default-collation
•ends-with
•lang
•lower-case
•matches
•normalize-space
•normalize-unicode
•replace
•starts-with
•string-join
•string-to-codepoints
•substring
•substring-after
•substring-before
•tokenize
•translate
•upper-case
XML
You can add common XML functions as you build expressions. From the Expression Editor, a list of common XML functions displays in these categories:
•XML Documents, URIs, and IDs (processes only)
•XML Namespaces and Names
•XML Nodes
The following XML Nodes functions are available in the Expression Editor:
Function
Syntax
Description
data
fn:data(arg)
Returns the atomic value of a node.
The function takes a sequence of items and returns a sequence of atomic values. For more information, see data.
deep-equal
fn:deep-equal(parameter1, parameter2, collation)
Assesses whether two nodes have the same content and attributes. For more information, see deep-equal.
root
fn:root(arg)
Returns the root of the tree that contains the argument. For more information, see root.
Atomic Values of All Types functions
The following functions are available in the Atomic Values of All Types section of the Expression Editor:
boolean
The boolean function in XQuery is used to convert its argument to a boolean value according to specific rules.
Syntax
fn:boolean(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The sequence to be converted into a boolean. It can be an atomic value, a sequence of nodes, or an empty sequence. It can contain zero or more items.
Return Value
•If the sequence is empty, the result is false.
•If the sequence contains a single boolean value, that value is returned.
•If the sequence contains a single numeric value, false is returned for 0 or NaN, and true for any other numeric value.
•If the sequence contains a single string, false is returned for an empty string, and true for any other string.
•For nodes, the existence of nodes in a sequence determines the truth value: true for a non-empty sequence, and false for an empty one.
•If the sequence contains more than one item and none of these conditions apply, an error occurs.
Examples
The following table lists some sample values and return values:
Input
Return Value
fn:boolean( () )
false
fn:boolean('')
false
fn:boolean(0)
false
fn:boolean('0')
true
fn:boolean('false')
true
fn:boolean(("Hello"))
true
fn:boolean(xs:float('NaN'))
false
fn:boolean($ordDoc/order[1])
true
fn:boolean($ordDoc/noSuchChild)
false
fn:boolean(<a>false</a>)
true
empty
The empty function in XQuery is used to determine whether a sequence is empty. It is useful in various conditional checks and scenarios where determining the presence of data is necessary.
Syntax
fn:empty(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
This is the sequence that you want to test for emptiness. It can contain zero or more items.
Return Value
If the value of $arg is the empty sequence, the function returns true. Otherwise, the function returns false .
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:empty( ('a', 'b', 'c') )
false
fn:empty( () )
true
fn:empty(0)
false
fn:empty((1, 2, 3))
false
fn:empty(("apple", "orange"))
false
exists
The exists function in XQuery is used to determine whether a sequence contains one or more items.
Syntax
fn:exists(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The sequence to check for existence. It can be a node, an atomic value, or a sequence of items. It can contain zero or more items.
Return Value
If the value of $arg is not the empty sequence, the function returns true. Otherwise, the function returns false .
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:exists( ('a', 'b', 'c') )
true
fn:exists( '' )
true
fn:exists( () )
false
fn:exists( false() )
true
fn:exists( (1, 2, 3) )
true
false
The false function in XQuery is a function that always returns the boolean value false. It's part of the XQuery standard functions for working with boolean values.
Syntax
fn:false()
The false function does not take any parameters.
Return Value
Returns the xs:boolean value false . Equivalent to xs:boolean("0") .
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:false()
false()
fn:not(fn:false())
true
nilled
The nilled function in XQuery is used to check whether a given node is nilled. A nilled element is where the xsi:nil attribute is set to true in an XML document that supports XML Schema.
Syntax
fn:nilled(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The node to be checked for the nilled status. This can be an element node or none.
Return Value
•Returns an xs:boolean indicating whether the argument node is nilled.
•Returns true if the node is an element and is nilled, that is, xsi:nil="true".
•Returns false if the node is an element but not nilled.
•Returns None if $arg is not an element node or if it is empty.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:nilled(())
None
let $textNode := text{"example"} return fn:nilled($textNode)
None
not
The not function accepts a sequence of items, from which it calculates the effective boolean value of the sequence as a whole before negating it.
Syntax
fn:not(arg)
The following table describes the argument for this command:
Argument
Required/ Optional
Description
arg
Required
The boolean expression you want to negate. This can be a boolean value or None.
Return Value
The $arg is first reduced to an effective boolean value by applying the fn:boolean() function. Returns true if the effective boolean value is false or None, and false if the effective boolean value is true.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:not(true())
false
fn:not(false())
true
fn:not(())
true
fn:not('')
true
fn:not(0)
true
fn:not(<e>false</e>)
false
number
The number function constructs an xs:double value either from a node that contains a number, or from an atomic value. This function is useful for telling the processor to treat a node or value as a number, irrespective of its declared type, if any.
Syntax
fn:number(arg)
The following table describes the argument for this command:
Argument
Required/ Optional
Description
arg
Required
The atomic value you want to convert to a number. This can be a string representing a number, a numeric type, or None.
Return Value
Returns the value indicated by $arg or, if $arg is not specified, the context item after atomization, converted to an xs:double.
The difference between using the fn:number function and the xs:double constructor is that the fn:number function returns the value NaN in the case that the argument cannot be cast to a numeric value, whereas the xs:double constructor will raise an error.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:number('29.99')
29.99
fn:number('ABC')
NaN
fn:number(42)
42.0
fn:number( () )
NaN
fn:number(true())
1
string
The string function in XQuery is used to convert an argument to its string representation. It is commonly used to ensure that a given value is treated as a string.
Syntax
fn:string(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The item you want to convert to a string. This can be any atomic type, node, or sequence. The sequences with more than one item will return an error.
Return Value
Returns the value of $arg represented as a xs:string. If no argument is supplied, the context item ( . ) is used as the default argument. The behavior of the function if the argument is omitted exactly the same as if the context item had been passed as the argument.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:string(123)
"123"
fn:string("Hello, World!")
"Hello, World!"
fn:string(true())
"true"
true
The true function in XQuery is a simple function that returns the boolean value true.
Syntax
fn:true()
The true function does not take any parameters.
Return Value
Returns the xs:boolean value true. Equivalent to xs:boolean("1") .
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:true()
true
fn:not(fn:true())
false
Date and time functions
The following date functions are available in the Dates and Times section of the Expression Editor:
addToDate
Adds a specified amount to one part of a datetime value, and returns a date in the same format as the date you pass to the function. The addToDate function accepts positive and negative integer values. Use addToDate to change the following parts of a date:
•Year. Enter a positive or negative integer in the amount argument. Use any of the year format strings: Y, YY, YYY, or YYYY. The following expression adds 10 years to all dates in the SHIP_DATE column:
•Month. Enter a positive or negative integer in the amount argument. Use any of the month format strings: MM, MON, MONTH. The following expression subtracts 10 months from each date in the SHIP_DATE column:
•Day. Enter a positive or negative integer in the amount argument. Use any of the day format strings: D, DD, DDD, DY, and DAY. The following expression adds 10 days to each date in the SHIP_DATE column:
•Hour. Enter a positive or negative integer in the amount argument. Use any of the hour format strings: HH, HH12, HH24. The following expression adds 14 hours to each date in the SHIP_DATE column:
•Minute. Enter a positive or negative integer in the amount argument. Use the MI format string to set the minute. The following expression adds 25 minutes to each date in the SHIP_DATE column:
•Seconds. Enter a positive or negative integer in the amount argument. Use the SS format string to set the second. The following expression adds 59 seconds to each date in the SHIP_DATE column:
•Milliseconds. Enter a positive or negative integer in the amount argument. Use the MS format string to set the milliseconds. The following expression adds 125 milliseconds to each date in the SHIP_DATE column:
•Microseconds. Enter a positive or negative integer in the amount argument. Use the US format string to set the microseconds. The following expression adds 2,000 microseconds to each date in the SHIP_DATE column:
Note: You must manually add the xs:dateTime phrase and enclose the date values within single quotation marks.
The following table describes the arguments:
Argument
Required/ Optional
Description
date
Required
Date/Time data type. Passes the values that you want to change.
You can enter any valid transformation expression.
format
Required
A format string that specifies the portion of the date value that you want to change. Enclose the format string within single quotation marks, for example, 'mm'. The format string is not case sensitive.
amount
Required
An integer value that specifies the amount of years, months, days, hours, and so on by which you want to change the date value. You can enter any valid transformation expression that evaluates to an integer.
Return Value
Date in the same format as the date you pass to this function.
NULL if a null value is passed as an argument to the function.
Examples
The following expressions all add one month to each date in the DATE_SHIPPED column. If you pass a value that creates a day that does not exist in a particular month, addToDate returns the last day of the month. For example, if you add one month to Jan 31 1998, addToDate returns Feb 28 1998.
Also, addToDate recognizes leap years and adds one month to Jan 29 2000:
The following table shows some sample values and return values:
DATE_SHIPPED
RETURN VALUE
Jan 1 1997 12:00:30AM
Dec 31 1996 9:00:30AM
Jan 31 1997 6:24:45PM
Jan 31 1997 3:24:45AM
Oct 9 1997 2:30:12PM
Oct 8 1997 11:30:12PM
Mar 3 1996 5:12:20AM
Mar 2 1996 2:12:20PM
Mar 1 1996 5:32:12AM
Feb 29 1996 2:32:12PM (Leap Year)
NULL
NULL
adjust-date-to-timezone
Adjusts a date value to a specific time zone, or removes the time zone component from the date value.
Syntax
fn:adjust-date-to-timezone(arg, timezone)
The following table describes the arguments:
Argument
Required/
Optional
Description
arg
Required
The date value that is to be adjusted.
The date-value is of type xs:date or is an empty sequence.
timezone
Optional
A duration that represents the time zone to which date-value is to be adjusted.
Return Value
The fn:adjust-date-to-timezone function behaves differently depending on whether the $arg date value already has a time zone, and on the value of the time zone provided as given below:
•The $timezone argument is expressed as an xs:dayTimeDuration, for example -PT5H for US Eastern Standard Time.
•If $timezone is an empty sequence, returns an xs:date without a time zone. Otherwise, returns an xs:date with a time zone.
•If $arg already has a time zone, its value is adjusted to that time zone.
•To adjust the time zone, an xs:date is treated as an xs:dateTime with time 00:00:00 .
•If $arg does not already have a time zone, its date part stays the same, and the time is associated with the specified time zone.
•If $timezone is omitted from the function call, it is assumed to be the implicit time zone.
Examples
The following table contains examples and return values for the adjust-date-to-timezone function:
Adjusts a dateTime value to a specific time zone, or removes the time zone component from the dateTime value.
Syntax
fn:adjust-dateTime-to-timezone(arg, timezone)
The following table describes the arguments:
Argument
Required/
Optional
Description
arg
Required
The dateTime value that is to be adjusted.
The dateTime-value is of type xs:dateTime or is an empty sequence.
timezone
Optional
A duration that represents the time zone to which dateTime-value is to be adjusted.
Return Value
The fn:adjust-dateTime-to-timezone function behaves differently depending on whether the $arg date value already has a time zone, and on the value of the time zone provided as given below:
•The $timezone argument is expressed as an xs:dayTimeDuration, for example -PT5H for US Eastern Standard Time.
•If $timezone is an empty sequence, returns an xs:dateTime without a time zone. Otherwise, returns an xs:dateTime with a time zone.
•If $arg already has a time zone, its value is adjusted to that time zone.
•If $arg does not already have a time zone, its date part stays the same, and the time is associated with the specified time zone.
•If $timezone is omitted from the function call, it is assumed to be the implicit time zone.
Examples
The following table contains examples and return values for the adjust-date-to-timezone function:
Adjusts a time value to a specific time zone, or removes the time zone component from the date value.
Syntax
fn:adjust-time-to-timezone(arg, timezone)
The following table describes the arguments:
Argument
Required/
Optional
Description
arg
Required
The time value that is to be adjusted.
The time-value is of type xs:time or is an empty sequence.
timezone
Optional
A duration that represents the time zone to which time-value is to be adjusted.
Return Value
The fn:adjust-time-to-timezone function behaves differently depending on whether the $arg date value already has a time zone, and on the value of the time zone provided as given below:
•The $timezone argument is expressed as an xs:dayTimeDuration, for example -PT5H for US Eastern Standard Time.
•If $timezone is an empty sequence, returns an xs:time without a time zone. Otherwise, returns an xs:time with a time zone.
•If $arg already has a time zone, its value is adjusted to that time zone.
•If $arg does not already have a time zone, its date part stays the same, and the time is associated with the specified time zone.
•If $timezone is omitted from the function call, it is assumed to be the implicit time zone.
Examples
The following table contains examples and return values for the adjust-date-to-timezone function:
The fn:current-date function takes no parameters, and returns the current date with the time zone. The time zone is implementation-dependent.
Example
If this function was invoked on January 12, 2023, the returned value would be 2023-01-12Z.
current-dateTime
Returns the current dateTime with time zone.
Syntax
fn:current-dateTime()
Return Value
The fn:current-dateTime function takes no parameters, and returns the current date and time with the time zone. If the function is called multiple times within the same query, it returns the same value every time. The time zone is implementation-dependent.
Example
If this function was invoked on January 12, 2023 in time zone Z, the returned value would be 2023-01-12T11:25:30.125Z.
current-time
Returns the current time.
Syntax
fn:current-time()
Return Value
The fn:current-time function takes no parameters, and returns the current time with the time zone. If the function is called multiple times within the same query, it returns the same value every time. The time zone is implementation-dependent.
Example
The following expression will return 23:17:00.000-05:00 as the result:
fn:current-time()
dateDiff
Returns the length of time between two dates. You can specify the format as years, months, days, hours, minutes, seconds, milliseconds, or microseconds. The dateDiff function subtracts the second date from the first date and returns the difference.
The dateDiff function calculates the value based on the number of months instead of the number of days. It calculates the date differences for partial months with the days selected in each month. To calculate the date difference for the partial month, dateDiff adds the days used within the month. It then divides the value with the total number of days in the selected month.
The dateDiff function gives a different value for the same period in the leap year period and a non-leap year period. The difference occurs when February is part of the dateDiff function. The dateDiff function divides the days with 29 for February for a leap year and 28 if it is not a leap year.
For example, you want to calculate the number of months from September 13 to February 19. In a leap year period, dateDiff calculates the month of February as 19/29 months or 0.655 months. In a non-leap year period, dateDiff calculates the month of February as 19/28 months or 0.678 months. The dateDiff function similarly calculates the difference in the dates for the remaining months and the dateDiff function returns the total value for the specified period.
Note: Some databases might use a different algorithm to calculate the difference in dates.
Note: You must manually add the xs:dateTime phrase and enclose the date values within single quotation marks.
The following table describes the arguments:
Argument
Required/ Optional
Description
date
Required
Date/Time data type. Passes the values for the first date that you want to compare.
You can enter any valid transformation expression.
date
Required
Date/Time data type. Passes the values for the second date that you want to compare.
You can enter any valid transformation expression.
format
Required
Format string that specifies the date or time measurement. You can specify years, months, days, hours, minutes, seconds, milliseconds, or microseconds. You can specify only one part of the date, such as 'mm'. Enclose the format strings within single quotation marks. The format string is not case sensitive. For example, the format string 'mm' is the same as 'MM', 'Mm', or 'mM'.
Return Value
Double value. If the first date is later than the second date, the return value is a positive number. If the first date is earlier than the second date, the return value is a negative number.
0 if the dates are the same.
NULL if one (or both) of the date values is NULL.
Examples
The following expressions return the number of hours between the DATE_PROMISED and DATE_SHIPPED columns:
The following table lists some sample values and return values:
DATE_PROMISED
DATE_SHIPPED
LEAP YEAR VALUE (in Months)
NON-LEAP YEAR VALUE (in Months)
Sept 13
Feb 19
-5.237931034
-5.260714286
NULL
Feb 19
NULL
N/A
Sept 13
NULL
NULL
N/A
dateTime
Constructs a dateTime value from a date value and a time value.
Syntax
fn:dateTime(arg1, arg2)
The fn:dateTimeAdd (arg1 as xs:date?, arg2 as xs:time?) is different from the xs:dateTime constructor, which accepts a single argument that includes the date and time. Time zone is taken into account when constructing the date/time.
Return Value
•If only one of the arguments has a time zone, or if both arguments have the same time zone, the result has this time zone.
•If neither the date nor the date argument has a time zone, the result has no time zone.
•If the two arguments have different time zones, an error is returned.
•If the combination does not result in a valid time, for example, the day is 32 or the minute is 61, an error is returned.
Example
The following expression returns 2023-06-12T11:35:29 as the result:
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The duration value from which the days component is to be extracted.
The duration-value is an empty sequence, or is a value that has one of the following types:
- xs:dayTimeDuration
- xs:duration
- xs:yearMonthDuration
Return Value
•If duration-value is of type xs:dayTimeDuration or is of type xs:duration, the returned value is of type xs:integer, and is the days component of duration-value cast as xs:dayTimeDuration.
•If duration-value is of type xs:yearMonthDuration, the returned value is 0.
•If duration-value is an empty sequence, the returned value is an empty sequence.
•If duration-value is negative, the returned value is negative.
Example
The following expression returns the days from the duration:
The following table lists some sample values and return values:
DURATION
RETURN VALUE
P5D
5
-PT24H
-1
PT23H
0
P1DT36H
2
PT1440M
1
getDatePart
Returns the specified part of a date as an integer value. Therefore, if you create an expression that returns the month portion of the date, and pass a date such as 1997-04-01T00:00:00, getDatePart returns 4.
Syntax
date:getDatePart(xs:dateTime('date'), 'format')
Note: You must manually add the xs:dateTime phrase and enclose the date values within single quotation marks.
The following table describes the arguments:
Argument
Required/ Optional
Description
date
Required
Date/Time data type.
You can enter any valid transformation expression.
format
Required
A format string that specifies the portion of the date value that you want to return. Enclose format strings within single quotation marks, for example, 'mm'. The format string is not case sensitive.
For example, if you pass the date 1997-04-01 to getDatePart, the format strings 'YYYY' returns 1997.
Return Value
Integer representing the specified part of the date.
NULL if a value passed to the function is NULL.
Examples
The following expressions return the hour for each date in the DATE_SHIPPED column. 12:00:00AM returns 0 because the default date format is based on the 24 hour interval:
The following table lists some sample values and return values:
DATE_SHIPPED
RETURN VALUE
1997-03-13T12:00:00AM
1997
1997-06-3T11:30:44PM
1997
NULL
NULL
getLocale
Returns a string representing the current locale where the process is running.
Syntax
date:getLocale()
Use the getLocale function to retrieve the current locale setting active within the system. It identifies regional or language specific settings that are used to generate certain values such as language code and a country/region code.
Return Value
Returns the locale value as a text string.
Example
If the process is being executed in the IST time zone, the following expression returns the locale information:
date:getLocale()
The following table lists some sample properties and values:
PROPERTY
VALUE
Base locale ID
en_IN
Language
en
Country
IN
Display name
English (India)
getTimeZone
Returns a string that specifies the timezone ID of the Secure Agent machine that runs the process.
For processes and taskflows that run on cloud server, the system always sets the timezone to GMT.
Syntax
date:getTimeZone()
Return Value
Returns the timezone ID as a string value.
Example
If you run the process on a Secure Agent configured with the system time zone set to IST, the function date:getTimeZone() returns IST.
If you run the process or taskflows on the Cloud Server, the function date:getTimeZone() returns GMT.
hours-from-dateTime
Returns the hour portion of a date/time.
Syntax
fn:hours-from-dateTime(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The dateTime value from which the hours component is to be extracted.
The dateTime-value is of type xs:dateTime or is an empty sequence.
Return Value
Returns the hour portion of an xs:dateTime value in its localized form, as an integer between 0 and 23 inclusive.
If dateTime-value is an empty sequence, the returned value is an empty sequence.
Example
The following expression returns the hour from the date/time:
fn:hours-from-dateTime(xs:dateTime('TIME'))
The following table lists some sample values and return values:
TIME
RETURN VALUE
2023-08-15T10:30:23
10
2023-08-15T10:30:23-05:00
10
hours-from-duration
Returns the hours in a duration.
Syntax
fn:hours-from-duration(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The duration value from which the hours component is to be extracted.
The duration-value is an empty sequence or is a value that has one of the following types:
- xs:dayTimeDuration
- xs:duration
- xs:yearMonthDuration
Return Value
•If duration-value is of type xs:dayTimeDuration or is of type xs:duration, the returned value is of type xs:integer, and is a value between -23 and 23, inclusive. The value is the hours component of duration-value cast as xs:dayTimeDuration.
•If duration-value is of type xs:yearMonthDuration, the returned value is of type xs:integer and is 0.
•If duration-value is an empty sequence, the returned value is an empty sequence.
•If duration-value is negative, the returned value is negative.
Example
The following expression returns the hours from the duration:
The following table lists some sample values and return values:
DURATION
RETURN VALUE
P1DT5H
5
-PT36H
-12
PT23H
23
PT1H90M
2
PT2H59M
2
PT3600S
1
hours-from-time
Returns the hour portion of a time.
Syntax
fn:hours-from-time(arg)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
arg
Required
The time value from which the hours component is to be extracted.
The time-value is of type xs:time or is an empty sequence.
Return Value
Returns the hour portion of an xs:time value in its localized form, as an integer between 0 and 23 inclusive.
If time-value is an empty sequence, the returned value is an empty sequence.
Example
The following expression returns the hour from the time:
fn:hours-from-time(xs:time('TIME'))
The following table lists some sample values and return values:
TIME
RETURN VALUE
10:30:23
10
10:30:23-05:00
10
09:30:00-08:00
9
implicit-timezone
Returns the value of the implicit timezone property.
Syntax
fn:implicit-timezone()
The implicit time zone is used in comparisons and calculations involving date and time values that do not have explicitly defined time zones. The implicit time zone is defined by the implementation.
Return Value
Returns the implicit time zone as an xs:dayTimeDuration value.
Example
If the implicit time zone is UTC minus 5 hours, the following expression returns -PT5H as the result:
fn:implicit-timezone()
lastDay
Returns the date of the last day of the month for each date in a column.
Syntax
date:lastDay(date)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
date
Required
Date/Time data type. Passes the date for which you want to return the last day of the month.
You can enter any valid transformation expression that evaluates to a date.
Return Value
Date. The last day of the month for the date value that you pass to this function.
NULL if a value in the selected column is NULL.
Example
The following expression returns the current date as the last day:
date:lastDay(fn:current-dateTime('DATE'))
The following table lists some sample values and return values:
DATE
RETURN VALUE
18-04-98 01:00
Apr 18 1998 01:00:00 AM
20-08-99 05:00
Aug 20 1999 05:00:00 AM
The following expression returns the last day of the previous month for each date in the DATE column:
The following table lists some sample values and return values:
DATE
RETURN VALUE
Apr 1 1998 12:00:00AM
Mar 31 1998 12:00:00AM
Jan 6 1998 12:00:00AM
Dec 31 1997 12:00:00AM
Feb 2 1996 12:00:00AM
Jan 31 1996 12:00:00AM
NULL
NULL
You can nest toDate to convert string values to a date. toDate function always includes time information. If you pass a string that does not have a time value, the date returned will include the time 00:00:00.
The following example returns the last day of the month for each date in the same format as the string:
date:lastDay(toDate('DATE', 'MON-DD-YYYY'))
The following table lists some sample values and return values:
DATE
RETURN VALUE
'18-NOV-98'
Nov-30-1998 00:00:00
'28-APR-98'
Apr-30-1998 00:00:00
NULL
NULL
'18-FEB-96'
Feb-29-1996 00:00:00(Leap year)
date:lastDay(date:toDate("DATE", "YYYY-MM-DD"))
The following table lists some sample values and return values:
DATE
RETURN VALUE
'18-NOV-98'
1998-Nov-30 00:00:00
'28-APR-98'
1998-Apr-30 00:00:00
NULL
NULL
'18-FEB-96'
1996-Feb-29 00:00:00(Leap year)
millisToDate
Converts the current time from milliseconds.
Syntax
date:millisToDate(millis)
Argument
Required/
Optional
Description
millis
Required
Numeric data type. Passes the values in milliseconds.
Return Value
The function returns a date that is the number of milliseconds passed since January 1, 1970, 00:00:00 UTC.
Examples
The function returns the corresponding date values for the value mentioned in the MILLISECONDS column:
MILLISECONDS
RETURN VALUE
1000
1970-01-01T00:00:01Z
1900800000
1970-01-23T00:00:00Z
minutes-from-dateTime
Returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the localized value of $arg.
Syntax
fn:minutes-from-dateTime(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as datetime that you want to convert to minutes.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the MILLISECONDS column:
MILLISECONDS
RETURN VALUE
1999-05-31T13:40:00-05:00
40
1999-05-31T13:30:00+05:30
30
minutes-from-duration
The function returns an xs:integer representing the minutes component in the value of $arg.
Syntax
fn:minutes-from-duration(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a duration that must be converted to minutes.
Return Value
The function returns an xs:integer representing the minutes component in the value of $arg. The result is obtained by casting $arg to an xs:dayTimeDuration.
Examples
The function returns the corresponding date values for the value mentioned in the DURATION column:
DURATION
RETURN VALUE
P3DT12H32M12S
32
-P5DT12H30M
-30
minutes-from-time
Returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the localized value of $arg.
Syntax
fn:minutes-from-time(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a time that must be converted to minutes.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the TIME column:
TIME
RETURN VALUE
11:23:00
23
13:00:00Z
0
month-from-date
Returns an xs:integer between 1 and 12, both inclusive, representing the month component in the localized value of $arg.
Syntax
fn:month-from-date(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a date that must be converted to months.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer value between 1 and 12, both inclusive, representing the month component in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the DATE column:
DATE
RETURN VALUE
1991-05-31-05:00
05
2000-01-01+05:00
01
month-from-dateTime
Returns an xs:integer between 1 and 12, both inclusive, representing the month component in the localized value of $arg.
Syntax
fn:month-from-dateTime(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a datetime that must be converted to months.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer value between 1 and 12, both inclusive, representing the month component in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the DATETIME column:
DATETIME
RETURN VALUE
1995-05-31T13:20:00-05:00
05
1996-12-31T19:20:00-05:00
12
months-from-duration
Returns an xs:integer representing the minutes component in the value of $arg . The result is obtained by casting $arg to an xs:dayTimeDuration.
Syntax
fn:months-from-duration(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a duration that must be converted to months.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer value between 1 and 12, both inclusive, representing the month component in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the DURATION column:
DURATION
RETURN VALUE
1991-05-31-05:00
05
2000-01-01+05:00
01
seconds-from-dateTime
Returns an xs:decimal value greater than or equal to 0 and less than 60, representing the seconds and fractional seconds in the localized value of $arg.
Syntax
fn:seconds-from-dateTime(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a datetime that must be converted to seconds.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:decimal value greater than or equal to 0 and less than 60, representing the seconds and fractional seconds in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the DATETIME column:
DATETIME
RETURN VALUE
2006-08-15T10:30:14.5
14.5
2001-05-31T13:20:40
40
seconds-from-duration
Returns an xs:decimal representing the seconds component in the value of $arg . The result is obtained by casting $arg to an xs:dayTimeDuration.
Syntax
fn:seconds-from-duration(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a duration that must be converted to seconds.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:decimal value greater than or equal to 0 and less than 60, representing the seconds and fractional seconds in the local value of $arg.
Examples
The function returns the corresponding date values for the value mentioned in the DURATION column :
DURATION
RETURN VALUE
PT30.8S
30.8
seconds-from-time
Returns an xs:decimal value greater than or equal to zero and less than 60, representing the seconds and fractional seconds in the localized value of $arg.
Syntax
fn:seconds-from-time(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a time that must be converted to seconds.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:decimal value greater than or equal to 0 and less than 60, representing the seconds and fractional seconds in the localized value of $arg.
Examples
The function returns the corresponding date values for the value mentioned as arg in the TIME column :
TIME
RETURN VALUE
13:20:11.5
11.5
timezone-from-date
Returns the timezone component of $arg, if any.
Syntax
fn:timezone-from-date(arg)
Return Value
If $arg has a timezone component, the result is an xs:dayTimeDuration that indicates deviation from UTC. Its value might range from +14:00 to -14:00 hours, both inclusive. Otherwise, the result is an empty sequence.
Examples
The function returns the corresponding date values for the value mentioned in the DATE column:
DATE
RETURN VALUE
1999-05-31-05:00
-PT5H
timezone-from-dateTime
Returns the timezone component of an xs:dateTime.
Syntax
fn:timezone-from-dateTime(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a datetime that must be converted to a timezone.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns the timezone component of $arg, if any. If $arg has a timezone component, the result is an xs:dayTimeDuration that indicates deviation from UTC. Its value might range from +14:00 to -14:00 hours, both inclusive. If $arg has no timezone component, the result is the empty sequence.
Examples
The function returns the corresponding date values for the value mentioned in the DATETIME column:
DATETIME
RETURN VALUE
1995-05-31T13:20:00-05:00
-PT5H
timezone-from-time
Returns the timezone component of an xs:time.
Syntax
fn:timezone-from-time(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a time that must be converted to a timezone.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise the fucntion returns the timezone component of the xs:time value supplied as argument. The result is an xs:dayTimeDuration that indicates deviation from UTC. Its value might range from +14:00 to -14:00 hours, both inclusive.
Examples
The function returns the corresponding date values for the value mentioned in the TIME column:
TIME
RETURN VALUE
12:00:00-05:00
-PT5H
toChar
Converts the date passed to a string based on the specified format string.
Syntax
date:toChar(date, format)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a date that must be converted to a specified format string.
Examples
The function returns the corresponding date values for the value mentioned as arg in the DATE column:
DATE
RETURN VALUE
date:toChar(08-02-2017, DL)
August 02, 2017
toDate
Converts a character string to a date data type. You use the toDate format strings to specify the format of the source strings.
The output port must be Date/Time for toDate expressions.
If you are converting two-digit years with toDate, use either the RR or YY format string. Do not use the YYYY format string.
Syntax
date:toDate(xs:dateTime('date'), 'format')
Note: You must manually add the date phrase and enclose the date values within single quotation marks.
The following table describes the arguments:
Argument
Required/
Optional
Description
date
Required
Must be a string data type. Passes the values that you want to convert to dates. You can enter any valid transformation expression.
format
Required
Enter a valid toDate format string. The format string must match the parts of the date argument. For example, if you pass the date 'Mar 15 1998 12:43:10AM', you must use the format string 'MON DD YYYY HH12:MI:SSAM'.
Return Value
Date.
The toDate function always returns a date and time. If you pass a string that does not have a time value, the date returned always includes the time 00:00:00.000000000. You can map the results of this function to any target column with a datetime data type.
The following table lists some sample values and return values:
DATE_STR
RETURN_VALUE
'12/31/1999 3783'
12/31/1999 01:02:03
'09/15/1996 86399'
09/15/1996 23:59:59
trunc (Dates)
Truncates dates to a specific year, month, day, hour, minute, second, or millisecond.
You can truncate the following date parts:
•Year. If you truncate the year portion of the date, the function returns Jan 1 of the input year with the time set to 00:00:00.000000000. For example, the following expression returns 1/1/1997 00:00:00.000000000:
•Month. If you truncate the month portion of a date, the function returns the first day of the month with the time set to 00:00:00.000000000. For example, the following expression returns 4/1/1997 00:00:00.000000000:
•Day. If you truncate the day portion of a date, the function returns the date with the time set to 00:00:00.000000000. For example, the following expression returns 6/13/1997 00:00:00.000000000:
•Hour. If you truncate the hour portion of a date, the function returns the date with the minutes, seconds, and milliseconds set to 0. For example, the following expression returns 4/1/1997 11:00:00.000000000:
•Minute. If you truncate the minute portion of a date, the function returns the date with the seconds and milliseconds set to 0. For example, the following expression returns 5/22/1997 10:15:00.000000000:
•Second. If you truncate the second portion of a date, the function returns the date with the milliseconds set to 0. For example, the following expression returns 5/22/1997 10:15:29.000000000:
•Millisecond. If you truncate the millisecond portion of a date, the function returns the date with the microseconds set to 0. For example, the following expression returns 5/22/1997 10:15:30.135000000:
The following table lists some sample values and return values:
DATE_SHIPPED
RETURN VALUE
Jan 15 1998 2:10:31AM
Jan 15 1998 02:00:00.000000000
Apr 19 1998 1:31:20PM
Apr 19 1998 13:00:00.000000000
Jun 20 1998 3:50:04AM
Jun 20 1998 03:00:00.000000000
Dec 20 1998 3:29:55PM
Dec 20 1998 15:00:00.000000000
Dec 31 1998 11:59:59PM
Dec 31 1998 23:00:00.000000000
NULL
NULL
The following expression truncates the minute portion of each date in the DATE_SHIPPED column:
date:trunc(xs:dateTime('DATE_SHIPPED'), 'MI')
The following table lists some sample values and return values:
DATE_SHIPPED
RETURN VALUE
Jan 15 1998 2:10:30AM
Jan 15 1998 02:10:00.000000000
Apr 19 1998 1:31:20PM
Apr 19 1998 13:31:00.000000000
Jun 20 1998 3:50:04AM
Jun 20 1998 03:50:00.000000000
Dec 20 1998 3:29:55PM
Dec 20 1998 15:29:00.000000000
Dec 31 1998 11:59:59PM
Dec 31 1998 23:59:00.000000000
NULL
NULL
year-from-date
Returns an xs:integer representing the year in the localized value of $arg. The value might be negative.
Syntax
fn:year-from-date(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a date that must be converted to a year format.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer representing the year in the localized value of $arg.
Examples
The function returns the corresponding year values for the value mentioned as arg in the DATE column:
DATE
RETURN VALUE
1999-06-30
1999
2001-01-01+05:00
2001
year-from-dateTime
Returns an xs:integer representing the year component in the localized value of $arg.
Syntax
fn:year-from-dateTime(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a datetime that must be converted to a year format.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer representing the year in the localized value of $arg.
Examples
The function returns the corresponding year values for the value mentioned as arg in the DATETIME column:
DATETIME
RETURN VALUE
1999-06-30+08:00
1999
2001-01-01+05:00
2001
years-from-duration
Returns an xs:integer representing the years component in the value of $arg. The result is obtained by casting $arg to an xs:yearMonthDuration.
Syntax
fn:years-from-duration(arg)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument as a duration that must be converted to years.
Return Value
If $arg is an empty sequence, the function returns the empty sequence. Otherwise, the function returns an xs:integer representing the years component in the value of $arg. Given that a duration is a ($months, $seconds) tuple, the result is the value of ($months idiv 12).
Examples
The function returns the corresponding date values for the value mentioned as arg in the DURATION column:
DATETIME
RETURN VALUE
P20Y15M
21
-P15M
-1
Lists
The following functions are available in the Lists section of the Expression Editor:
append
The append function in XQuery concatenates two input sequences by returning a sequence consisting of all items from the first sequence followed by all items from the second sequence.
Syntax
list:append(objectlist, newItem)
The following table describes the argument for this command:
Argument
Required/Optional
Description
objectlist
Required
The first sequence of items to be concatenated.
newItem
Required
The second sequence of items to append to the first
Return Value
•Returns a sequence of items: all items from objectlist followed by all items from newItem.
•If one of the inputs is an empty sequence, returns the other sequence.
•The order of items in both sequences is preserved.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
list:append((), ("a", "b"))
a;b
list:append(("apple"), ())
("apple")
list:append((), ())
()
Additional information
•It works with sequences of any type, such as atomic values, nodes, or mixed.
•It preserves the order of the original sequences.
count
The count function in XQuery returns the number of items in a sequence.
Syntax
list:count(objectlist)
The following table describes the argument for this command:
Argument
Required/Optional
Description
objectlist
Required
The input sequence whose items are to be counted.
Return Value
•Returns an xs:integer representing the number of items in the input sequence.
•Returns 0 if the input sequence is empty.
Examples
The following table lists some sample values and return values:
•It is useful for determining sequence size in conditional expressions, loops, or in data processing.
•The function counts all items in the sequence, regardless of type.
head
The head function in XQuery returns the first item in a sequence or the empty sequence if the input sequence is empty.
Syntax
list:head(objectlist)
The following table describes the argument for this command:
Argument
Required/Optional
Description
objectlist
Required
The input sequence from which the first item is to be returned.
Return Value
•Returns the first item in $seq if the sequence is non-empty.
•Returns the empty sequence () if the input $seq is empty.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
list:head((10, 20, 30))
10
list:head(())
()
list:head(("apple", "banana"))
"apple"
Additional information
•head is used to retrieve the initial item from a sequence, similar to the fn:subsequence($seq, 1, 1) but more efficient and straightforward.
•This function is part of XPath/XQuery 3.1.
•It can return any item type, such as atomic or node.
list
The list function in XQuery converts a sequence of IDs into a semicolon-separated list of IDs for an object list.
Syntax
list:list(sequence)
The following table describes the argument for this command:
Argument
Required/Optional
Description
sequence
Required
A sequence of items to be included in the list.
Return Value
Returns a sequence of a semicolon-separated list of the input items.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
list:list(('a','b','c'))
("a", "b", "c")
list:list((1,2,3))
(1, 2, 3)
remove
The remove function in XQuery returns a sequence that is the input sequence with the item at the specified position removed.
Syntax
list:remove(objectlist, position)
The following table describes the argument for this command:
Argument
Required/Optional
Description
objectlist
Required
The input sequence from which an item is to be removed.
position
Required
The 1-based position of the item to remove from $seq.
Return Value
•Returns a sequence with the item at position $pos removed.
•If $pos is less than 1 or greater than the length of $seq, the original $seq is returned unchanged.
•Sequence order is preserved except the removed item.
Additional information
•The 1-based index means $pos=1 targets the first item.
•This function is part of XPath/XQuery 3.1.
•It is useful in manipulating sequences dynamically by removing specific items.
replace
The replace function in XQuery replaces an existing item in a list with a new value.
Syntax
list:replace(objectlist, position, newItem)
The following table describes the argument for this command:
Argument
Required/Optional
Description
objectlist
Required
The sequence or list in which to replace the item.
position
Required
The 1-based position of the item to replace.
newItem
Required
The new item to insert in place of the old one.
Return Value
•Returns a sequence where the item at position position in the input sequence objectlist is replaced by newItem.
•If position is out of range (less than 1 or greater than the length of objectlist), the original sequence is returned unchanged.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
list:replace((10, 20, 30, 40), 2, 25)
(10, 25, 30, 40)
list:replace(("a", "b", "c"), 1, "x")
("x", "b", "c")
list:replace((1, 2, 3), 4, 5)
(1, 2, 3)
sequence
The sequence function in XQuery converts a semicolon-separated list to a sequence. When an object list field is inserted into formula and content, the field is wrapped in the list:sequence(objectlist_field_name) XQuery function. For object lists in hosted objects, this converts the semicolon separated list of IDs in the object list into a sequence. For object lists for process objects, the value is already a sequence and the function returns the list unchanged.
Examples
The following example converts an object list in a semicolon-separated list, then iterates over each item:
for $objectid in list:sequence($objectlist) ...
The following example converts a sequence of IDs into a semicolon-separated list of IDs for an object list for hosted objects. For an object list for process objects, it returns a sequence of values:
let $mergedObjectLists := ( as:sequence($objectlist1), as:sequence($objectlist2) ) return list:list($mergedObjectLists)
tail
The tail function in XQuery returns all items of an input sequence except for the first item. If the input sequence is empty or contains only one item, the result is an empty sequence.
Syntax
list:tail(objectlist)
The following table describes the argument for this command:
Argument
Required/Optional
Description
objectlist
Required
The input sequence from which the tail, that is except for the first item is returned.
Return Value
•Returns a sequence containing all items from the input sequence except the first.
•Returns the empty sequence () if the input has zero or one item.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
list:tail((10, 20, 30, 40))
(20, 30, 40)
list:tail(("apple", "banana"))
("banana")
list:tail((<a/>, <b/>, <c/>))
(<b/>, <c/>)
list:tail((42))
()
list:tail(())
()
Math functions
The following functions are available in the Math section of the Expression Editor:
acos
The acos function in XQuery returns the arc cosine, that is inverse cosine of a numeric input value. The input represents the cosine of an angle, and the function returns the angle in radians, within the range 0 to π.
Syntax
math:acos(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
A numeric value representing the cosine of an angle; valid input range is -1 to 1.
Return Value
•Returns the angle in radians whose cosine is the input value $arg.
•Returns an empty sequence if the input is an empty sequence or if the input is outside the valid range, that is -1 to 1.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:acos(1)
0
math:acos(0)
1.57079632679
math:acos(-1)
3.14159265359
math:acos(1.5)
empty sequence
math:acos(())
()
Additional information
•The function expects the input value to be between -1 and 1 inclusive. Values outside this range are invalid.
•The result is given in radians.
•The function gracefully handles empty inputs by returning an empty sequence.
asin
The asin function in XQuery returns the arcsine (inverse sine) of a numeric input value. The input represents the sine of an angle, and the function returns the angle in radians, within the range -π/2 to π/2.
Syntax
math:asin(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
A numeric value representing the sine of an angle; valid input range is -1 to 1.
Return Value
•Returns the angle in radians whose sine is the input value $arg.
•Returns the arc sine of the argument, the result being in the range -π/2 to +π/2 radians.
•Returns an empty sequence if the input is an empty sequence or if the input is outside the valid range (-1 to 1).
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:asin(0)
0
math:asin(1)
1.57079632679
math:asin(-1)
-1.57079632679
math:asin(1.5)
Empty sequence
math:asin(())
()
Additional information
•The input value must be between -1 and 1 inclusive to be valid.
•The function returns the corresponding angle in radians.
•It gracefully handles empty inputs by returning an empty sequence.
atan
The atan function in XQuery returns the arctangent (inverse tangent) of a numeric input value. It calculates the angle in radians whose tangent is the given number. The result ranges from -π/2 to π/2.
Syntax
math:atan(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
A numeric value representing the tangent of an angle.
Return Value
•Returns the angle in radians whose tangent is the input value $arg.
•Returns the arc tangent of the argument, the result being in the range -π/2 to +π/2 radians.
•Returns an empty sequence if the input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:atan(0)
0
math:atan(1)
0.78539816339
math:atan(-1)
-0.78539816339
math:atan(())
()
Additional information
•The input value can be any numeric value (positive, negative, or zero).
•The function returns the corresponding angle in radians.
•It handles empty inputs gracefully by returning an empty sequence.
•Unlike atan2, this function takes a single argument only.
atan2
The atan2 function in XQuery returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis, the result being in the range -π to +π.
Syntax
math:atan2(arg1, arg2)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The y-coordinate or numerator in the quotient (tan θ = y/x).
arg2
Required
The x-coordinate or denominator in the quotient.
Return Value
•Returns the angle in radians between the positive x-axis and the point (x, y).
•Returns an empty sequence if either input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT (approximate)
math:atan2(0, 1)
0
math:atan2(1, 1)
0.78539816339
math:atan2(1, 0)
1.57079632679
math:atan2(-1, -1)
-2.35619449019
math:atan2((), 2)
()
math:atan2(1, ())
()
Additional information
•The function helps determine the angle taking into account the signs of both coordinates, providing the correct quadrant.
•Inputs must be numeric and can be positive, negative, or zero.
•It handles empty inputs gracefully by returning an empty sequence.
cos
The cos function in XQuery returns the cosine of a numeric input value, where the input represents an angle expressed in radians.
Syntax
math:cos(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The angle in radians to calculate the cosine of. It can be any numeric type.
Return Value
•Returns the cosine of the input angle $arg as a numeric value.
•Returns an empty sequence if the input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:cos(0)
1
math:cos(math:pi())
-1
math:cos(())
()
Additional information
•The input value must be in radians.
•The function handles empty sequences by returning an empty sequence.
exp
The exp function in XQuery calculates the exponential of a given numeric input, returning e^{x}, where e is Euler’s number that is approximately 2.71828, and x is the input argument.
Syntax
math:exp(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The exponent value used to calculate ( e^{x} ). Accepts any numeric type (integer, decimal, float, double).
Return Value
•Returns the exponential value ( e^{x} ) as a numeric type.
•Returns an empty sequence if the input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:exp(0)
1
math:exp(1)
2.718281828459045
math:exp(2)
7.38905609893065
math:exp(-1)
0.367879441171442
math:exp(())
()
Additional information
•The input can be any numeric value, such as positive, negative, or zero.
•The function returns a numeric value of the exponential calculation.
•Gracefully handles empty input by returning an empty sequence.
exp10
The exp10 function in XQuery returns the value of 10 raised to the power of the numeric input argument, that is it calculates ( 10^x ), where ( x ) is the input value.
Syntax
math:exp10(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The exponent value ( x ) used to calculate ( 10^x ). Accepts any numeric type.
Return Value
•Returns the numeric result of ( 10^{x} ).
•Returns an empty sequence if the input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:exp10(0)
1
math:exp10(1)
10
math:exp10(2)
100
math:exp10(-1)
0.1
math:exp10(())
()
Additional information
•Input can be any numeric value including negative, zero, or positive.
•The function gracefully handles empty input by returning an empty sequence.
•The return type depends on the input numeric type.
log
The log function in XQuery returns the natural logarithm of the argument.
Syntax
math:log(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The positive numeric value to compute the natural logarithm of.
Return Value
•Returns the natural logarithm (base ( e )) of the input value.
•Returns an empty sequence if the input is an empty sequence.
•Usually returns an error or empty if input is less than or equal to zero, since logarithm is undefined for those.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:log(1)
0
math:log(math:e())
1
math:log(10)
2.302585092994046
math:log(-1)
Error or empty sequence
math:log(())
()
Additional information
•The function argument must be a positive numeric value.
•Passing zero, negative numbers, or empty sequences will result in an error or empty sequence.
•Returns a numeric value representing the natural logarithm.
log10
The log10 function in XQuery returns the base-ten logarithm of the argument.
Syntax
math:log10(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The positive numeric value to compute the base-10 logarithm of.
Return Value
•Returns the base-10 logarithm of the input value.
•Returns an empty sequence if the input is an empty sequence.
•Returns an error or empty sequence for values less than or equal to zero, as logarithm is undefined for these.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:log10(1)
0
math:log10(10)
1
math:log10(100)
2
math:log10(-5)
Error or empty sequence
math:log10(())
()
Additional information
•The input value must be positive.
•The function returns a numeric value representing the base-10 logarithm.
•It gracefully handles empty input by returning an empty sequence.
pi
The pi function in XQuery returns the mathematical constant π (pi), which is approximately 3.141592653589793.
Syntax
math:pi()
Return Value
Returns the constant π as a double precision floating-point number (xs:double).
Examples
The following table shows the sample value and its return value:
SAMPLE FUNCTION
OUTPUT
math:pi()
3.141592653589793
Additional information
•This function does not accept any parameters.
•The return type is always xs:double.
•It is useful for mathematical calculations requiring the pi constant.
pow
The pow function in XQuery returns the value of the first numeric argument raised to the power of the second numeric argument, that is ( x^y ).
Syntax
math:pow(arg1, arg2)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The base number to be raised to a power.
arg2
Required
The exponent value to raise the base to.
Return Value
•Returns the value of $base raised to the power of $exponent.
•Returns an empty sequence if either argument is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:pow(2, 3)
8
math:pow(10, 0)
1
math:pow(5, -1)
0.2
math:pow((), 2)
()
math:pow(2, ())
()
Additional information
•Both parameters are required and must be numeric.
•The function supports integer, decimal, float, and double numeric types.
•It returns a numeric value representing the power calculation.
•Gracefully handles empty inputs by returning an empty sequence.
sin
The sin function in XQuery returns the sine of a numeric input angle, where the angle is given in radians.
Syntax
math:sin(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The angle in radians for which to compute the sine.
Return Value
•Returns the sine of the input angle as a numeric value.
•Returns an empty sequence if the input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:sin(0)
0
math:sin(math:pi() div 2)
1
math:sin(math:pi())
1.2246467991473532E-16
math:sin(())
()
Additional information
•The input angle must be in radians.
•The function handles empty input gracefully by returning an empty sequence.
•The return type matches the numeric type of the input argument or is a compatible numeric type.
sqrt
The sqrt function in XQuery returns the square root of a non-negative numeric input value.
Syntax
math:sqrt(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
A non-negative numeric value to compute the square root of.
Return Value
•Returns the square root of the input value as a numeric.
•Returns an empty sequence if the input is an empty sequence.
•Typically results in an error or empty sequence if the input is negative, as the square root of a negative number is undefined in the real number domain.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:sqrt(9)
3
math:sqrt(0)
0
math:sqrt(2)
1.41421356237
math:sqrt(-1)
Error or empty sequence
math:sqrt(())
()
Additional information
•The input must be zero or positive for a real result.
•The function returns a numeric value matching the input type or a compatible numeric type.
•It handles empty input gracefully by returning an empty sequence.
tan
The tan function in XQuery returns the tangent of a given numeric value interpreted as an angle in radians.
Syntax
math:tan(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The input angle in radians.
Return Value
•Returns the tangent value of the input angle in radians as an xs:double.
•Returns true if the xml:lang attribute of the node or its nearest ancestor matches the $testlang value.
•Returns false if there is no match or if xml:lang is absent.
•Returns an empty sequence if the input is an empty sequence or invalid.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
math:tan(0)
0
math:tan(1)
Approximately 1.55740772465490
math:tan(3.1415926535 div 4)
0.9999999999999999
math:tan(())
()
Additional information
•The input angle is always in radians, not degrees.
•To use degrees, you can convert degrees to radians as shown in the following expression:
radians := degrees * (fn:pi() div 180)
•The fn:tan function is useful in mathematical, geometric, and trigonometric calculations written in XQuery expressions.
Miscellaneous functions
The following functions are available in the Miscellaneous section of the Expression Editor:
aesDecryption
Decrypts the specified data with the provided key using the Advanced Encryption Standard (AES) algorithm. You must use the same key that you had used for encrypting the data in the aesEncryption function.
Syntax
util:aesDecryption(key, dataToDecrypt)
Return Value
The function returns a decrypted value.
Examples
The following example returns decrypted values for the data and the key passed as inputs in the function:
Encrypts the specified data with the provided key using the Advanced Encryption Standard (AES) algorithm.
Syntax
util:aesEncryption(key, dataToEncrypt)
Return Value
The function returns an encrypted value.
Examples
The following example returns encrypted values for the data and the key passed as inputs in the function:
SAMPLE FUNCTION
OUTPUT
util:aesEncryption("1234@abc", "Informatica")
QETcr60N6QBSTB0X8V4Y+GL\/K0+nt7M6ON0VommGAU4=
util:aesEncryption("abcdefghkl", "cloud")
tceVjWKW2lKWQ+ZJfHn4gUKXPDUPrEilmNoTueesPo0=
decode
Searches a column for a value that you specify. If the function finds the value, it returns a result value, which you define. You can build an unlimited number of searches within a decode function.
If you use decode to search for a value in a string column, you can either trim trailing blank characters with the rtrim function or include the blanks in the search string.
You can enter any valid transformation expression. You can pass any data type except Binary.
To pass a NULL value, you must specify an empty sequence in the following format: ()
search1
Required
Passes the values for which you want to search.
You can enter any valid transformation expression. You can pass any value with the same data type as the value argument. The search value must match the value argument. You cannot search for a portion of a value. Also, the search value is case sensitive.
For example, if you want to search for the string 'Halogen Flashlight' in a particular column, you must enter 'Halogen Flashlight, not just 'Halogen'. If you enter 'Halogen', the search does not find a matching value.
To pass a NULL value, you must specify an empty sequence in the following format: ()
result1
Required
The value that you want to return if the search finds a matching value.
You can enter any valid transformation expression and pass any data type except Binary.
To pass a NULL value, you must specify an empty sequence in the following format: ()
args
Required
Pairs of search values and result values separated by a comma.
Escapes special characters in the provided string to make it valid for usage in JSON.
Syntax
util:escapeJsonString(str)
Return Value
Encodes and returns the value as a JSON string according to http://json.org/ rules.
Examples
The function returns the following values for various strings provided as input:
STRING INPUT
RETURN VALUE
//
/\/\
Item1, Items2
Item1, Items2
\n
\\\\n
getAssetLocation
Returns the location where the process or the guide that uses the function is stored.
Note: In addition to guides, you can use the getAssetLocation function only in processes that run on the Cloud Server.
Syntax
util:getAssetLocation()
Return Value
The function returns the location of the folder where the asset exists.
getAssetName
Returns the name of the process or the guide that uses the function.
Syntax
util:getAssetName()
Return Value
The function returns the asset name as a string in the output.
getInstanceStartTime
Returns the start time of the running instance of the specified process or guide.
Syntax
util:getInstanceStartTime()
Return Value
The function returns the start time of the running instance corresponding to the specified asset. The function returns an output in the yyyy-MM-dd'T'HH:mm:ss.SS'Z' format.
Examples
The following sample displays the result of the function that is used in a process:
2023-09-20T09:02:50.774Z
getOrganizationId
Returns the Informatica Intelligent Cloud Services organization ID string in the context of the executing instance.
Syntax
util:getOrganizationId()
Return Value
When the process is deployed on the agent, the function returns the output as $public.
When the process is deployed on the cloud server, the function returns the Informatica Intelligent Cloud Services organization ID string as the output.
Examples
The following sample displays the result of the function:
getOrganizationName
Returns the organization name in the context of the executing process, guide, service connector, or data access service connector.
Syntax
util:getOrganizationName()
Return Value
The function returns the organization name string as the output.
iif
Returns one of two values that you specify based on the results of a condition.
Syntax
util:iif(condition, val1 ,val2)
The following table describes the arguments:
Argument
Required/Optional
Description
condition
Required
The condition that you want to evaluate.
You can enter any valid transformation expression that evaluates to TRUE or FALSE.
val1
Required
The value that you want to return if the condition is TRUE. The return value is always the data type specified by this argument.
You can enter any valid transformation expression, including another iif expression. You can pass any data type except Binary.
val2
Optional
The value that you want to return if the condition is FALSE.
You can enter any valid transformation expression, including another iif expression. You can pass any data type except Binary.
The FALSE (val2) condition in the iif function is not required. If you omit val2, the function returns one of the following values when the condition is FALSE:
•0 if val1 is a Numeric data type.
•Empty string if val1 is a String data type.
•NULL if val1 is a Date/Time data type.
For example, the following expression does not include a FALSE condition and val1 is a string data type so decode returns an empty string for each row that evaluates to FALSE:
util:iif(SALES > 100, EMP_NAME)
The following table lists some sample values and return values:
SALES
EMP_NAME
RETURN VALUE
150
John Smith
John Smith
50
Pierre Bleu
'' (empty string)
120
Sally Green
Sally Green
NULL
Greg Jones
'' (empty string)
Return Value
val1 if the condition is TRUE.
val2 if the condition is FALSE.
For example, the following expression includes the FALSE condition NULL so decode returns NULL for each row that evaluates to FALSE:
util:iif(SALES > 100, EMP_NAME, NULL)
The following table lists some sample values and return values:
SALES
EMP_NAME
RETURN VALUE
150
John Smith
John Smith
50
Pierre Bleu
NULL
120
Sally Green
Sally Green
NULL
Greg Jones
NULL
iif and data types
When you use iif, the data type of the return value is the same as the data type of the result with the greatest precision.
For example, you have the following expression:
util:iif(SALES < 100, 1, .3333)
The TRUE result (1) is an integer and the FALSE result (.3333) is a decimal. The Decimal data type has a greater precision than the Integer data type. Therefore, the data type of the return value is always a decimal value.
Special uses of iif
Use nested iif statements to test multiple conditions. The following example tests for various conditions and returns 0 if sales is 0 or negative:
Matches input data to a list of values. By default, the match is case sensitive.
Syntax
util:in(valueToSearch, values, caseFlag)
The following table describes the arguments:
Argument
Required/
Optional
Description
valueToSearch
Required
Can be a string, date, or numeric value. Input value that you want to match against a comma-separated list of values.
To pass a NULL value, you must specify an empty sequence in the following format: ()
values
Required
Can be a string, date, or numeric value. Comma-separated list of values that you want to search for. Values can be columns. There is no limit to the maximum number of values that you can list.
To pass a NULL value, you must specify an empty sequence in the following format: ()
caseFlag
Optional
Must be an integer. Determines whether the arguments in this function are case sensitive. You can enter any valid transformation expression.
When caseFlag is a number other than 0, the function is case sensitive.
When caseFlag is a null value or 0, the function is not case sensitive.
Return Value
TRUE (1) if the input value matches the list of values.
FALSE (0) if the input value does not match the list of values.
NULL if the input is a null value.
Example
The following expression determines if the input value is a safety knife, chisel point knife, or medium titanium knife. The input values do not have to match the case of the values in the comma-separated list:
util:in(ITEM_NAME, ‘Chisel Point Knife’, ‘Medium Titanium Knife’, ‘Safety Knife’, 0)
The following table lists some sample values and return values:
ITEM_NAME
RETURN VALUE
Stabilizing Vest
0 (FALSE)
Safety knife
1 (TRUE)
Medium Titanium knife
1 (TRUE)
NULL
isNull
Returns whether a value is NULL.
Syntax
util:isNull(value)
The following table describes the argument for this command:
Argument
Required/
Optional
Description
value
Required
Passes the rows that you want to evaluate. You can enter any valid transformation expression. You can pass a value of any data type except Binary.
Return Value
TRUE (1) if the value is NULL.
FALSE (0) if the value is not NULL.
Example
The following example checks for NULL values in the items table:
util:isNull( ITEM_NAME )
The following table lists some sample values and return values:
ITEM_NAME
RETURN VALUE
Flashlight
0 (FALSE)
NULL
1 (TRUE)
Regulator system
0 (FALSE)
''
0 (FALSE) Empty string is not NULL
removeSystemNamespaceXML
Removes system namespaces from an XML document to provide a more simplified and readable XML structure.
Syntax
util:removeSystemNamespaceXML(currentElement)
Return Value
The function returns a more simplified and readable XML structure.
Examples
The following table contains an example of an XML code snippet that is passed as an input in the function and the corresponding XML output:
Asymmetric encryption is a cryptographic method that uses a public-private key pair and optionally a passphrase or password to encrypt and decrypt data. The rsaDecryption function decrypts cipher text using the RSA algorithm with the provided private key and passphrase. You can protect private keys with a passphrase. If you're not using a passphrase, leave the string empty. If your key file isn't password protected, the passphrase is ignored.
Note: You can decrypt data only in a process configured to run on a Secure Agent, and the key file must be available on the selected agent.
You can use the following types of keys for RSA encryption:
•GPG keys. The keys must be in the ASCII format, and the private keys must be protected with a passphrase.
•OpenSSL keys. The keys must be in the PKCS#8 format and be encoded as a PEM file for use in encryption and decryption. You can protect the private keys with a passphrase.
RSA limits the amount of data you can encrypted or decrypted based on the following key size:
•With a1024-bit key, you can encrypt up to 128 bytes of data.
•With a 2048-bit key, you can encrypt up to 256 bytes of data.
•With a 4096-bit key, you can encrypt up to 512 bytes of data.
Asymmetric encryption is a cryptographic method that uses a public-private key pair and optionally a passphrase or password to encrypt and decrypt data. The rsaEncryption function encrypts data using the RSA algorithm and the provided public key.
Note: You can encrypt data only in a process configured to run on a Secure Agent, and the key file must be available on the selected agent.
You can use the following types of keys for RSA encryption:
•GPG keys. The keys must be in the ASCII format, and the private keys must be protected with a passphrase.
•OpenSSL keys. The keys must be in the PKCS#8 format and be encoded as a PEM file for use in encryption and decryption. You can protect the private keys with a passphrase.
RSA limits the amount of data you can encrypted or decrypted based on the following key size:
•With a1024-bit key, you can encrypt up to 128 bytes of data.
•With a 2048-bit key, you can encrypt up to 256 bytes of data.
•With a 4096-bit key, you can encrypt up to 512 bytes of data.
Syntax
util:rsaEncryption(keyType, key, dataToEncrypt)
The following table describes the arguments for this command:
Argument
Description
keyType
Specifies the type of RSA key used.
You can enter one of the following values:
- GPG
- OpenSSL
key
The absolute path of the public key file on the selected agent.
The Expression Editor accepts the file path of keys as input instead of the keys itself.
dataToEncrypt
The plain text data that you want to encrypt.
Return Value
The function returns a base64-encoded text as a result of the RSA encryption.
Examples
The following example returns encrypted values for the data based on the key passed as inputs in the function:
Converts a string or numeric value to a decimal value. The toDecimal function ignores leading spaces.
Syntax
util:toDecimal(value, scale)
The following table describes the arguments:
Argument
Required/
Optional
Description
value
Required
Must be a string or numeric data type. Passes the value that you want to convert to decimals.
You can enter any valid transformation expression.
scale
Optional
Must be an integer literal between 0 and 28, inclusive. Specifies the number of digits allowed after the decimal point. If you omit this argument, the function returns a value with the same scale as the input value.
This argument is required in advanced mode.
Return Value
Decimal of precision and scale between 0 and 28, inclusive.
0 if the value in the selected column is an empty string or a non-numeric character.
NULL if a value passed to the function is NULL.
Example
This expression uses values from the column IN_TAX. The data type is decimal with precision of 10 and scale of 3:
util:toDecimal(IN_TAX, 3)
The following table lists some sample values and return values:
IN_TAX
RETURN VALUE
'15.6789'
15.679
'60.2'
60.200
'118.348'
118.348
NULL
NULL
'A12.3Grove'
0
This expression uses values from the column Sales. The data type is decimal with precision of 10 and scale of 2:
util:toDecimal(Sales, 2)
The following table lists some sample values and return values:
Sales
RETURN VALUE
'1234'
1234
'1234.01'
1234.01
If you want the return value in 1234.00 format, you can use the following expression:
format-number(util:toDecimal('1234', 2), '0.00')
Decimal overflow
If the size of the number on the left hand side of the decimal point exceeds the precision, the decimal operation overflows.
To resolve this, modify the scale and/or precision of the expression port and connect downstream ports of the mapping to accommodate the size of the input data in the expression.
For example:
If a numeric field is defined to be size 28 with scale of 15, this accepts 13 numbers on the left side of the decimal and 15 on the right. So the following numbers would be valid for a number of 28,15:
1234567890123.11143
13575.123451234567891
However, these numbers would cause a decimal overflow error:
111112222233333.4444
123.1111122222333334
toInteger
Converts a string or numeric value to an integer. The toInteger syntax contains an optional argument that you can choose to round the number to the nearest integer or truncate the decimal portion. The toInteger function ignores leading spaces.
Syntax
util:toInteger(value, flag)
The following table describes the arguments:
Argument
Required/
Optional
Description
value
Required
Must be a string or numeric data type. Passes the value that you want to convert to an integer.
You can enter any valid transformation expression.
flag
Optional
Specifies whether to truncate or round the decimal portion. The flag must be an integer literal or the constants TRUE or FALSE:
- toInteger truncates the decimal portion when the flag is TRUE or a number other than 0.
- toInteger rounds the value to the nearest integer if the flag is FALSE or 0 or if you omit this argument.
Return Value
Integer.
NULL if a value passed to the function is NULL.
0 if a value passed to the function contains alphanumeric characters.
Example
The following expressions use values from the column IN_TAX:
util:toInteger(IN_TAX, fn:boolean(1))
The following table lists some sample values and return values:
IN_TAX
RETURN VALUE
'15.6789'
15
'60.2'
60
'118.348'
118
NULL
NULL
'A12.3Grove'
0
' 123.87'
123
'-15.6789'
-15
'-15.23'
-15
trace
Provides an execution trace to be used in debugging queries.
The fn:trace function accepts items and a label for those items and returns the items unchanged. The exact behavior of the function is implementation-dependent, but generally the processor puts the label and the value of the items in a log file or user console.
Syntax
fn:trace(value, label)
The following table describes the arguments:
Argument
Required/
Optional
Description
value
Required
The items to trace.
label
Optional
A label to display with the trace information.
Return Value
Based on the items and a label for those items, it returns the items unchanged.
Example
Assume that you have the following variable definition:
let $var1 := 5
The following expression returns The correct value is: 5 as the result:
fn:trace($var1, 'The correct value is: ')
trunc (Numbers)
Truncates numbers to a specific digit based on the number of decimal places specified by the precision.
Syntax
util:trunc(arg, precision)
Argument
Required/
Optional
Description
arg
Required
Numeric data type. Passes the argument that you want to truncate. You can enter any valid expression that evaluates to a numeric data type.
precision
Optional
Can be a positive or negative integer. You can enter any valid expression that evaluates to an integer. The integer specifies the number of digits to truncate.
If precision is a positive integer, trunc returns arg with the number of decimal places specified by precision. If precision is a negative integer, trunc changes the specified digits to the left of the decimal point to zeros. If you omit the precision argument, trunc truncates the decimal portion of arg and returns an integer.
All trailing zeros after the decimal point in an argument will be truncated. For example, the following expression returns 2345.7535 as the result:
util:trunc(2345.75350000, 6)
If a number contains more than 16-digits after the decimal point, the result returns an exponential value due to an XQuery limitation.
For example, the following expression returns 1.234567812345679E7 as the result:
util:trunc(12345678.12345678901234567890, 15)
If you pass a decimal precision value, the arg is rounded to the nearest integer before evaluating the expression.
Return Value
Numeric or integer value based on the parameters provided in the function.
Examples
The following expressions truncate the values in the PRICE column:
util:trunc(PRICE, 3)
PRICE
RETURN VALUE
12.9995
12.999
-18.8652
-18.865
56.9563
56.956
15.9928
15.992
util:trunc(PRICE, -1)
PRICE
RETURN VALUE
12.99
10
-187.86
-180
56.95
50
1235.99
1230
util:trunc(PRICE )
PRICE
RETURN VALUE
12.99
12
-18.99
-18
56.95
56
15.99
15
serialize
This function serializes the supplied node $arg, returning the serialized node as a string.
Syntax
fn:serialize()
Return Value
When the process is deployed on the cloud server or agent, the function returns a string output.
Examples
The function returns the following output for the provided input using Saxon 9.5.1.10 PE version:
INPUT
OUTPUT
<a/> (element)
<?xml...?><a/>
"<a/>" (string)
<a/>
The function returns the following output for the provided input using Saxon 11.5 EE version:
INPUT
OUTPUT
<a/> (element)
<a/>
"<a/>" (string)
<a/>
For more information about changed behaviors in Application Integration due to Saxon libraries upgrade, see the following knowledge base article: KB 000205484.
simplifyXml
Rearranges data within XML so that it can be used by the process objects.
Syntax
util:simplifyXml(undefined)
Return Value
When the process is deployed on the cloud server or agent, the function returns an output without name spaces and convert attributes into child elements.
Examples
The function returns the following output for the XML data provided as input:
INPUT
OUTPUT
<ns:root xmlns:ns="https://qwerty" attrKey="attrValue"> data </ns:root>
The following functions are available in the Numbers section of the Expression Editor:
abs
Returns the absolute value of a numeric value.
Syntax
fn:abs(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Numeric datatype. Returns the absolute value of a number. You can enter any valid expression.
Return Value
•If you pass the argument as negative, it returns a negative argument value. Otherwise, returns a positive argument value.
•If type of argument is one of the four numeric types xs:float, xs:double, xs:decimal, or xs:integer, the type of the result is the same as the type of argument.
•If the type of argument is a type derived from one of the numeric types, the result is an instance of the base numeric type.
•NULL if you pass a null value to the function.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:abs(40)
40
fn:abs(3.5)
3.5
fn:abs(-4)
-4
Null
Null
The following expression returns the difference between two numbers as a positive value, regardless of which number is larger:
fn:abs( PRICE - COST )
PRICE
COST
RETURN VALUE
250
150
100
52
48
4
169.95
69.95
100
70
30
40
430
330
100
100
200
100
avg
Returns the average of the values in the input sequence given in the argument, that is, the sum of the values divided by the number of values.
Syntax
fn:avg(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Numeric data type. Passes the values for which you want to calculate an average. You can enter any valid transformation expression.
Return Value
•Numeric value.
•NULL if all values passed to the function are NULL.
Examples
The following table lists some sample values and return values:
SAMPLE Function
OUTPUT
fn:avg( (1, 2, 3, 4, 5) )
3
fn:avg( (1, 2, 3, (), 4, 5) )
3
fn:avg( () )
()
The following expression returns the average wholesale cost of flashlights:
fn:avg( WHOLESALE_COST, ITEM_NAME='Flashlight' )
ITEM_NAME
WHOLESALE_COST
Flashlight
35.00
Navigation Compass
8.05
Regulator System
150.00
Flashlight
29.00
Depth/Pressure Gauge
88.00
Flashlight
31.00
Tip
You can perform arithmetic on the values passed to AVG before the function calculates the average. For example:
fn:avg( QTY * PRICE - DISCOUNT )
ceiling
Returns the smallest, that is, closest to negative infinity number with no fractional part that is not less than the value of argument. If the type of argument is one of the four numeric types xs:float, xs:double, xs:decimal, or xs:integer, the type of the result is the same as the type of argument. If the type of argument is a type derived from one of the numeric types, the result is an instance of the base numeric type.
Syntax
fn:ceiling(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Numeric data type. You can enter any valid expression.
Return Value
•Integer if you pass a numeric value with declared precision between 0 and 28.
•Double value if you pass a numeric value with declared precision greater than 28.
•NULL if a value passed to the function is NULL.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:ceiling(5)
5
fn:ceiling(5.1)
6
fn:ceiling(5.5)
6
fn:ceiling(-5.5)
-5
fn:ceiling(-5.51)
-5
fn:ceiling( () )
()
The following expression returns the price rounded to the next integer:
fn:ceiling( PRICE )
PRICE
RETURN VALUE
39.79
40
125.12
126
74.24
75
NULL
NULL
-100.99
-100
Tip
You can perform arithmetic on the values passed to ceiling before ceiling returns the next integer value. For example, if you wanted to multiply a numeric value by 10 before you calculated the smallest integer less than the modified value, you might write the function as follows:
fn:ceiling( PRICE * 10 )
floor
Returns the largest, that is, closest to positive infinity number with no fractional part that is not greater than the value of argument. If type of argument is one of the four numeric types xs:float, xs:double, xs:decimal, or xs:integer, the type of the result is the same as the type of argument. If the type of argument is a type derived from one of the numeric types, the result is an instance of the base numeric type.
Syntax
fn:floor(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Numeric datatype. You can enter any valid expression as long as it evaluates to numeric data.
Return Value
•Integer if you pass a numeric value with declared precision between 0 and 28.
•Double if you pass a numeric value with declared precision greater than 28.
•NULL if a value passed to the function is NULL.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:floor(5)
5
fn:floor(5.1)
5
fn:floor(5.7)
5
fn:floor(-5.1)
-6
fn:floor(-5.7)
-6
fn:floor( () )
()
The following expression returns the largest integer less than or equal to the values in the PRICE column:
fn:floor( PRICE )
PRICE
RETURN VALUE
39.79
39
125.12
125
74.24
74
NULL
NULL
-100.99
-101
Tip
You can perform arithmetic on the values you pass to floor. For example, to multiply a numeric value by 10 and then calculate the largest integer that is less than the product, you might write the function as follows:
fn:floor( UNIT_PRICE * 10 )
max
The max XQuery function is used to find the maximum value in a sequence of atomic values.
Syntax
fn:max(arg, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The sequence of values.
collation
Optional
A string used to specify the collation for string comparisons. It defines how string comparison is performed. If not provided, the default collation applies. This parameter is relevant when comparing strings.
Return Value
•The function returns the maximum value from the input sequence.
•If the sequence is empty, the function returns an empty sequence.
•If the sequence contains more than one maximum value, the first occurrence is returned.
•If the sequence contains values with mixed data types, an error occurs.
•NULL if all values passed to the function are NULL.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:max( (2, 1, 5, 4, 3) )
5
fn:max( ('a', 'b', 'c') )
c
fn:max( (xs:date('1999-04-15'), current-date()) )
Current date
fn:max( 2 )
2
fn:max( () )
()
min
Selects an item from the input sequence argument whose value is less than or equal to the value of every other item in the input sequence. If there are two or more such items, then the specific item whose value is returned is implementation dependent.
Syntax
fn:min(arg, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The sequence of values.
collation
Required
The collation to use for comparing strings.
Return Value
xs:anyAtomicType?
NULL if all values passed to the function are NULL, or if no rows are selected (for example, the filter condition evaluates to FALSE or NULL for all rows).
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:min( (2.0, 1, 3.5, 4) )
1
fn:min( ('a', 'b', 'c') )
a
round
Returns the number with no fractional part that is closest to the argument. If there are two such numbers, the one that is closest to positive infinity is returned. If type of argument is one of the four numeric types xs:float, xs:double, xs:decimal, or xs:integer, the type of the result is the same as the type of argument. If the type of argument is a type derived from one of the numeric types, the result is an instance of the base numeric type.
Syntax
fn:round(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Numeric datatype. Returns the number with no fractional part that is closest to the argument. You can enter any valid expression.
Return Value
•Numeric value.
•If one of the arguments is NULL, ROUND returns NULL.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:round(5)
5
fn:round(5.1)
5
fn:round(5.5)
6
fn:round(-5.5)
-5
fn:round(-5.51)
-6
round-half-to-even
The value returned is the numerically closest value to $arg that is a multiple of ten to the power of minus $precision. If two such values are equally near, for example, if the fractional part in $arg is exactly .500..., the function returns the one whose least significant digit is even.
Syntax
fn:round-half-to-even(arg, precision)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The number to round.
precision
Required
The precision to round the number to. It can be a positive or negative integer.
Return Value
•Numeric value.
•The returned value is rounded to the number of decimal places indicated by $precision. For example, if the precision specified is 2, the function rounds 594.3271 to 594.33. If the precision is 0, the number is rounded to an integer. Specifying a negative precision results in the number being rounded to the left of the decimal point. For example, if $precision is -2, the function rounds 594.3271 to 600. If $precision is omitted, it defaults to 0.
•If the argument is exactly half way between two values, it is rounded to whichever adjacent value is even.
•The result type depends the numeric type of the argument. If $arg is untyped, it is cast to xs:double.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:round-half-to-even(5.5)
6
fn:round-half-to-even(6.5)
6
fn:round-half-to-even(9372.253, 2)
9372.25
fn:round-half-to-even(9372.253, 0)
9372
fn:round-half-to-even(9372.253, -3)
9000
sum
Returns a value obtained by adding together the values in $arg.
Syntax
fn:sum(arg, zero)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Numeric data type. Passes the values you want to add. You can enter any valid transformation expression. You can use operators to add values in different fields.
zero
Required
The return condition for an empty sequence. If $zero is not specified, the value returned for an empty sequence is the xs:integer value 0. If $zero is specified, the value returned for an empty sequence is $zero.
Return Value
•Numeric value.
•NULL if all values passed to the function are NULL.
•The $zero argument allows you to specify an alternate value for the sum of the empty sequence. If $arg is the empty sequence, and $zero is provided, the function returns $zero. The $zero argument could be the empty sequence, the integer 0, the value NaN, a duration of zero seconds, or any other atomic value.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:sum( (1, 2, 3) )
6
fn:sum( (1, 2, 3, () ) )
6
fn:sum( () )
0
fn:sum( (), () )
()
The following expression returns the sum of all values greater than 2000 in the Sales field:
sum( SALES, SALES > 2000 )
SALES
2500.0
1900.0
1200.0
NULL
3458.0
4519.0
RETURN VALUE: 10477.0
Tip
You can perform arithmetic on the values passed to sum before the function calculates the total. For example:
sum( QTY * PRICE - DISCOUNT )
Sequences functions
The following functions are available in the Sequences section of the Expression Editor:
count
The count function in XQuery is used to determine the number of items in a sequence.
Syntax
fn:count(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The sequence of items to count.
Return Value
•The function returns an xs:integer representing the number of items in the sequence.
•The count() function operates on sequences, including numbers, strings, and XML nodes.
•If the input sequence is empty, it returns 0.
•If all values passed to this function are NULL, it returns 0.
•It does not count individual characters within a string, only top-level sequence items.
Examples
If you have an XML document containing a list of books and you want to count how many books are listed:
let $books := doc("library.xml")/library/book return fn:count($books)
The output is 3.
The following table lists some additional sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:count( (1, 2, 3) )
3
fn:count( (1, 2, 3, () ) )
3
fn:count( (1, 2, 3, 1, 2 ) )
5
fn:count( () )
0
distinct-values
The distinct-values function in XQuery returns a sequence containing only the distinct atomic values from the provided sequence, effectively removing any duplicates.
Syntax
fn:distinct-values(arg, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The sequence of atomic values.
collation
Optional
The collation to use for comparing strings.
Return Value
Returns a sequence where duplicate values in $arg have been removed, keeping only one instance for each set of values that are equal (eq) to each other. Values of type xs:untypedAtomic are treated as xs:string for comparison purposes. If values cannot be compared because the eq operator is not defined for their types, these values are treated as distinct. The order of the returned sequence may vary depending on the implementation.
Examples
Consider the following XML sample:
let $in-xml := <in-xml> <a>3</a> <b>5</b> <b>3</b> </in-xml>
The following table lists some sample values and return values based on the above snippet:
The index-of function in XQuery is used to find the positions of items in a sequence that are equal to a given search item. It returns a sequence of positions where the specified item occurs.
Syntax
fn:index-of(seqParam, srchParam, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
seqParam
Required
The sequence of atomic values to be searched. This sequence can include strings, numbers, and booleans.
srchParam
Optional
The item for which you want to find the index positions within $seqParam.
collation
Optional
A string specifying the collation to use when comparing strings, if required. If omitted, the default collation is used.
Return Value
Returns a sequence of positive integers giving the positions within the sequence $seqParam of items that are equal to $srchParam. If no matches are found, it returns an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:index-of( ('a', 'b', 'c'), 'a')
1
fn:index-of( ('a', 'b', 'c'), 'd')
()
fn:index-of( (4, 5, 6, 4), 4)
(1, 4)
fn:index-of( (4, 5, 6, 4), 04.0)
(1, 4)
fn:index-of( ('a', 5, 6), 'a')
1
fn:index-of( (), 'a')
()
fn:index-of( (<a>1</a>, <b>1</b>), <c>1</c> )
(1, 2)
insert-before
The insert-before function in XQuery is used to insert items into a sequence at a specified position. This function allows the modification of sequences by adding elements before a designated index.
Syntax
fn:insert-before(target, position, inserts)
The following table describes the argument for this command:
Argument
Required/Optional
Description
target
Required
The sequence into which new items will be inserted.
position
Optional
The position in the $target sequence before which the items in $inserts should be inserted. Positions are 1-based. If the position is less than 1, the items are inserted at the beginning of the sequence; if the position is greater than the length of the sequence, the items are appended to the end.
inserts
Required
The sequence of items to be inserted into the $target sequence.
Return Value
The fn:insert-before function returns a copy of the $target sequence with the item(s) in $inserts inserted at the position indicated by $position. Position numbers start at 1, not 0.
Examples
The following table lists some sample values and return values:
The last function in XQuery is used to determine the position number of the last item in the current context node list during the evaluation of an expression. It is particularly useful within XPath expressions and FLWOR loops to determine the size or to operate on the last item of a sequence.
Syntax
fn:last()
The last function does not take any parameters. It operates within a context, usually within XPath expressions or FLWOR (For, Let, Where, Order by, Return) expressions.
Return Value
Returns the context size from the dynamic context.
It returns the integer position of the last item in the current context sequence. If you are iterating over a sequence, last() provides the total number of items in that sequence.
Examples
The following table lists some sample queries and return values:
SAMPLE FUNCTION
OUTPUT
let $doc := <items> <item>Apple</item> <item>Banana</item> <item>Cherry</item> </items> (: Select the last <item> :) let $lastItem := $doc/item[position() = fn:last()] (: Select all but the last <item> :) let $allButLast := $doc/item[position() lt fn:last()] return <results> <last-item>{$lastItem/text()}</last-item> <all-but-last>{ $allButLast/text() }</all-but-last> </results>
The position function in XQuery is used to determine the current position number of an item during the iteration over a sequence.
Syntax
fn:position()
The position function does not require any parameters. It operates within the context of a sequence, typically used in iterative expressions like FLWOR loops.
Return Value
Returns the context position from the dynamic context. It returns an integer representing the position starting with 1, not 0, of the current context item within the context sequence.
Examples
The following table lists some sample queries and return values:
SAMPLE FUNCTION
OUTPUT
let $doc := <items> <item>Apple</item> <item>Banana</item> <item>Cherry</item> </items> (: Select the last <item> :) let $lastItem := $doc/item[position() = fn:last()] (: Select all but the last <item> :) let $allButLast := $doc/item[position() lt fn:last()] return <results> <last-item>{$lastItem/text()}</last-item> <all-but-last>{ $allButLast/text() }</all-but-last> </results>
The remove function in XQuery is used to eliminate an item from a sequence located at a specified position. This function helps in restructuring sequences by removing items without altering the rest.
Syntax
fn:remove(target, position)
The following table describes the argument for this command:
Argument
Required/Optional
Description
target
Required
The sequence from which an item will be removed.
position
Optional
The position of the item in the sequence that should be removed. If $pos is less than 1 or greater than the number of items in the sequence, the sequence remains unchanged.
Return Value
Returns a sequence that includes all the items except for the one at the specified position. If the position is out of range, it returns the original sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:remove( ('a', 'b', 'c'), 2)
('a', 'c')
fn:remove( ('a', 'b', 'c'), 10)
('a', 'b', 'c')
fn:remove( ('a', 'b', 'c'), 0)
('a', 'b', 'c')
reverse
Reverses the order of items in a sequence.
Syntax
fn:reverse(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
Any character value. Value you want to reverse.
Return Value
String. Reverse of the input value. If $arg is the empty sequence, the empty sequence is returned.
Example
The following expression reverses the numbers of the customer code:
fn:reverse( CUSTOMER_CODE )
CUSTOMER_CODE
RETURN VALUE
0001
1
0002
2
0003
3
0004
4
(())
()
subsequence
The subsequence function in XQuery is designed to retrieve a specific portion of a sequence based on a starting location and an optional length. It allows extracting parts of a sequence efficiently, focusing only on the desired segment.
Syntax
fn:subsequence(sourceSeq, startingLoc, length)
The following table describes the argument for this command:
Argument
Required/Optional
Description
sourceSeq
Required
The input sequence from which a subsequence will be extracted.
startingLoc
Optional
The 1-based position within $sourceSeq where the subsequence starts. Non-integer values are rounded to the nearest integer. If $startingLoc is less than 1, it adjusts appropriately to start from the beginning of the sequence.
length
Optional
The number of items to include in the subsequence. Non-integer values are rounded to the nearest integer. If not specified or if the value is such that the subsequence extends beyond the end of $sourceSeq, all remaining items are included.
Return Value
•Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.
•If $startingLoc is beyond the end of the sequence or $length is 0 or negative, it returns an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:subsequence( ('a', 'b', 'c', 'd', 'e'), 3)
('c', 'd', 'e')
fn:subsequence( ('a', 'b', 'c', 'd', 'e'), 3, 2)
('c', 'd')
fn:subsequence( ('a', 'b', 'c', 'd', 'e'), 3, 10)
('c', 'd', 'e')
fn:subsequence( ('a', 'b', 'c', 'd', 'e'), 10)
()
fn:subsequence( ('a', 'b', 'c', 'd', 'e'), -2, 5)
('a', 'b')
fn:subsequence( (), 3)
()
fn:subsequence((5, 10, 15, 20), 2.5, 2.6)
15, 20
unordered
The unordered function in XQuery is used to indicate that the order of items in a sequence does not matter for a particular operation. It informs the query engine to ignore the order, potentially optimizing performance, especially in parallel processing scenarios.
Syntax
fn:unordered(sourceSeq)
The following table describes the argument for this command:
Argument
Required/Optional
Description
sourceSeq
Required
The sequence of items whose order is deemed unimportant. This sequence can contain any kind of items, including nodes, elements, and atomic values.
Return Value
Returns the same sequence of items as $sourceSeq, but the order of the items might change during query evaluation. The specific returned order is implementation-dependent and might vary.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:unordered((3, 1, 4, 1, 5, 9))
3, 1, 4, 1, 5, 9
fn:unordered(("a", "o", "b", "g"))
a, o, b, g
Strings functions
The following functions are available in the Strings section of the Expression Editor:
codepoint-equal
The codepoint-equal function in XQuery is used to compare two strings to determine if they are equal based on their Unicode code points. It checks if two strings are identical without considering any advanced collation rules.
Syntax
fn:codepoint-equal(comparand1, comparand2)
The following table describes the argument for this command:
Argument
Required/Optional
Description
comparand1
Required
The first string to compare. It can be an actual string or an empty sequence (()).
comparand2
Required
The second string to compare. It can also be an actual string or an empty sequence (()).
Return Value
•Boolean.
•Returns true or false depending on whether the value of $comparand1 is equal to the value of $comparand2, according to the Unicode code point collation.
•Returns an empty sequence if either input is an empty sequence.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:codepoint-equal('abc', 'abc')
true
fn:codepoint-equal('abc', 'ab c')
false
fn:codepoint-equal('abc', ())
()
fn:codepoint-equal((), ())
()
fn:codepoint-equal("hello", "world")
false
fn:codepoint-equal("hello", "")
false
codepoints-to-string
The codepoints-to-string function in XQuery is used to construct a string from a sequence of Unicode code points. This function takes numeric representations of characters and converts them into a string.
Syntax
fn:codepoints-to-string(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
A sequence of integers representing Unicode code points. Each integer corresponds to a Unicode code point that is converted into the respective character in the resulting string.
Return Value
•Returns a string formed by converting each code point in the input sequence to its corresponding character. If empty-sequence() is provided, it returns an empty string.
•If any of the code points in $arg is not a legal XML character, an error occurs.
Examples
The following table lists some sample values and return values:
The compare function in XQuery is used to compare two strings using a specified collation. This function can help determine the order of strings, for example, sorting based on a defined collation.
Syntax
fn:compare(comparand1, comparand2, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
comparand1
Required
The first string to be compared. This can be a valid string or empty-sequence().
comparand2
Required
The second string to be compared. This can also be a valid string or empty-sequence().
collation
Optional
A string that specifies the collation URI to be used for the comparison. If omitted, the default collation is used. The collation affects how string comparison is done, taking locale-specific rules into account.
Return Value
•Returns a negative integer if $comparand1 is less than $comparand2.
•Returns zero if the strings are equal.
•Returns a positive integer if $comparand1 is greater than $comparand2.
•Returns empty-sequence() if either input is empty-sequence().
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:compare('a', 'b')
-1
fn:compare('a', 'a')
0
fn:compare('b', 'a')
1
fn:compare('ab', 'abc')
-1
fn:compare('a', 'B')
1
This shows that when using the simple code point collation, a lowercase a comes after an uppercase B.
fn:compare(upper-case('a'), upper-case('B'))
-1
fn:compare('a', ())
()
fn:compare('a', 'b', 'FOO')
Error FOCH0002
fn:compare((), ())
()
concat
The concat function in XQuery is used to concatenate two or more strings into a single string. This function allows you to effectively combine multiple string values into one continuous string.
Syntax
fn:concat(arg1, arg2)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The first value to concatenate.
arg2
Required
The second value to concatenate.
Return Value
•Returns a single xs:string composed of the concatenated string representations of the provided arguments.
•If any of the arguments is the empty sequence, the argument is treated as the zero-length string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:concat('a')
Error XPST0017
fn:concat('a', 'b')
ab
fn:concat('a', 'b', 'c')
abc
fn:concat('a', (), 'b', '', 'c')
abc
fn:concat( ('a', 'b', 'c') )
Error XPST0017
fn:concat('a', <x>b</x>, 'c')
abc
fn:concat("Hello, ", "World", "!")
"Hello, World!"
fn:concat("Result: ", 42)
"Result: 42"
fn:concat("Start-", (), "End")
"Start-End"
contains
The contains function in XQuery is used to determine whether one string contains another substring. This function determines if the main string contains at least one occurrence of the specified substring. It evaluates to a boolean value indicating the presence or absence of a substring within a larger string.
Syntax
fn:contains(arg1, arg2, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The main string to check for the presence of another substring. If it is empty-sequence(), it is treated as an empty string.
arg2
Required
The substring to find within $arg1. This is the substring you are searching for. If it is empty-sequence(), it is treated as an empty string.
collation
Optional
A URI that specifies the collation to be used when comparing strings. Collations define locale-specific rules for string comparison. If omitted, the default collation is used.
Return Value
•Returns a boolean value indicating whether at least one sequence of collation units in $arg1 minimally matches the collation units in $arg2, including matches at the beginning or end, as determined by the specified or default collation.
•Returns true if $arg2 is found within $arg1.
•Returns false if $arg2 is not found within $arg1.
•Returns false if either $arg1 or $arg2 is the empty sequence ().
•If $collation is provided, the substring search uses the specified collation rules.
•If invalid collation URI is provided, an error is raised.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:contains('query', 'e')
true
fn:contains('query', 'ery')
true
fn:contains('query', 'query')
true
fn:contains("Hello", "hel")
false
fn:contains('query', 'x')
false
fn:contains('query', '')
true
fn:contains('query', ())
true
fn:contains( (), 'q')
false
Additional Notes
•Case-sensitive by default unless a case-insensitive collation is specified.
•Used to filter XML nodes containing a substring inside element text or attribute values.
•Optional collation supports linguistic comparisons and internationalization.
The concept of default-collation is not a direct function in XQuery but rather a setting or property that can affect XQuery expressions, particularly those dealing with collation-sensitive operations such as string comparisons. XQuery relies on this default collation to perform operations, such as sorting and comparing strings when a specific collation is not provided.
Syntax
fn:default-collation()
Return Value
Returns the default collation that is used in most operations where a collation is not explicitly specified. If no default collation is specified in the query prolog, the function returns the system default collation. If no system default collation is defined, the function returns a value representing the Unicode code point collation.
Example
The following expression represents the sample value and return value:
For example, if that is the name of the default collation.
ends-with
The ends-with function in XQuery is used to determine whether a string ends with a specified substring. It is a useful function for string manipulation and validation tasks.
Syntax
fn:ends-with(arg1, arg2, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The main string to be checked. This is the string you want to analyze to see if it ends with $arg2. If it is an empty-sequence(), it is treated as an empty string.
arg2
Required
The substring to compare against the end of $arg1. If it is an empty-sequence(), it is treated as an empty string.
collation
A URI that specifies the collation to be used when comparing strings. Collations define locale-specific rules for comparing characters. The default collation is used if this parameter is omitted.
Return Value
•Returns a boolean value indicating whether one string ($arg1) ends with the characters of a second string ($arg2).
•Returns true if $arg1 ends with $arg2.
•Returns false if it does not.
Examples
The following table lists some sample values and return values:
Assume "http://example.com/collation" supports specific comparison rules. The output would depend on whether the specified collation affects the treatment of accents or other features, possibly returning true.
lang
The lang function in XQuery is used to determine whether a node's language attribute matches a specified language. This function is particularly useful for querying XML documents that use language attributes to manage multilingual content.
Syntax
fn:lang(testlang, node)
The following table describes the argument for this command:
Argument
Required/Optional
Description
testlang
Required
The language tag to test against the xml:lang attribute of the node. It typically follows language tagging conventions, such as "en", "fr", and "en-US". This parameter must be provided as a string.
node
Required
The context node whose language attribute is to be tested. If omitted, the context item from which the function is called is used by default.
Return Value
•Returns true if the xml:lang attribute of the node or its nearest ancestor matches the $testlang value.
•Returns false if there is no match or if xml:lang is absent.
Examples
The following table lists some sample XML structures, queries, and return values:
<book xml:lang="fr"> <title>Bonjour le Monde</title> </book
fn:lang("en", /book/title)
false
<article xml:lang="en-US"> <section> <para>This is a paragraph.</para> </section> </article>
fn:lang("en-US")
true
<document> <content>Some text here.</content> </document>
fn:lang("en", /document/content)
false
lower-case
The lower-case function in XQuery is used to convert all the characters in a string to lowercase. This function is useful for tasks where case-insensitivity is required, such as searching, sorting, or normalizing textual data.
Syntax
fn:lower-case(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The string to be converted to lowercase. If the argument is an empty sequence (()), it is treated as an empty string.
Return Value
Returns a string where all the alphabetic characters in the input string have been converted to lowercase. Characters that are not alphabetic, such as numbers and punctuation remain unchanged.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:lower-case('QUERY')
query
fn:lower-case('Query')
query
fn:lower-case('query')
query
fn:lower-case('QUERY123')
query123
fn:lower-case("Hello World!")
"hello world!"
fn:lower-case("")
""
fn:lower-case("1234!@#$")
"1234!@#$"
matches
The matches function in XQuery is used to determine whether a string matches a given regular expression pattern. This function is essential for pattern matching and text validation tasks.
Syntax
fn:matches(input, pattern, flags)
The following table describes the argument for this command:
Argument
Required/Optional
Description
input
Required
The input string to be tested against the pattern. If this argument is an empty sequence (()), it is treated as an empty string.
pattern
Required
A regular expression pattern against which the input string is matched. The pattern should be a valid regular expression according to the XML Schema definition.
flags
Optional
A string of flags that modify the matching behavior as follows:
- m: Multi-line mode, where the start and end of line anchors (^ and $) match the start and end of any line instead of the entire string.
- s: Single-line mode, where the dot (.) matches all characters, including line terminators.
- i: Case-insensitive matching.
Return Value
Returns true if $input matches the regular expression supplied as $pattern as influenced by the value of $flags, if present. Otherwise, returns false .
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:matches('query', 'q')
true
fn:matches('query', 'ue')
true
fn:matches('query', '^qu')
true
fn:matches('query', 'qu$')
false
fn:matches('query', 'q.*')
true
fn:matches('query', '[a-z]{5}')
true
fn:matches((), 'q' )
false
fn:matches('query', '[qu')
Error FORX0002
fn:matches("Hello World", "World")
true
fn:matches("Hello World", "^World")
false
fn:matches("Hello World", "hello", "i")
true
fn:matches((), "^$")
true
normalize-space
The normalize-space function in XQuery removes leading and trailing whitespace from a string and replaces sequences of whitespace characters within the string with a single space. This function is useful for cleaning up and formatting text data.
Syntax
fn:normalize-space(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The input string whose spaces need to be normalized. If this argument is omitted, the function operates on the context item typically the current node or string in the query. If the argument is an empty sequence (()), it is treated as an empty string.
Return Value
•Returns the value of $arg with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of one or more than one whitespace character with a single space, #x20.
•If the input is an empty sequence, it returns an empty string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:normalize-space('query')
query
fn:normalize-space(' query ')
query
fn:normalize-space('xml query')
xml query
fn:normalize-space('xml query')
xml query
fn:normalize-space('xml query')
xml query
fn:normalize-space('')
zero-length string
fn:normalize-space(' ')
zero-length string
fn:normalize-space(())
zero-length string
fn:normalize-space( <element> query </element>)
query
fn:normalize-space("CleanString")
CleanString
fn:normalize-space("Line1\n\tLine2\t Line3")
Line1\\n\\tLine2\\t Line3
normalize-unicode
The normalize-unicode function in XQuery performs Unicode normalization, that allows text to be compared without regard to subtle variations in character representation. It replaces certain characters with equivalent representations. Two normalized values can then be compared to determine whether they are the same. Unicode normalization is also useful for allowing character strings to be sorted appropriately.
The $normalizationForm argument controls which normalization form is used, and hence which characters are replaced.
Syntax
fn:normalize-unicode(arg, normalizationForm)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The input string to be normalized. If this argument is an empty sequence (()), it is treated as an empty string.
normalizationForm
Optional
The Unicode normalization form to apply. According to the Unicode Standard, the allowed forms are:
- "NFC": Canonical Composition
- "NFD": Canonical Decomposition
- "NFKC": Compatibility Composition
- "NFKD": Compatibility Decomposition
If omitted, "NFC" is the default form used.
Return Value
•Returns the normalized string according to the specified Unicode normalization form. The effective value of the $normalizationForm is computed by removing leading and trailing blanks, if present, and converting to upper case.
•If the input is an empty sequence, it returns an empty string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:normalize-unicode('query')
query
fn:normalize-unicode('query', '')
query
fn:normalize-unicode('￡', 'NFKC')
£
Converts ￡ to £.
fn:normalize-unicode('leçon', 'NFKD')
leçon
Converts leçon to leçon. There are two characters in the output, a "c" and a separate cedilla, but it might not be visible separately in your browser.
fn:normalize-unicode('15 ㎗')
15 ㎗
fn:normalize-unicode('15 ㎗', 'NFKC')
15 dl
Converts ㎗ to the letters 'dl'.
replace
The replace function in XQuery is used to replace parts of a string that match a specified regular expression with a replacement string. This function is highly useful for string manipulation tasks such as text sanitation, formatting, and transformation.
Syntax
fn:replace(input, pattern, replacement, flags)
The following table describes the argument for this command:
Argument
Required/Optional
Description
input
Required
The input string to be processed. If this argument is an empty sequence (()), it is treated as an empty string.
pattern
Required
A regular expression pattern that specifies what part of the input string to replace. The pattern must be a valid regular expression.
replacement
Required
The string that will replace each substring of the input string that matches the regular expression pattern. Special replacement strings, such as $1, can be used to refer to captured groups within the pattern.
flags
A string of flags that modify the behavior of the regular expression as follows:
- s: Single-line mode, where the dot (.) matches all characters, including newline.
- m: Multi-line mode, where start ^ and end $ anchors match the start and end of any line.
- i: Case-insensitive mode.
Return Value
•Returns the xs:string that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern with an occurrence of the $replacement string.
•If no portions match, the original string is returned unchanged.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:replace('query', 'r', 'as')
queasy
fn:replace('query', 'qu', 'quack')
quackery
fn:replace('query', '[ry]', 'l')
quell
fn:replace('query', '[ry]+', 'l')
quel
fn:replace('query', 'z', 'a')
query
fn:replace('query', 'query', '')
zero-length string
fn:replace( (), 'r', 'as')
zero-length string
fn:replace('query', 'r?', 'as')
Error FORX0003
fn:replace('query', '(r', 'as')
Error FORX0002
fn:replace('Chapter', '(Chap)|(Chapter)', 'x')
xter
The following examples show the difference between reluctant and regular quantifiers:
SAMPLE FUNCTION
OUTPUT
fn:replace('reluctant', 'r.*t', 'X')
X
fn:replace('reluctant', 'r.*?t', 'X')
Xant
fn:replace('aaah', 'a{2,3}', 'X')
Xh
fn:replace('aaah', 'a{2,3}?', 'X')
Xah
fn:replace('aaaah', 'a{2,3}', 'X')
Xah
fn:replace('aaaah', 'a{2,3}?', 'X')
XXh
The following examples exhibit the use of sub-expressions:
The starts-with function in XQuery is used to determine whether a string begins with a specified substring. This function is particularly useful for string validation and prefix matching tasks.
Syntax
fn:starts-with(arg1, arg2, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The main string to be checked. This is the string you want to determine if it starts with $arg2. If it is an empty sequence (()), it is treated as an empty string.
arg2
Required
The substring to check for at the start of $arg1. If this argument is an empty sequence, it is treated as an empty string.
collation
Optional
A URI that specifies the collation to be used for string comparison. Collations are sets of rules for comparing characters in strings. If this parameter is omitted, the default collation is used.
Return Value
•Returns a boolean indicating whether or not the value of $arg1 starts with a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.
•Returns true if the main string $arg1 starts with the substring $arg2.
•Returns false if it does not.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:starts-with('query', 'que')
true
fn:starts-with('query', 'query')
true
fn:starts-with('query', 'u')
false
fn:starts-with('query', '')
true
fn:starts-with('', 'query')
false
fn:starts-with('', '')
true
fn:starts-with('query', ())
true
fn:starts-with(' query', 'q')
false
fn:starts-with("Query", "que")
false
string-join
The string-join function in XQuery is used to concatenate a sequence of strings into a single string, with a specified separator between each. This function is particularly useful for combining strings into a formatted output.
Syntax
fn:string-join(arg1, arg2)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
A sequence of strings to be joined. Each item in the sequence is joined together in the order they appear. If the sequence is empty, the function returns an empty string.
arg2
Required
The string to insert between adjacent items in the sequence. This separator is appended between each pair of strings in the sequence.
Return Value
•Returns a string created by concatenating the members of the $arg1 sequence using $arg2 as a separator.
•If the value of $arg2 is the zero-length string, the members of $arg1 are concatenated without a separator.
•If the sequence is empty, it returns an empty string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:string-join( ('a', 'b', 'c'), '')
abc
fn:string-join( ('a', 'b', 'c'), '/*')
a/*b/*c
fn:string-join( ('a', '', 'c'), '/*')
a/*/*c
fn:string-join( 'a', '/*')
a
fn:string-join((), '/*')
zero-length string
fn:string-join(("Line1", "Line2", "Line3"), "\n")
"Line1 Line2 Line3"
string-length
The string-length function in XQuery is used to determine the number of characters in a given string including the leading and trailing whitespace characters. It is particularly useful for tasks that require string validation or manipulation, where the size of the string is relevant.
Syntax
fn:string-length(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The input string whose length you want to determine. If the argument is omitted, the function defaults to using the context item; if the context item is not a string, a type error is raised. If the argument is an empty sequence (()), it is treated as an empty string.
Return Value
Returns an integer equal to the length in characters of the value of $arg. For an empty string or empty sequence, it returns 0.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:string-length('query')
5
fn:string-length(' query ')
9
fn:string-length(normalize-space(' query '))
5
fn:string-length('xml query')
9
fn:string-length('')
0
fn:string-length(())
0
fn:string-length("Hello, World!")
13
fn:string-length(" \t")
4
string-to-codepoints
The string-to-codepoints function in XQuery is used to convert a string into a sequence of Unicode codepoints. This function provides a way to analyze and manipulate the individual characters embedded within a string at their fundamental encoding level.
Syntax
fn:string-to-codepoints(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The input string to be converted into Unicode codepoints. If the argument is an empty sequence (()), it is treated as an empty string.
Return Value
•Returns a sequence of integers representing the Unicode codepoints of each character in the input string.
•If the input string is empty or an empty sequence, the function returns an empty sequence.
Examples
The following table lists some sample values and return values:
The substring function in XQuery extracts a portion of a string based on specified start and optional length parameters. It is useful for string manipulation tasks where specific parts of a string need to be isolated and processed.
Syntax
fn:substring(sourceString, startingLoc, length)
The following table describes the argument for this command:
Argument
Required/Optional
Description
sourceString
Required
The string from which the substring will be extracted. If the argument is an empty sequence (()), it is treated as an empty string.
startingLoc
Required
The position within the source string where the substring begins. Position indexing starts at 1. If this number is less than 1, the start is considered from the first character.
length
Optional
The number of characters to include in the substring. If omitted, the substring extends to the end of the source string.
Return Value
•Returns the portion of the value of $sourceString beginning at the position indicated by the value of $startingLoc and continuing for the number of characters indicated by the value of $length. The characters returned do not extend beyond $sourceString.
•If $startingLoc is zero or negative, only those characters in positions greater than zero are returned.
•If the start position is beyond the end of the string, it returns an empty string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:substring('query', 1)
query
fn:substring('query', 3)
ery
fn:substring('query', 1, 1)
q
fn:substring('query', 2, 3)
uer
fn:substring('query', 2, 850)
uery
fn:substring('query', 6, 2)
zero-length string
fn:substring('query', -2)
query
fn:substring('query', -2, 5)
qu
fn:substring('query', 1, 0)
zero-length string
fn:substring('', 1)
zero-length string
fn:substring((), 1)
zero-length string
fn:substring("Example", 0)
"Example"
fn:substring("Short", 10)
""
substring-after
The substring-after function in XQuery returns the part of a string that follows a specified substring. It is useful for extracting text that appears after a certain character or sequence in a given string.
Syntax
fn:substring-after(arg1, arg2, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The input string from which the substring will be extracted. If the argument is an empty sequence (()), it is treated as an empty string.
arg2
Required
The substring to search for within $arg1. The function returns the portion of $arg1 that follows the first occurrence of $arg2. If $arg2 is an empty sequence, it is treated as an empty string.
collation
Required
The collation to use to compare strings
Return Value
•Returns the substring of $arg1 that appears immediately after $arg2.
•If $arg2 is not found within $arg1, the function returns an empty string.
•If $arg2 is an empty string, the entire $arg1 is returned.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:substring-after('query', 'u')
ery
fn:substring-after('queryquery', 'ue')
ryquery
fn:substring-after('query', 'y')
zero-length string
fn:substring-after('query', 'x')
zero-length string
fn:substring-after('query', '')
query
fn:substring-after('', 'x')
zero-length string
fn:substring-after("Hello, World!", ", ")
"World!"
substring-before
The substring-before function in XQuery returns the part of a string that appears before a specified substring. This function is useful for extracting text that precedes a certain character or sequence in a given string.
Syntax
fn:substring-before(arg1, arg2, collation)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg1
Required
The input string from which the substring will be extracted. If this argument is an empty sequence (()), it is treated as an empty string.
arg2
Required
The substring to search for within $arg1. The function returns the portion of $arg1 that occurs before the first occurrence of $arg2. If $arg2 is an empty sequence, it is treated as an empty string.
collation
Required
The collation to use to compare strings
Return Value
•Returns the substring of $arg1 that appears immediately before $arg2.
•If $arg2 is not found within $arg1, the function returns an empty string.
•If $arg2 is an empty string, an empty string is returned since there's nothing to find before.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:substring-before('query', 'r')
que
fn:substring-before('query', 'ery')
qu
fn:substring-before('queryquery', 'ery')
qu
fn:substring-before('query', 'query')
zero-length string
fn:substring-before('query', 'x')
zero-length string
fn:substring-before('query', '')
zero-length string
fn:substring-before('query', ())
zero-length string
fn:substring-before("Hello, World!", ", ")
"Hello"
fn:substring-before("repeat", "repeat")
""
fn:substring-before("XQuery", "SQL")
""
tokenize
The tokenize function in XQuery is used to split a string into a sequence of substrings based on a specified regular expression pattern that serves as a delimiter. This function is particularly useful for parsing and separating components of a string for further processing.
Syntax
fn:tokenize(input, pattern, flags)
The following table describes the argument for this command:
Argument
Required/Optional
Description
input
Required
The input string to be tokenized. If this argument is an empty sequence (()), it is treated as an empty string.
pattern
Required
A regular expression pattern that specifies the delimiter by which the input string will be split. The pattern should be a valid regular expression according to the XML Schema definition.
flags
Optional
A string of flags that modify the behavior of the regular expression as follows:
- s: Single-line mode, where the dot (.) matches all characters, including newline.
- m: Multi-line mode, where start ^ and end $ anchors match the start and end of any line.
- i: Case-insensitive mode.
Return Value
Returns a sequence of strings obtained by partitioning the $input string at delimiters specified by the $pattern. If the input string is empty or the pattern does not find any matches, an empty sequence or the entire input string is returned as appropriate.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:tokenize( 'a b c', '\s')
('a', 'b', 'c')
fn:tokenize( 'a b c', '\s')
('a', '', '', 'b', 'c')
fn:tokenize( 'a b c', '\s+')
('a', 'b', 'c')
fn:tokenize( ' b c', '\s')
('', 'b', 'c')
fn:tokenize( 'a,b,c', ',')
('a', 'b', 'c')
fn:tokenize( 'a,b,,c', ',')
('a', 'b', '', 'c')
fn:tokenize( 'a, b, c', '[,\s]+')
('a', 'b', 'c')
fn:tokenize( '2006-12-25T12:15:00', '[\-T:]')
('2006', '12', '25', '12', '15', '00')
fn:tokenize( 'Hello, there.', '\W+')
('Hello', 'there', '')
fn:tokenize( (), '\s+')
()
fn:tokenize( 'abc', '\s')
abc
fn:tokenize( 'abcd', 'b?')
Error FORX0003
fn:tokenize( 'a,xb,xc', ',|,x')
('a', 'xb', 'xc')
fn:tokenize("", ",")
()
translate
The translate function in XQuery is used to replace characters in a string based on a specified mapping from source characters to target characters. This function is useful for simple character substitutions and deletions within strings.
Syntax
fn:translate(arg, mapString, transString)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The input string in which character replacements are to be made. If this argument is an empty sequence (()), it is treated as an empty string.
mapString
Required
A string containing characters to be replaced. Each character in mapString is mapped to the corresponding character in transString.
transString
Required
A string containing replacement characters. Each character in mapString is replaced by the character at the corresponding position in transString. If transString is shorter than mapString, characters with no corresponding replacement are removed from the input.
Return Value
Returns a string where each character in the input $src is replaced according to the mappings defined by $mapString and $transString. Characters in $src that are not in $mapString remain unchanged. If replacements result in removal, those characters are removed.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:translate('1999/01/02', '/', '-')
1999-01-02
fn:translate('xml query', 'qlmx', 'QLMX')
XML Query
fn:translate('xml query', 'qlmx ', 'Q')
Query
fn:translate('xml query', 'qlmx ', '')
uery
fn:translate('xml query', 'abcd', 'ABCD')
xml query
fn:translate('', 'qlmx ', 'Q')
zero-length string
fn:translate((), 'qlmx ', 'Q')
zero-length string
fn:translate("hello world", "hod", "jrx")
"jellr wxrlr"
fn:translate("12345", "9", "0")
"12345"
upper-case
The upper-case function in XQuery converts all the characters in a given string to their uppercase equivalents according to the Unicode standard. This function is helpful for normalizing text for comparison or display purposes.
Syntax
fn:upper-case(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The input string whose characters are to be converted to uppercase. If this argument is an empty sequence (()), it is treated as an empty string.
Return Value
•Returns a new string where all lowercase letters in the input string have been converted to uppercase.
•Non-alphabetic characters and characters that do not have an uppercase equivalent remain unchanged.
•If the input is an empty string, it returns an empty string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:upper-case('query')
QUERY
fn:upper-case('QUERY')
QUERY
fn:upper-case('Query')
QUERY
fn:upper-case('query-123')
QUERY-123
fn:upper-case("123abc!@#")
"123ABC!@#"
fn:upper-case("")
""
XML Documents, URIs and IDs
The following functions are available in the XML Documents, URIs and IDs section of the Expression Editor:
base-uri
The base-uri function in XQuery returns the base URI of the given node. The base URI is typically the URI against which relative URIs in the document should be resolved.
Syntax
fn:base-uri(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The node for which to retrieve the base URI. If omitted or empty, the context item is used.
Return Value
•Returns the base URI of the specified node as an xs:anyURI.
•Returns an empty sequence if the base URI is not available.
•Returns an error if no context item is available and no argument is provided.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:base-uri() (when context item is a node with base URI)
"http://example.com/doc.xml"
fn:base-uri(/root)
"http://example.com/doc.xml"
fn:base-uri(())
()
fn:base-uri() (with no context item)
Error
Additional information
•If the input node has no base URI, the function returns an empty sequence.
•The function can be called without arguments if a context node exists.
•Useful for resolving relative references in XML documents.
collection
The collection function in XQuery returns a sequence of nodes from a collection identified by a URI. It is used to access sets of XML documents or items stored in a collection, typically in an XQuery or XML database environment.
Syntax
fn:collection(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The URI identifying the collection to retrieve. If omitted or empty, the default collection for the static context is returned.
Return Value
•Returns a sequence of nodes/items from the specified collection.
•Returns an empty sequence if the collection is empty or the URI does not identify any collection.
•Returns the default collection if no argument is provided.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:collection("http://example.com/myCollection")
Sequence of nodes from the collection
fn:collection()
Sequence of nodes from default collection
fn:collection("")
Empty sequence
fn:collection("nonexistent")
Empty sequence
Additional information
•The exact behavior depends on the XQuery processor and environment. For example, XML database.
•The collection URI is often implementation-specific.
•Useful for querying multiple XML documents as a single data source.
doc
The doc function in XQuery retrieves a single XML document node identified by a URI. It is commonly used to load an XML document from a given URI into an XQuery expression for querying.
Syntax
fn:doc(uri)
The following table describes the argument for this command:
Argument
Required/Optional
Description
uri
Required
The URI identifying the XML document to retrieve.
Return Value
•Returns the document node of the XML document identified by the URI.
•Returns an empty sequence if no document is found at the specified URI.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:doc("http://example.com/sample.xml")
Document node of the specified XML
fn:doc("")
Empty sequence
fn:doc("nonexistent.xml")
Empty sequence
Additional information
•The behavior depends on the XQuery processor and the availability of the URI.
•The URI is often resolved relative to the base URI of the query.
•The function retrieves exactly one document; multiple documents are not returned.
doc-available
The doc-available function in XQuery checks whether a document identified by the given URI is available and can be retrieved without error.
Syntax
fn:doc-available(uri)
The following table describes the argument for this command:
Argument
Required/Optional
Description
uri
Required
The URI identifying the XML document to check.
Return Value
•Returns true if the document is available and can be successfully retrieved.
•Returns false if the document is not available, cannot be retrieved, or an error occurs during retrieval.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:doc-available("http://example.com/sample.xml")
true
fn:doc-available("nonexistent.xml")
false
fn:doc-available("")
false
Additional information
•Useful to safely check for document existence before attempting to retrieve it with doc().
•The function does not raise errors. It returns a boolean indicating availability.
•Behavior may depend on the underlying XQuery processor and access rights.
document-uri
The document-uri function in XQuery returns the document URI associated with a given document node. It helps identify the URI of the document from which the node originates.
Syntax
fn:document-uri(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
The document node whose document URI is to be retrieved.
Return Value
•Returns the URI of the document as an xs:anyURI.
•Returns an empty sequence if the input node is not a document node or if no URI is available.
•Returns an empty sequence for empty input.
Examples
The following table lists some sample values and return values:
•The parameter should be a document node, typically obtained from fn:doc() or similar functions.
•Useful for retrieving the source URI of a loaded document.
encode-for-uri
The encode-for-uri function in XQuery returns a string where characters in the input string that are not allowed in a URI component are percent-encoded according to RFC 3986. It is similar to URL encoding but tailored for URI components.
Syntax
fn:encode-for-uri(uri-part)
The following table describes the argument for this command:
Argument
Required/Optional
Description
uri-part
Required
The string to be encoded for use as a URI component.
Return Value
•Returns a string where characters not valid in a URI component are percent-encoded.
•Spaces and other special characters are encoded as %XX hexadecimal sequences.
•Does not return empty sequence. Input must be a string.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:encode-for-uri("a b+c/d")
"a%20b%2Bc%2Fd"
fn:encode-for-uri("name@example.com")
"name%40example.com"
fn:encode-for-uri("")
""
Additional information
•The function is useful for encoding string components to safely include them in URIs.
•Does not encode characters that are valid in URI components, such as letters, digits, hyphens, underscores, dots, and tildes.
•Always returns a string. It does not accept empty or non-string types.
escape-html-uri
The escape-html-uri function in XQuery returns a string that is safe to use within HTML URIs by escaping characters that have a special meaning in HTML, such as &, <, >, ", and ' with corresponding percent-encodings. This ensures the URI can be safely embedded in HTML attributes without breaking the markup.
Syntax
fn:escape-html-uri(uri)
The following table describes the argument for this command:
Argument
Required/Optional
Description
uri
Required
The URI string to be escaped for HTML usage.
Return Value
•Returns a string with characters that are special in HTML URI contexts replaced by percent-encoded equivalents.
•Ensures the URI string is safe for inclusion in HTML documents as part of a URI.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:escape-html-uri("foo<>\")
"foo%3C%3E%22"
fn:escape-html-uri("")
""
Additional information
•The function is specifically designed to escape URIs within HTML contexts where certain characters need escaping to avoid breaking HTML syntax.
•It only encodes characters that are significant in HTML URIs, different from general URI encoding.
•Always returns an xs:string.
id
The id function in XQuery returns a sequence of element nodes with unique IDs matching the specified ID value(s). It retrieves elements based on the values of their ID attributes, commonly used for referencing elements defined with xml:id or DTD ID attributes.
Syntax
fn:id(arg, node)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
One or more ID values (space-separated tokens) to locate matching elements.
node
Optional
The node that provides the context for resolving the IDs. Defaults to the root node of the context item if omitted.
Return Value
•Returns a sequence of element nodes whose IDs match any of the values in $arg.
•Returns an empty sequence if no matching IDs are found.
•Resolves ID values with respect to the $contextNode or context root node if $contextNode is omitted.
Additional information
•The ID attributes must be declared as type ID in the schema or DTD for ID resolution to work.
•The $arg string(s) can contain one or multiple whitespace-separated ID tokens.
•If the context node has no root or relevant attributes, the result may be empty.
idref
The idref function in XQuery returns the sequence of element or attribute nodes with an IDREF value matching the value of one or more of the ID values supplied in $arg .
Syntax
fn:idref(arg, node)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Required
One or more IDREF values (space-separated tokens) to find referencing elements.
node
Optional
The node that provides context for resolving IDREFs. Defaults to root node of the context item if omitted.
Return Value
•Returns a sequence of element nodes whose IDREF attributes contain any of the specified $arg values.
•Returns an empty sequence if no matching IDREFs are found.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:idref("item1", /root)
Elements that refer to the ID "item1" under /root.
fn:idref(("item1", "item2"))
Sequence of elements referring to "item1" or "item2".
fn:idref("nonexistent")
()
fn:idref("item1") (with context node omitted)
Elements referring to "item1" relative to context root node.
Additional information
•The IDREF attributes must be declared accordingly in the schema or DTD for IDREF resolution.
•The $arg can hold multiple space-separated reference values.
•The function depends on the context node or defaults to the root of the context item.
iri-to-uri
The iri-to-uri function in XQuery converts an Internationalized Resource Identifier (IRI) to a Uniform Resource Identifier (URI) by escaping characters that are not allowed in URIs according to RFC 3986. This process includes percent-encoding characters outside the ASCII range and certain reserved characters.
Syntax
fn:iri-to-uri(iri)
The following table describes the argument for this command:
Argument
Required/Optional
Description
iri
Required
The IRI string to be converted to a URI.
Return Value
•Returns a string representing the corresponding URI after encoding the IRI.
•Converts Unicode and other characters as needed into percent-encoded sequences.
•Always returns an xs:string.
Examples
The following table lists some sample values and return values:
•Primarily used to make IRIs safe for use where URIs are required.
•Escapes characters outside the ASCII range and reserved characters as per URI syntax rules.
•Does not take empty or non-string inputs.
resolve-uri
The resolve-uri function in XQuery resolves a given relative URI against a base URI, producing an absolute URI. If the first argument is already an absolute URI, it returns it directly. It is useful for combining relative paths with base locations.
Syntax
fn:resolve-uri(relative, base)
The following table describes the argument for this command:
Argument
Required/Optional
Description
relative
Required
The relative URI to be resolved. If absolute, it is returned unchanged.
base
Optional
The base URI against which to resolve the relative URI. If omitted, the base URI of the static context or empty sequence is used.
Return Value
•Returns an absolute URI (xs:anyURI) that results from resolving the relative URI against the base URI.
•Returns empty sequence if the relative URI is an empty sequence.
•Returns the relative URI as-is if it is already an absolute URI.
•Returns empty sequence or errors if the resolution cannot be determined.
Examples
The following table lists some sample values and return values:
•If $base is omitted, the function uses the base URI of the static context where the function is invoked.
•Useful for building full URIs in web or XML processing contexts.
static-base-uri
The static-base-uri function in XQuery returns the static base URI of the query or module in which it is called. This is the base URI that was statically assigned, often the location of the query file or module, and is used as the default base for resolving relative URIs in the query.
Syntax
fn:static-base-uri()
Return Value
•Returns an xs:anyURI representing the static base URI of the module or query.
•Returns an empty sequence if no static base URI is available. For example, in interactive sessions without a defined static base URI.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:static-base-uri()
"http://example.com/queries/myquery.xq"
fn:static-base-uri() (in an environment without static base URI)
()
Additional information
•The static base URI is generally set by the processor based on where the query or module is stored.
•It differs from base-uri() which is dynamic and context-dependent.
•Useful for resolving relative URIs in a stable, fixed way during query compilation or execution.
XML Namespaces and Names
The following functions are available in the XML Namespaces and Names section of the Expression Editor:
QName
The QName function in XQuery constructs a QName (Qualified Name) from a namespace URI and a local part (local name). It is used to create a QName value dynamically in XQuery.
Syntax
fn:QName(paramURI, paramQName)
The following table describes the argument for this command:
Argument
Required/Optional
Description
paramURI
Optional
The namespace URI part of the QName. It can be empty or "" if no namespace is desired.
paramQName
Required
The local part or the local name of the QName. It must be a valid non-colonized name (NCName).
Return Value
•Returns an xs:QName constructed from the provided namespace URI and local name.
•Raises an error if the local name is not a valid NCName.
•If the namespace URI is empty or "", the QName is in no namespace.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:QName("http://example.com/ns", "name")
QName("{http://example.com/ns}name")
fn:QName("", "name")
QName("name")
fn:QName((), "name")
QName("name")
fn:QName("http://example.com/ns", "1invalid")
Error
Additional information
•The $localName must conform to NCName syntax. Colons are not allowed.
•The function is useful when constructing QNames programmatically.
•It can be used where element or attribute names need to be dynamically generated.
in-scope-prefixes
The in-scope-prefixes function returns the sequence of namespace prefixes that are in scope for a given element node. This helps identify what namespace prefixes can be used for that element and its sub-elements.
Syntax
fn:in-scope-prefixes(element)
The following table describes the argument for this command:
Argument
Required/Optional
Description
element
Required
The element node whose in-scope prefixes are to be returned.
Return Value
•Returns a sequence of strings representing the namespace prefixes in scope for the given element.
•The sequence may contain the empty string "" representing the default namespace prefix.
•Returns an empty sequence if the argument is empty or not an element node.
Examples
The following table lists some sample values and return values:
Validation error. Empty sequence is not allowed as first argument to in-scope-prefixes function.
Additional information
•The empty string "" in the result denotes the default namespace prefix.
•The function only works with element nodes; other node types return empty.
•It reflects the namespaces visible due to declarations on the element or inherited from ancestors.
local-name
The local-name function in XQuery returns the local part (local name) of the expanded QName of the node provided as input. This excludes the namespace prefix and namespace URI.
Syntax
fn:local-name(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The node from which to extract the local name. If omitted or empty, the context item is used.
Return Value
•Returns the xs:string representing the local name of the input node's QName.
•Returns an empty string if the input is an empty sequence or the node does not have a name. For example, text nodes.
•Raises an error if no context item is provided and the argument is omitted.
Examples
The following table lists some sample values and return values:
fn:local-name() (with context node <ex:item> in scope)
"item"
Additional information
•The function works with element, attribute, processing-instruction, comment, or document nodes.
•For nodes without a QName, such as text or comment nodes. It returns an empty string.
•It optionally uses the context item if no argument is passed.
local-name-from-QName
The local-name-from-QName function in XQuery returns the local part of a QName value. It extracts only the local name without namespace prefix or URI from the given xs:QName.
Syntax
fn:local-name-from-QName(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The QName from which to extract the local name. If empty or omitted, returns an empty sequence.
Return Value
•Returns the xs:string representing the local name part of the QName.
•Returns an empty sequence if the input is empty or omitted.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:local-name-from-QName(QName("", "bar"))
"bar"
fn:local-name-from-QName(())
()
Additional information
•The input must be a valid QName.
•The function is complementary to fn:namespace-uri-from-QName() which returns the namespace part.
•It is useful when working with QName values where you need the local name alone.
name
The name function in XQuery returns the QName value of the node as a string, representing the element or attribute name including its prefix, if any. It returns the string-form of the node's name.
Syntax
fn:name(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The node whose name is to be returned. If omitted, the context item is used.
Return Value
•Returns the name of a node, as an xs:string that is either the zero-length string, or has the lexical form of an xs:QName .
•Returns a string representing the QName of the node, including namespace prefix if present.
•Returns an empty string if the node has no name, for example, text nodes, or the input is empty.
•Raises an error if no argument is provided and the context item is not a node.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:name(<a:book xmlns:a="http://example.com"/> )
"a:book"
fn:name(text{"Hello"})
""
fn:name(())
""
fn:name() (with context node <ex:item> in scope)
"ex:item"
Additional information
•The function works for element, attribute, processing-instruction, and namespace nodes.
•For nodes without names, such as text, comment, the return is an empty string.
•The prefix is included if present, unlike local-name().
namespace-uri
The namespace-uri function in XQuery returns the namespace URI of the expanded QName of the provided node. It helps retrieve the namespace part associated with elements or attributes.
Syntax
fn:namespace-uri(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The node whose namespace URI is to be retrieved. If omitted, the context item is used.
Return Value
•Returns the xs:anyURI representing the namespace URI of the node’s QName.
•Returns the empty string "" if the node has no namespace.
•Returns an empty sequence if the input is empty.
•Raises an error if no argument is provided and the context item is absent or not a node.
Examples
The following table lists some sample values and return values:
•Works with element, attribute, and processing instruction nodes.
•Returns the namespace URI even if a prefix is not explicitly present.
•It is useful for namespace-aware XML processing.
namespace-uri-for-prefix
The namespace-uri-for-prefix function in XQuery returns the namespace URI that is bound to a specific prefix in the context of a given element node. This is useful for determining what namespace a prefix corresponds to when processing XML.
Syntax
fn:namespace-uri-for-prefix(prefix, element)
The following table describes the argument for this command:
Argument
Required/Optional
Description
prefix
Required
The namespace prefix to be resolved. Use "" (empty string) for default namespace.
element
Optional
The element node whose namespace context is used for resolving the prefix. If omitted, the static context is used.
Return Value
•Returns the namespace URI (xs:anyURI) associated with the prefix in the scope of the element.
•Returns the empty sequence if the prefix is not bound to any namespace in the given element’s context.
•For the empty string prefix, returns the default namespace URI, if any.
•Returns empty sequence if no namespace binding is found.
Examples
The following table lists some sample values and return values:
•The function searches for namespace declarations beginning at the specified $element and then traverses upward through its ancestor nodes.
•It is especially useful for dynamic namespace resolution during XML processing.
•If the prefix is not declared, the function returns an empty sequence rather than an error.
namespace-uri-from-QName
The namespace-uri-from-QName function in XQuery returns the namespace URI part of a given QName value. This allows extracting the namespace URI component from an xs:QName.
Syntax
fn:namespace-uri-from-QName(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The QName from which to extract the namespace URI. Returns empty sequence if $arg is empty or omitted.
Return Value
•Returns the namespace URI for $arg as an xs:string.
•Returns the xs:anyURI representing the namespace URI of the QName argument.
•Returns the zero-length string is returned, if $arg is no namespace.
•Returns an empty sequence if the input is empty or omitted.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:namespace-uri-from-QName(QName("", "bar"))
"" (empty string)
fn:namespace-uri-from-QName(())
()
Additional information
•The input must be a valid QName.
•This function complements local-name-from-QName() which returns the local part.
•It can be used to determine namespace URIs dynamically when working with QName values.
node-name
The node-name function in XQuery returns the QName of the node, which includes the namespace prefix and local name as an xs:QName value. It is used to obtain the qualified name of element or attribute nodes.
Syntax
fn:node-name(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The node whose QName is returned. If omitted, the context item is used.
Return Value
•Returns the xs:QName representing the node’s name including namespace, if any.
•Returns the empty sequence if the input is an empty sequence or if the node has no name, for example, text nodes.
•Raises an error if no argument is provided and the context item is not a node.
Examples
The following table lists some sample values and return values:
•Applicable primarily to element and attribute nodes.
•For nodes that do not have a QName, such as text, comment, or processing-instruction, returns empty sequence.
•It is useful for introspecting the qualified name of nodes programmatically.
prefix-from-QName
The prefix-from-QName function in XQuery returns the namespace prefix part of a given QName value. If the QName has no prefix, the function returns an empty sequence.
Syntax
fn:prefix-from-QName(arg)
The following table describes the argument for this command:
Argument
Required/Optional
Description
arg
Optional
The QName from which to extract the prefix. Returns empty sequence if input is empty or omitted.
Return Value
•Returns the namespace prefix (xs:string) of the input QName.
•Returns the empty sequence if the QName has no prefix or the input is empty.
Examples
The following table lists some sample values and return values:
SAMPLE FUNCTION
OUTPUT
fn:prefix-from-QName(QName("", "bar"))
()
fn:prefix-from-QName(())
()
Additional information
•This function complements local-name-from-QName() and namespace-uri-from-QName().
•It is useful when needing to handle or inspect namespace prefixes dynamically.
resolve-QName
The resolve-QName function in XQuery takes a QName string and resolves it to an xs:QName value using the in-scope namespaces of a supplied element node. It essentially maps a QName in string form to an actual QName based on the element's namespace context.
Syntax
fn:resolve-QName(qname, element)
The following table describes the argument for this command:
Argument
Required/Optional
Description
qname
Required
A string representing the QName to be resolved, which might include a prefix. For example, "ex:tag".
element
Required
The element node providing the namespace context for resolving prefixes in the QName string.
Return Value
•Returns an xs:QName resolved by associating the prefix of the $qname with the namespace URI in scope on the $element.
•If the prefix in $qname is not bound in the $element's scope, or if the local part is not a valid NCName, an error occurs.
Examples
The following table lists some sample values and return values:
•The function is namespace-aware, resolving prefixes to URIs using the element's in-scope namespaces.
•The input string must be a valid QName in lexical form, either unprefixed or prefixed correctly.
•It is useful when you need to turn string names into QName values with the correct namespace bindings.
XML Nodes functions
The following XML functions are available in the XML Nodes section of the Expression Editor:
data
The atomic value of a node.
The fn:data function takes a sequence of items and returns a sequence of atomic values.
Syntax
fn:data(arg)
The following table describes the argument:
Argument
Required/
Optional
Description
arg
Required
The items whose typed values are to be returned.
Return Value
For atomic values, it returns the unchanged value. For nodes, it extracts the typed value of the node.
Example
The following expression returns 123, 456 as the result:
fn:data((123, 456))
Assume that you have the following variable definition:
let $x := <hello>Hello
let $x := <hello>Hello <world>World</world> </hello>
The expression fn:data($x) returns the following result:
Hello World
deep-equal
Assesses whether two nodes have the same content and attributes.
To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal. The $collation argument identifies a collation which is used at all levels of recursion when strings are compared, but not when names are compared.
Syntax
fn:deep-equal(parameter1, parameter2, collation)
The following table describes the arguments:
Argument
Required/
Optional
Description
parameter1
Required
The first sequence to compare.
parameter2
Required
The second sequence to compare.
collation
Optional
The collation to use for comparing strings. The collation argument identifies the collation to be used at all levels of recursion when strings are compared, but not when names are compared.
Return Value
Returns true if both the $parameter1 and $parameter2 sequences contain the same values, in the same order.
Atomic values are compared based on their typed values, using the eq operator. If two atomic values cannot be compared, for example, if one is a number, and the other is a string, the function returns false rather than raising an error.
Examples
The following expression returns true as the result:
fn:deep-equal (1, 1)
The following expression returns false as the result:
fn:deep-equal ((1,2), (2,1))
The following expression returns false as the result:
fn:deep-equal (123, John)
root
Returns the root of the tree that contains the argument.
Syntax
fn:root(arg)
The following table describes the argument:
Argument
Required/
Optional
Description
arg
Required
The node whose root node will be returned.
Return Value
The fn:root function returns a document node if the $arg node is part of a document. However, it returns an element if the $arg node is not part of a document.
If $arg is the empty sequence, the empty sequence is returned.
If the function is called without an argument, the context item is used as the default argument. If the context item is undefined or is not a node, an error occurs.
Example
Assume that you have the following variable definition:
let $in-xml := <a><x>123</x></a>
The expression root($in-xml/x) returns the following result:
<a> <x>123</x> </a>
Specifying Functions and Variables
To configure service connectors, you may need to specify variables and functions to define bindings, output fields, and other properties.
Built-in Variables
You can reference these variables in a service connector using an XQuery expression:
Variable
Variable Type
Description
$VariableName
All connection properties
Properties, input and Other Parameters can be specified using this format.
$ResponseStatusCode
Output field mapping
HTTP response code.
$ResponseHeaders
Output field mapping
Contains the HTTP response header in an element list where each item is:
<header name="Content-Type">text/plain</header>
For example:
$ResponseHeaders[@name = "Content-Type"]/text()
$RESTResponse
Output field mapping
Contains the RESTResponse XML data, including the headers and code. Visible in the Test Results for the Service Connector.
Output Field Mapping Functions
When you define bindings in the service connector, you can use many functions in the Expression Editor.
Returns a response header value. If the header parameter is not defined, this function returns the optional default value.
getResponseHeaderNames
svc:getResponseHeaderNames( $ResponseHeaders ) : list of strings
Returns a list that contains the names of all the parameters within a response header.
Digital Signature Functions Overview
Using the digital signature functions available for Process Designer, you can use XQuery to create processes and service connectors that handle signing of content. The supported functions are either:
•Symmetric, signed using Hash-based Message Authentication Code (HMAC), which is based on a shared password and key, and allows you to use multiple key formats.
•Asymmetric, signed using private keys (for example, PKCS8, PKCS12, Java KeyStore).
One common use for signed digital content is to allow for API authentication in a service connector, which allows you to use hashing and related functions on string-based content. For example, you might need to use signed headers as part of the payload
For more information on each of the functions, see Using Functions.
Note: There are currently no supported functions to verify signed content, or to sign binary content.
HMAC
The HMAC signing method is used with many services, including:
•Amazon Web Services (AWS)
•Twitter OAuth
Process Designer supports HMAC SHA1, HMAC SHA256, and HMAC SHA512 with Base64, Hex, Hex64 or Base64Url encoding. For example, you might use one of these functions to sign content for AWS:
•dsig:hmacSignature( $data as xs:string, $key as xs:string, $algorithm as xs:string, $encoding as xs:string?, $keyCharset as xs:string ) as xs:string
•dsig:hmacSHA1signature( $data as xs:string, $key as xs:string, $encoding as xs:string?, $keyCharset as xs:string ) as xs:string
•dsig:hmacSHA256signature( $data as xs:string, $key as xs:string, $encoding as xs:string?, $keyCharset as xs:string) as xs:string
•dsig:hmacSHA512signature ( $data as xs:string, $key as xs:string, $encoding as xs:string?, $keyCharset as xs:string) as xs:string
AWS Authentication
The AWS REST API requires the authentication header in this format:
Note: If using a private key to sign content, the keystore file must reside on a Secure Agent and the process or service connector must run on the Secure Agent in order to access the key. The file path to the key must be specified in the object properties (for example, "C:/certs/mykey.p12").
You can also:
•Deploy the PKCS8/12 artifact on an agent contribution and specify its location using the 'project:/' scheme.
•Supply the key using encoded key content instead of a file location, which may be useful during development of a service connector. For example, you can paste the encoded content into a text area for test purposes.
PKCS8 Key File
To sign with the PKCS8 key file, use this function:
dsig:signWithKeyFile( $messageToSign as xs:string, $pathToKey as xs:string, $encryptionAlgorithm as xs:string, $digestAlgorithm as xs:string ) as xs:string
The key file can be binary or in Base64-encoded format.
P12 and Keystore Based Files
To sign with a P12 or KeyStore-based file, use this function:
dsig:signWithCertificate( $messageToSign as xs:string, $pathToCertificate as xs:string, $keyRecoveryPassword as xs:string, $encryptionAlgorithm as xs:string, $digestAlgorithm as xs:string ) as xs:string
For example, you can use this method for Google JWT (JSON Web Token) Authentication for service accounts. After you obtain a Google private key for access and save it on your Secure Agent, you create a JWT request and sign it with your private key.
Calculates a hash-based message authentication code (HMAC) using the SHA256 algorithm and the optional encoding where $encoding is one of the following values: Base64 (default), Base64Url, Hex, or Hex64.
A sequence of one or more characters based on which you want to split the string.
secretKey
Required
The secret key for HMAC computation. The key can be of any length. However, the recommended size is 64 bytes. If the key is more than 64 bytes long, it is hashed using SHA-256 to derive a 32-byte key.
encoding
Required
Type of encoding used for the output. For example, you can calculate HMAC using the SHA256 algorithm where encoding is one of the following values: Base64 (default), Base64Url, Hex, or Hex64.
keyCharset
Optional
An argument used to specify the character set of the secret key that you pass as an argument in the function. The keyCharset is set to UTF-8 by default.
Attachments
Process Designer exposes an endpoint so you can access attachments in a process using an event handler, internal API calls, custom service connectors or built-in connectors like the Amazon S3 Connector. This enables you to pass through an attachment and extract data about the attachment like the file size and file name using functions on the response (where supported).
When you design a process, you can pass attachments into a subprocess, service connector, or Service steps or return attachments (where the output field is defined using the Attachment type).
In a process, you can allow the user to add one or more attachments as inputs where the attachment is coming directly from the screen (not carried across steps using process fields). For example, you could use a process to capture real property data and allow the user to attach photos of the associated property. However, you cannot access the attachment data within a process.
Note: If you run a process on the cloud server, do not use an attachment whose size is more than the default 5,242,880 bytes. The cloud server cannot process attachments that are greater than 5,242,880 bytes.
You can specify named input parameters as attachments using two Simple data types:
- Attachment supports single attachments and allows you to define the maximum file size as a field property.
- Attachments supports multiple attachments and allows you to define the maximum file size and maximum number of files as field properties.
From within the process, you can access metadata about the attachment using an XQuery formula and built-in functions. For example, the following returns the size of the 'photo' input:
sff:getAttachmentSize($input.photo)
You can assign input attachment fields to outputs or temp fields using an Assignment step. In that case, be sure that the target temp or output field is also of type Attachment.
In this example, the second parameter ($encodedContent) is a base64-encoded string:
Note: The attachment functions are available in processes but not in service connectors. See below for more information on handling attachments in service connectors.
Refer to Using Functions for more information on the functions available for use with attachments.
Attachment Payload
When using simple attachments, be sure that:
•Each named part has the same name (name and Content-Disposition) as the Input parameter in the process.
•The Content-Type of the part must also match the content type of the Input parameter. For all data types except attachments, Content-Type= text/plain (for example, text, checkbox, date).
•If the part represents a process object, its contents should be valid, serialized JSON content (with a Content-Type of application/json).
•You define process output field (s) of type Attachment (or Attachments). These fields are returned as attachments to the caller.
For example, if the process has input fields "first" (Text), "last" (Text), and "inputFile" (Attachment), the payload would be similar to the following:
POST /active-bpel/public/rt/Attachments_Test HTTP/1.1 Content-Type: multipart/form-data; boundary=----TheBoundary1234 ------TheBoundary1234 Content-Disposition: form-data; name="first" John ------TheBoundary1234 Content-Disposition: form-data; name="last" Smith ------TheBoundary1234 Content-Disposition: form-data; name="inputFile"; filename="filename.png" Content-Type: image/png ... binary image data ... ------TheBoundary1234--
The first part of the response should be a JSON document describing the response output fields. The JSON content will have the output field values (standard response).
If the output field is of type Attachment, the value will be a string containing the content-id (cid) of the part containing the attachment. For example, if the output fields are the "first" (Text), "last" (Text), and "inputFile" (Attachment), the response should look similar to:
•If you do not enable Output field is whole payload in the process properties and you have a single output field of type attachment, the response contains both the attachment data and the metadata, as shown here:
--Boundary content-type: ...
cid:outputFile
--Boundary content-type: image/jpeg
[binary data]
If you enable Output field is whole payload and you have exactly one output field of type Attachment, you can receive a single attachment (of type text or binary) without the metadata. If a third-party wants to access only the attachment, it is easier to consume. For example:
HTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: length
[.. JPEG data ...]
Using Attachments in Service Connectors
You can define a service connector in order to submit an attachment from a process to a service connector's input or obtain an attachment from a service connector and submit it to a process as an attachment.
Attachments are sent directly to the service input (including Salesforce-based services) from processes and service connectors.
Note: You upload or download content from services like Amazon S3 and propagate the attachment back to the main process under the name defined in the output mapping. With the Amazon S3 Connector, you can read or write the contents of an S3 object both as a Base64-encoded string and as an attachment. For more information, see the Amazon S3 Connector Guide.
Using Multiple Output Attachments in Service Connectors
A service connector can handle a multipart response appropriately and create multiple attachments for different response parts. The part related metadata information is available in the attachment properties.
A service connector can also recognize the payload part. The first JSON/XML/Text part is used as the payload. You can extract data from the payload in the output field expressions of the action as you would normally do when you work with non-multipart responses. Note that the selected payload will not be available as an attachment.
In the Output tab, you can use the Get from Attachments option to work with multiple attachments and pass the entire list of attachments to the selected variable except the payload.
You can also use an expression to work with attachments in service connectors. When you open the Expression Editor, you can find the new functions in the Functions tab, under the Output Attachments section.
Using GET, POST, and PUT
You can define a service connector to use GET, POST, or PUT operations on a resource that does not support JSON or XML.
Note that:
•The input parameters (Attachment type) must be uploaded to the destination from the binding URL (POST/PUT). Use a payload format based on the binding type and number of attachments.
•If there are multiple attachment parameters and the binding is FORM, send all the parameters (including non-file parameters) as multipart/form-data.
•If there are one or more attachment parameters and the binding is JSON, send files as multipart/form-data and combine non-file parameters into a single JSON element.
•If there is exactly one file parameter, the binding is CUSTOM, and the binding payload is empty (no XML or JSON in a custom textarea), POST or PUT the raw file data as is.
•If there are multiple attachment parameters and the binding is CUSTOM and the payload is XQuery, the HTTP outbound payload should be multipart/related. The first part is the CUSTOM (XQuery) content, followed by parts for each of the file/attachment input parameters.
•You can assign input attachment fields to outputs or temp fields using an Assignment step. In that case, be sure that the target temp or output field is also of type Attachment.
•Downloading multiple files (using multipart/mime attachment) is not supported.
Note: The "sff" functions are available only in processes.
HTTP and JMS Headers
Use header functions to get details about headers that you pass when you invoke a process. You can get details about process headers and message event headers.
Use header functions to get information that is only available in the header that you pass when you invoke a process. Examples include dates, JSON Web Tokens, and security IDs.
You can assign the header value to a field and, optionally, perform XQuery operations on the value.
The following image shows the header functions available under the Request Context section of the Expression Editor:
To understand how each function works, consider a process invoked with the following headers and values:
Header
Value
accept-language
en-US;q=0.9
client-ip
192.0.2.1
accept
text/xml
postman-token
0023-a5dfd-8vdg3-n2b3
CustomHeader
This is a custom header
ExecutionDate
Wed, July 25 2018 06:25:24 GMT
You can use the following header functions on their own, or along with other functions:
Get All Header Values
Use the getAllHeaders function to get a list of all headers and their values.
For example, if you use the following expression, you get a specific output:
Expression:
fn:getAllHeaders()
Output:
<headers> <header name="accept-language">en-US;q=0.9</header> <header name="client-ip">192.0.2.1</header> <header name="accept">text/xml</header> <header name="postman-token">0023-a5dfd-8vdg3-n2b3</header> <header name="CustomHeader">This is a custom header</header> <header name="ExecutionDate">Wed, July 25 2018 06:25:24 GMT</header> </headers>
Get Date Headers
Use the getDateHeader function to get the value of a Date header. The function returns data in the dateTime type.
You can use other Date and Time functions to parse the value.
For example, if you use the following expression, you get a specific output:
Use the getHeaderOrDefault to get a header value if the header exists, or some default value if the header does not exist.
To use this function, you must give the header name and a default value as expression parameters.
Let the default value be Not Available.
For example, if you use the following expression, you get a valid output:
Expression:
concat ("The header I want is", request:getHeaderOrDefault("postman-token","Not Avaialble" )
Output:
The header I want is 0023-a5dfd-8vdg3-n2b3
If you use the following expression, you get a Not Available output:
Expression:
concat ("The header I want is", request:getHeaderOrDefault("special-token","Not Avaialble" )
Output:
The header I want is Not Available
This is because the request does not contain a header with the name special-token.
Check if a Specific Header Exists
Use the headerExists function to check if a header with a specific name exists.
You get either True or False in the output.
For example, if you use the following expression, you get a specific output:
Expression:
request:headerExists("CustomHeader")
Output:
True
Headers from Message Events
If a process has message events, you can use any header functions to get headers from the message events. To do this, you must add the case-sensitive message event name as an expression parameter.
For example, if you pass a header with the name CustomHeader to the message event receive step, use the following expression to get the value of CustomHeader from the message event ME1.
request:getHeader("CustomHeader","ME1")
HTTP verb functions
Use HTTP verb functions to retrieve the HTTP verb and the resource path segments that are used in a request. The HTTP verb functions are available under the Request Context section of the Expression Editor.
You can use the following HTTP verb functions:
getRequestHTTPVerb
Use the getRequestHTTPVerb function to determine the HTTP verb that is used in a request. The function retrieves the HTTP verb from the request and returns one of the following responses in a string format:
- GET
- POST
- PATCH
- PUT
- DELETE
getResourcePathSegments
Use the getResourcePathSegments function to retrieve all or specific resource path segments of REST requests. The function returns the values as a string of tokens.
If you use the request:getResourcePathSegments() expression, you see the following response:
[Orders, OrderID_100, quantity, 5]
To retrieve a specific resource path segment, use a numeric qualifier to denote the position of the resource path segment from the process name.
For example, to retrieve the OrderID_100 segment alone in the response, use the following expression:
request:getResourcePathSegments()[2]
Note: You cannot use the getResourcePathSegments function to fetch the resource path segments of SOAP requests and message events. You cannot use the getResourcePathSegments function to fetch the host context.
Human task XQuery utilities
If you use a Human Task step in a process, you can use human task utility functions when working with XQuery in Process Designer or in any field that uses a formula to set a value.
The human task utility functions are available under the Human Task Utilities section of the Expression Editor.
The following table describes the human task utility functions:
Function
Syntax
Description
getHumanTaskId
task:getHumanTaskId(humanTaskStepName)
Returns the ID of the human task associated with the specified Human Task step name.
You can use the ID for other actions such as getting information about a human task, reassigning a task, or canceling a task.
getHumanTaskInfo
task:getHumanTaskInfo(humanTaskId)
Returns the following information about the human task based on the specified human task ID:
Reassigns a human task to the specified users and groups, and returns the task ID.
If you reassign the task to a single user, the user becomes the task owner. If you reassign the task to a group or multiple users, a user must claim the task to become the task owner.
To specify multiple users or groups, use a comma character as the delimiter. For example, use the following syntax:
