Virtuoso Functions Guide

Function: VAR

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the variance.VAR (VARIANCE) returns variance of expr. Virtuoso calculates the variance of expr as follows: 0 if the number of rows in expr = 1; VAR_SAMP if the number of rows in expr > 1

Function: VAR_SAMP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the sample variance.VAR_SAMP returns the sample variance of a set of numbers after discarding the nulls in this set. The expr is a numeric expression, and the function returns a value of type NUMERIC. If the function is applied to an empty set, then it returns null. The function makes the following calculation: This function is similar to VAR, except that given an input set of one element, VAR returns 0 and VAR_SAMP returns null.

Function: VAR_POP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the population variance.VAR_POP returns the population variance of a set of numbers after discarding the nulls in this set. The expr is a number expression, and the function returns a value of type NUMERIC. If the function is applied to an empty set, then it returns null. The function makes the following calculation:

Function: STDDEV

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the standard deviation.STDDEV returns standard deviation. it returns STDDEV_SAMP if the number of pairs is more than one, or NULL.

Function: STDDEV_SAMP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the cumulative sample standard deviation.STDDEV_SAMP computes the cumulative sample standard deviation and returns the square root of the sample variance. The expr is a numeric expression, and the function returns a value of type NUMERIC. This function is same as the square root of the VAR_SAMP function. When VAR_SAMP returns null, this function returns null.

Function: STDDEV_POP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the population standard deviation.STDDEV_POP computes the population standard deviation and returns the square root of the population variance. This function is the same as the square root of the VAR_POP function. When VAR_POP returns null, this function returns null.

Function: REGR_SYY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Auxiliary function used to compute various diagnostic statistics.REGR_SYY makes the following computation after eliminating NULL (expr1, expr2) pairs:

Function: REGR_SXX

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Auxiliary function used to compute various diagnostic statistics.REGR_SXX makes the following computation after eliminating NULL (expr1, expr2) pairs:

Function: REGR_SXY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Auxiliary function used to compute various diagnostic statistics.REGR_SXY makes the following computation after eliminating NULL (expr1, expr2) pairs:

Function: REGR_AVGX

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Evaluates the average of the independent variable (expr2) of the regression line.REGR_AVGX evaluates the average of the independent variable (expr2) of the regression line. It makes the following computation after the elimination of null (expr1, expr2) pairs:

Function: REGR_AVGY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Evaluates the average of the independent variable (expr1) of the regression line.REGR_AVGY evaluates the average of the independent variable (expr1) of the regression line. It makes the following computation after the elimination of null (expr1, expr2) pairs:

Function: REGR_R2

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the coefficient of determination (R-squared) of the regression line.REGR_R2 returns the coefficient of determination (also called "R-squared" or "goodness of fit") for the regression. VAR_POP(expr1) and VAR_POP(expr2) are evaluated after the elimination of null pairs. The return values are:

Function: REGR_COUNT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the number of non-null numbers used to fit the regression line.REGR_COUNT Returns the number of non-null numbers used to fit the regression line.

Function: REGR_INTERCEPT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the y-intercept of the regression line.REGR_INTERCEPT returns the y-intercept of the regression line. After the elimination of null (expr1, expr2) pairs, it makes the following computation:

Function: REGR_SLOPE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the slope of the line.REGR_SLOPE returns the slope of the line. After the elimination of null (expr1, expr2) pairs, it makes the following computation:

Function: COVAR_SAMP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the sample covariance of a set of number pairs.COVAR_SAMP returns the sample covariance of a set of number pairs. Both expr1 and expr2 are numeric expressions. Virtuoso applies the function to the set of (expr1, expr2) pairs after eliminating all pairs for which either expr1 or expr2 is null. Then Virtuoso makes the following computation: where n is the number of (expr1, expr2) pairs where neither expr1 nor expr2 is null.

Function: COVAR_POP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the population covariance of a set of number pairs.COVAR_POP returns the population covariance of a set of number pairs. Both expr1 and expr2 are numeric expressions. Virtuoso applies the function to the set of (expr1, expr2) pairs after eliminating all pairs for which either expr1 or expr2 is null. Then Virtuoso makes the following computation: where n is the number of (expr1, expr2) pairs where neither expr1 nor expr2 is null.

Function: CORR

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the coefficient of correlation of a set of number pairs.CORR returns the coefficient of correlation of a set of number pairs. Both expr1 and expr2 are number expressions. Virtuoso applies the function to the set of (expr1, expr2) after eliminating the pairs for which either expr1 or expr2 is null. Then Virtuoso makes the following computation:

Function: abs

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Return the absolute value of a numberabs returns the absolute value of its argument.

Function: __any_grants

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Checks a table for grants.The __any_grants() can be used to test whether there are any rights granted (for insert/update/delete) to a table for current SQL account.

Function: aref

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns specific element of an array or stringaref returns the nth element of an array, string or string_session, where nth is a zero-based index. If the first argument is a string or string_session, the integer ASCII value of the nth character is returned. If the first argument is an array of any, then the corresponding element is returned.

Function: ascii

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get ASCII value of a characterascii returns the ASCII value of the first character of a string. If an empty string is given, then zero is returned.

Function: aset

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

set array elementaset sets the nth element of a string, array or vector where nth is a zero-based index. If the first argument is a string, the nth character of string is replaced with the ASCII value given in the third argument elem.

Function: atof

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Convert a string to single precision floatatof returns its argument as a single precision floating point. If the string cannot be parsed and converted to a valid float, a value 0.0 is returned.

Function: atoi

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Convert a string to an integeratoi returns its argument as an integer. If the string cannot be parsed and converted to a valid integer, a value 0 is returned.

Function: att_local_name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Compose a fully qualified table name based on DSN and remote table name.The utility function, att_local_name(), can be used to make a fully qualified table name from non-qualified or qualified one, i.e. the qualifier and owner will be added if they are missing. The schema name will be replaced with current qualifier on execution, owner will be replaced or added with name of supplied DSN name. All non-alphanumeric characters in the name will be replaced with underscore symbol.

Function: backup

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Write data into transaction log format for backup purposes. Deprecated. This function requires dba privileges.

Function: backup_online

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

perform online backup of databaseThis procedure will backup all information from the checkpoint space to a series of files named ".bp", where is the sequence number of the file in the backup series. The first backup will be a full gzip compressed dump of database pages in the checkpoint space. Any subsequent call will only backup pages which have changed since the last backup was made. To start with a fresh full backup, use backup_clear_context to clear the change tracking data. At each checkpoint the checkpoint space will be updated, and the next "backup_online;" procedure will create new files. Once backup_online() has been called for the first time, the arguments supplied will be used for subsequent calls to it. Hence, arguments supplied to this procedure (except the "dirs" argument) will be ignored in subsequent calls. Before a new backup series can be started, the backup_context_clear(); procedure must be called first. This procedure will clear the current backup context and mark all pages in the checkpoint space as ready for backup. A database checkpoint cannot be performed while an online backup is in progress. Attempt to do a checkpoint will wait until the backup is complete.

Function: backup_context_clear

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Clears the backup context and marks all pages in checkpoint space as ready for online backupThis procedure must be called before a new backup series can be started, This procedure will clear the current backup context and mark all pages in the checkpoint space as ready for backup.

Function: Virtuoso Server Extension Interface (VSEI) functions

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get parameters for built in functionThe bif_...._arg functions are used in the Virtuoso shared object. They allow customization of the Virtuoso server. They are written in C code, and linked with the Virtuoso shared object. The _or_null_ variants of these functions represent the SQL null value as a 00 pointer, even though getting the same argument with bif_arg() would return a box with the DV_DB_NULL tag. All number functions will coerce other types of numbers to the result type. All array argument functions will accept any type of array. It is up to the VSE itself to distinguish. Virtuoso Server Extensions (VSEs) were formally referred to as Built-In Functions (BIFs).

Function: bit_and

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns bitwise AND of two 32-bit integers.The function returns bitwise AND of two given integers. On 64-bit platforms, both arguments are intentionally truncated to 32 bits to maintain compatibility.

Function: bit_or

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns bitwise OR of two 32-bit integers.The function returns bitwise OR of two given integers. On 64-bit platforms, both arguments are intentionally truncated to 32 bits to maintain compatibility.

Function: bit_not

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns bitwise NOT of a 32-bit integer.The function returns bitwise NOT of a given integer. On 64-bit platforms the argument is intentionally truncated to 32 bits to maintain compatibility.

Function: bit_shift

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the result of bitwise shift operation over two 32-bit integers.The function returns bitwise shift of two given integers. Depending on the arguments, the shift may be left or right. For right-shift, leftmost bits of the result are filled by the value of the 31-st bit. On 64-bit platforms, both arguments are intentionally truncated to 32 bits and the shift is restricted to 32 bits to maintain compatibility.

Function: bit_xor

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns bitwise XOR (exclusive "or") of two 32-bit integers.The function returns bitwise XOR (exclusive "or") of two given integers. On 64-bit platforms, both arguments are intentionally truncated to 32 bits, to provide compartibility.

Function: blob_to_string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Convert a blob to stringAlthough primarily used for converting blobs (long varbinary, long varchar) to string, blob_to_string may also be used to convert from wide string, persistent XML (XPER) and string_output streams. If the data being converted is longer than maximum length of a string, blob_to_string will signal an error.

Function: blob_to_string_output

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Convert a blob to string sessionAlthough primarily used for converting blobs (long varbinary, long varchar) to string output object, blob_to_string_output may also be used to convert from wide string, persistent XML (XPER) and string_output streams.

Function: bookmark

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Return the bookmark for current row of a scrollable cursorbookmark returns a bookmark for the current row of an open scrollable cursor. Given an invalid argument, i.e. no cursor, no current row or non-open cursor, it signals an error. The returned value can be used in subsequent FETCH .. BOOKMARK over the same cursor.

Function: ceiling

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Round a number to positive infinity.ceiling calculates the smallest integer greater than or equal to x.

Function: cfg_item_count

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

return number of items in a section in configuration fileReturn the number of items that exist in the specified section of the INI file.

Function: cfg_item_name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get nth item name from ini fileReturns the name of the item specified by item_index (begins from zero). If the index and section name do not point to a valid item, then zero is returned, otherwise on success the function returns the item name.

Function: cfg_item_value

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the value of an item from the ini fileReturn the value of an item identified by item_name and section parameters from the specified INI file.

Function: cfg_section_count

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get number of sections in an INI fileReturns the number of sections in an INI file.

Function: cfg_section_name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns INI file section nameReturns the name of section specified by the index (begins from zero). If the index can reference a section, the that section name is returned, otherwise returns zero on error.

Function: cfg_write

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Writes the item=value to an INI fileThis function requires dba privileges. This function allows modification of existing entries, or update updating existing items in an INI file.

Function: charset_define

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Define a character set.This function creates a new narrow language-specific character set, or redefines an existing one.

Function: charset_recode

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Translate a string to another character setThis function translates a string from a given source charset to a destination charset. It provides a generic way of recoding string entities. The src_charset may be a narrow or a wide string. If it's a narrow string (VARCHAR) then the src_charset is taken into account and defines the current encoding of the src_string. In any other case src_charset is ignored. src_charset and dst_charset are names of system-defined 8 bit charset tables. Use charsets_list to obtain a list of currently defined character sets and aliases. If either of these is null, then the charset in effect is used. There are two special character set names - "UTF-8" and "_WIDE_" - that are recognized by this function. These represent UTF-8 encoding of characters and wide string (NVARCHAR).

Function: charsets_list

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

List known character set names and aliases.This function produces a list of all character set names and aliases known to Virtuoso. The returned value is an array of strings with a character set name as each element. If the gen_res_set flag is 1, the function also produces a result set in which each row contains one varchar column with a name of a character set or alias.

Function: checkpoint_interval

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Configure database checkpointingThis function changes the database checkpointing interval to the given value in minutes. It may also be used to disable checkpointing in two ways: By setting checkpoint interval to 0, the checkpoint will only be performed after roll forward upon database startup. A setting of -1 will disable all checkpointing. Main use for this function is to ensure a clean online backup of the database slices. Copying of the database may take long and checkpointing would modify those files in mid-copy, thus rendering the resulting copy unusable. In case the system should, for some reason or another, become unstable, it is sometimes better to disable checkpointing after a database restart to resume backing up from where it was left prior to a system crash. Disabling all checkpointing by giving checkpoint_interval the value of -1 will do just that. The interval setting will be saved in the server configuration file as value of CheckpointInterval in section [Parameters], thus it will persist over consecutive server shutdown/restart cycles. A long checkpoint_interval setting will produce longer transaction logs, which in turn prolongs the time it takes for the database to perform a roll forward upon restart in case it was shut down without making a checkpoint.

Function: chr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Convert a long character code to a character or wide characterchr returns a new one character long string containing the character with character code given as parameter.

Function: client_attr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a varchar containing the requested information from the connection

Function: collation_define

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

define a new collationThis function lets you define a new collation.

Function: complete_table_name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a fully qualified table name.The complete_table_name() can be used to make a fully qualified table name from non-qualified one, i.e. the qualifier and owner will be added if they are missing.

Function: composite

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create a composite objectCreate a composite object Returns a composite object containing the serialization of each argument. The total serialized length of the arguments may not exceed 255.

Function: composite_ref

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get member of a composite objectcomposite_ref returns the nth element of the composite. The index is 0 based.

Function: concat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Concatenate stringsconcat returns a new string, concatenated from a variable number of strings given as arguments. NULL arguments are handled as empty strings. concat (str) returns a copy of str. concat () returns an empty string.

Function: concatenate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

concatenate stringsConcatenate is an alias of concat.

Function: connection_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get connection variableconnection_get is used to retrieve values stored within the current connection context. See connection_set for a more detailed discussion of connection variables.

Function: connection_id

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get connection identifierThis function returns a string uniquely identifying the connection in this server instance. It is usually a combination of server's port number and a serial number of the client.

Function: connection_is_dirty

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

check if current session connection variables have been alteredThis function is used to determine if the session variables have changed between a call to connection_vars_set and current point of execution. A call to connection_vars_set will cause subsequent calls to connection_is_dirty to return true. The function is useful in postprocessing functions for making conditional storage of session variables in a database table.

Function: connection_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Associates a value to the name in the context of the present connectionThis associates a value to the name in the context of present connection. The name should be a string and the value can be any data type except blob, open cursor or an XML entity. If the value is an array it may not contain the restricted types. Connection variable setting is not logged and information stored will be lost when the connection is closed. The value can be retrieved by any future statement executing within the same connection. Connection variables can be used as a global variable mechanism for stored procedures, the scope being the client connection. In the case of VSP or SOAP this mechanism cannot be used to pass information between requests by the same client. It will however, be useful for having 'global variables' between procedures called within the same HTTP request. Note that this mechanism is used to provide persistent HTTP session variables in some cases but this works through special before and after code which stores the values set with this function into an external session structure. In this sense this function itself has nothing to do with web session management although it can be used as a component for such.

Function: connection_vars

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieve all connection variables This function returns all stored session variables in an array with name/value pairs. Connection variables do not persist across sessions, one may maintain persistence of variables by storing them in a database table: see the Session Variables Section.

Function: connection_vars_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

set all connection variablesThis function clears all connection variables for current session and sets new ones defined in the array passed as parameter. Connection variables do not persist across sessions, one may maintain persistence of variables by storing them in a database table, as discussed in Session Variables -section.

Function: contains

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

A text contains predicate This is a SQL predicate that specifies a condition on a column on which a free text index exists. The expression is a string matching the grammar of a text search expression. This is computed for each evaluation of the contains predicate and does not have to be a constant. For example a parameter or variable of a containing score (e.g. procedure) is accepted. The score_limit is optional. If specified, it should be a numeric expression determining the minimum score required to produce a hit. A virtual column named 'SCORE' is available in queries involving a contains predicate. This can for example be returned in a result set or used for sorting. Note that the name is in upper case and is case sensitive in all case modes.

Function: cov_load

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Load test coverage data from file.This function accepts one argument with name of file containing test coverage data. The expected format of the file is described in the Branch Coverage section. The loaded file is merged with the data already collected by Virtuoso. More than one file can be loaded. The ultimate report will be the union of all files.

Function: cov_report

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Produce a text coverage report.This function is used to produce a coverage report in text format. The format of the file is described in the Branch Coverage section. This function takes a filename 'fname' as a path to the extended coverage report file and 'outdir' as a path to a directory where .cov files will be stored. The profile.prof file in the output directory is a summary of function call counts and execution times, once ranked by self time, once by time spent inside the function and functions called from there. Note that directory must exists before calling this function.

Function: cov_store

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Writes a test coverage to a file.This function is used to produce a coverage file called fname. The expected format of the file is described in the Branch Coverage section. By default a normal concise coverage will be produced. If the add_comment parameter is set to 1 then the coverage will include code excerpts contained in line entities.

Function: createXML

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function creates an XMLType instance. It works absolutely identically to the XMLType() constructor and is provided solely for compatibility.

Function: curdate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get current date and timeThese functions return the current date or time as a date, time or datetime, respectively. Internally they all return the same value but data type reported to client differs.

Function: current_charset

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get name of current charset.This function returns the "preferred" name of the current charset as a string. It returns value which is set in the INI file or those which is set with 'SET CHARSET=..' call. This cannot be used to return charset for the current HTTP connection in the VSP or VSPX context.

Function: DB.DBA.VACUUM

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Compact the databaseThis function reads through the specified tables and indices and finds groups of adjacent pages holding data that will fit on fewer pages than it currently occupies. If such a compression can be made, the pages are thus compacted. The pages become part of the committed state and will be written to the checkpoint space on the next checkpoint. The vacuum operation is non-locking and can be run on a busy database. It will simply skip pages with ongoing activity such as pending cursors or locks. The vacuum procedure returns only after it has read through the indices it affects but it will not prevent other activity on the indices. The vacuum operation may run out of disk space even if it makes net gains because the modified pages will not be final until the next checkpoint and the originals will not be free until this same checkpoint. Thus manually running a checkpoint after vacuum runs out of space will free the space and vacuum may be rerun.

Function: dateadd

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

arithmetic add to a datedateadd adds a positive or negative quantity of units to a date (in the internal date time format), and returns a new date so formed. The unit is specified as a string and can be one of the following: 'second', 'minute', 'hour', 'day', 'month', or 'year'. Use datestring to convert the result to a human-readable string.

Function: datediff

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get difference of 2 datesdatediff subtracts date1 from date2 and returns the difference as an integer in the specified units.

Function: datestring, datestring_gmt,

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

convert a datetime from internal to external date-time representationdatestring and datestring_gmt convert timestamps or datetimes from internal to external date-time representation. The external representation is a human-readable ASCII string of up to 30 characters. The external format is: YYYY-MM-DD hh:mm:ss uuuuuu where uuuuuu represents microseconds.

Function: datestring_GMT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

convert a timestamp to external format string in GMTConverts the local datetime to GMT and returns its external representation as a string.

Function: DAV add & update functions

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

functions for adding, updating, deleting of DAV collections or resourcesDAV_COL_CREATE creates a new collection on path, with supplied security permissions, returning a collection id (COL_ID) upon success. DAV_RES_UPLOAD creates or replaces an existing resource on path with content, mime type and supplied security permissions. Returns a resource id (RES_ID) on success. DAV_DELETE Removes an existing collection/resource. If silent is set to a nonzero value, no errors codes will be returned. returns 1 on success.

Function: DAV manipulation functions

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Functions for manipulating an existing DAV collection or resourceDAV_COPY copies the resource or collection taken from path to the destination. returns COL_ID or RES_ID on success. DAV_MOVE moves the collection or resource to the destination path returns 1 on success. DAV_PROP_SET defines or updates the property with name propname with propvalue. Returns PROP_ID on success.

Function: DAV lock manipulation functions

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Operations on locks of DAV collections and resourcesDAV_LOCK sets a new lock or refresh an existing lock or creates a lock object. DAV_UNLOCK releases a lock. DAV_IS_LOCKED reports whether the resource or collection is locked.

Function: DAV search functions

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Functions for searching a DAV collection or resourceDAV_SEARCH_ID() returns the RES_ID or COL_ID, depending on the 'what' parameter passed. ('R'esource or 'C'ollection or 'P'arent collection). DAV_SEARCH_PATH() returns full path string of resource or collection, depending on parameter passed. ('R'esource or 'C'ollection or 'P'arent collection). DAV_DIR_LIST() returns an array of arrays that contains the following information about the requested path:

Function: WebDAV Users & Groups administration

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Functions for manipulating an existing DAV collection or resourceDAV_ADD_USER() create a new WebDAV user with login name 'uid' and password 'pwd'. User will belong to the group named 'gid'. 'perms' are the default user permissions for creation of new resources. Additional user info supplied is 'home' directory, 'full name' and 'e-mail'. DAV_DELETE_USER() remove the existing webDAV user named 'uid'. DAV_HOME_DIR() returns the home folder for specified WebDAV user named 'uid'.

Function: DAV_EXP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Export a retrieved Web site to another WebDAV enabled serverThis function is used to export local content retrieved from a Web Robot Copy to the local file system.

Function: dayname

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

decompose a datetime to its componentsThese functions decompose a datetime to its components. These can be used on timestamps, datetimes, dates and times, all being the same internal data type.

Function: dayofmonth

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get day of month from a datetimedayofmonth takes a datetime and returns an integer containing day of the month represented by the datetime

Function: dayofweek

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get day of week from a datetimedayofweek takes a datetime and returns an integer containing a number representing the day of week of the datetime.

Function: dayofyear

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get day of year from a datetimedayofyear takes a datetime and returns an integer containing a number representing the day of year of the datetime.

Function: dbg_obj_print

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

print to the Virtuoso system consoledbg_obj_print prints a variable number of arguments onto the system console (stdout) of Virtuoso server, each argument in its own native format, on the same line, which is followed by one newline.

Function: dbg_printf

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

print formatted output onto the system consoledbg_printf prints a variable number (max. eight) of arguments to the system console of Virtuoso server, each argument formatted in C printf style, according to the format string specified in the first argument.

Function: dbname

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get current catalogReturns the current qualifier as set by the USE statement or default.

Function: delay

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

sleep for n secondsThis will halt calling procedure execution for specified interval in seconds.

Function: dict_duplicate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a copy of the given dictionary.The function creates a full copy of the given dictionary. Dictionary objects are always passed by reference, even if dictionary is passed as an 'in' argument of a function. If value of a variable is a dictionary and it is assigned to other variable then both variables refer to the same internal hash table. This function returns a really independent dictionary object. This function duplicates the given dictionary but does not duplicate dictionaries that may be stored in key-value pairs.

Function: dict_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the dependent part that corresponds to the given key in the given dictionary.The function returns the dependent part that corresponds to the given key in the given dictionary. The function returns default_value if the dictionary does not contain a pair whose key is equivalent to the given one. When only two arguments are passed to the function the default value is integer zero.

Function: dict_list_keys

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns an array of all keys stored in the given dictionary.The function returns an array of all keys stored in the given dictionary, ignoring dependent parts of key-value pairs. This is especially useful when dictionary is used to form a set of distinct keys, when dependent parts are fake (typically zeroes). If the destructive parameter is nonzero then the function may avoid copying of keys to the resulting array by moving them out from the dictionary. This is faster but the dictionary will become empty at the end of operation. The destructive parameter does not have any effect if the dictionary is used as a value of more than one variable. Thus it is safe to make this parameter nonzero as soon as the variable passed to the function as dict is no longer in use after the function call and there's no need to inspect the whole program to check if other variables may be affected.

Function: dict_new

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a new dictionary to store key-value pairs.This function creates a new dictionary. A dictionary is a memory-resident hash table that can store an arbitrary number of key-value pairs. Both key and dependent part can be of any type, including vectors. Two keys of different data types are always considered as different even if SQL '=' operator return 'true', e.g. integer zero and double precision 0.0 are two different keys. Vectors are equivalent if their corresponding members are either equal scalars or equivalent vectors. XML entities are equivalent if they refer to the same node or attribute in the same document. Dictionary objects are always passed by reference, even if dictionary is passed as an 'in' argument of a function. If value of a variable is a dictionary and it is assigned to other variable then both variables refer to the same internal hashtable. To create two really independent dictionary objects, use dict_duplicate ().

Function: dict_put

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds a key-value pair to a dictionaryThe function adds or updates a key-value pair in the given dictionary. If the dictionary contains a pair with the key part equivalent to the given one then old value is replaced with a new one. Otherwise, a new pair is added to the dictionary.

Function: dict_remove

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Removes the given key and associated dependent value from the given dictionary.The function removes the given key and the associated dependent value from the given dictionary. If the key-value pair is found (and removed) the function returns 1. If the dictionary does not contain a key equivalent to the given one the function returns zero.

Function: dict_to_vector

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a get_keyword style vector of all items stored in the given dictionary.The function returns an array of all data stored in the given dictionary, every pair is represented as two consecutive element of the resulting array. Thus the dictionary of N pairs is converted into a vector of length 2N where keys are at positions 0, 2, 4, ..., 2N-1 and corresponding dependent data are at positions 1, 3, 5, ..., 2N. If keys are all scalars of same type then get_keyword function can be used to search in the resulting array. If the destructive parameter is nonzero then the function may avoid copying of keys to the resulting array by moving them out from the dictionary. This is faster but the dictionary will become empty at the end of the operation. The destructive parameter does not have any effect if the dictionary is used as a value of more than one variable. Thus it is safe to make this parameter nonzero as soon as the variable passed to the function as dict is no longer in use after the function call and there's no need to inspect the whole program to check if other variables may be affected.

Function: disconnect_user

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Disconnect client connections of a given userdisconnect_user disconnects clients whose username matches the username_pattern string given as an argument, and returns an integer value giving the number of clients disconnected. This can be used after DELETE USER or REVOKE statement to make sure that the affected user has no open connections.

Function: dt_set_tz

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

modifies the timezone component of a datetimeThis modifies the timezone component of a datetime. The value remains equal for purposes of comparison but will look different when converted to a string. The timezone component is an offset from UTC in minutes. It can be retrieved with the timezone function.

Function: dvector

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

return an array of either long, float or double These functions are like vector but return an array of either long, float or double whereas vector returns a generic, untyped array.

Function: end_result

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

End the current result set.The result_names() predefines variables to be used in a result set to follow. The variables must be previously declared, from which the column data types are ascertained. This assigns the meta data but does not send any results. The result() function sends its parameters as a single row of results. These parameters should be compatible with those in the previous result_names(). The end_result() function can be used to separate multiple result sets. The result_names() can then be used to alter the result set structure. The result_names() call can be omitted if the application already knows what columns and their types are to be returned.

Function: either

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

conditionally return one of specified parameterseither returns a copy of arg1 if cond is something else than integer 0 (zero). Otherwise, a copy of arg2 is returned.

Function: elh_get_handler

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get localization function handler

Function: elh_load_handler

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

load encoding handler into system Loads given handler in table of handlers bound to encoding specified in the handler, using ISO 639 and RFC 1766 language IDs of the handler as keys for future table lookups. If another handler was already specified for given RFC 1766 id, table entry will be updated and will refer to new handler. If another handler was already specified for given ISO 639 id, it will be replaced only if new handler has ISO 639 language ID equal to its RFC 1766 ID. Please do not load custom versions of 'x-any' and 'x-ftq-x-any' handlers.

Function: encode_base64

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

base64-encode/decode a stringThese functions convert strings from/to base64-encoding.

Function: equ

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

comparison functionsThese functions return 1 if their first argument is less than (lt), less than or equivalent (lte), greater than (gt), greater than or equivalent (gte), equivalent (equ), or not equivalent (neq) to the second argument, respectively. If the arguments are not of the same type, then an appropriate type coercion is done for them before comparison. These functions correspond to SQL query operators <, <=, >, >=, = and <> and are needed because the SQL syntax does not allow these operators to be used on the left side of FROM keyword in a SELECT statement.

Function: exec

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

dynamic execution of SQL returning state and result setThis function provides dynamic SQL capabilities in Virtuoso PL. The first argument is an arbitrary SQL statement, which may contain parameter placeholders. The function returns as output parameters a SQL state, error message, column metadata and result set rows if the statement is a select. A stored procedure can be invoked by exec but a procedure's result set will not be received in the rows output parameter but rather sent to the client.

Function: close

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Closes cursor created by exec()Closes the cursor opened by the exec() function.

Function: exec_next

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get next result from a result setUse exec_next() to iterate over a result set produced by a statement run with exec.

Function: exec_result

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a result set row to the calling procedure contextThis function returns a result set row to the calling procedure's context, whether it is the client, exec function or a procedure view). The row's values are the elements of the supplied res_values_array vector.

Function: exec_result_names

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Supplies column details for procedure result set output.This function allows you to define the column details for result sets returned by procedures, in particular for use with the exec() function. This function is similar to result_names().

Function: exec_metadata

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Compiles a SQL statement and returns the metadataThis function provides dynamic SQL capabilities in Virtuoso PL. The first argument is an arbitrary SQL statement, which may contain parameter placeholders. The function returns as output parameters a SQL state, error message, column metadata if the statement is a select.

Function: exec_score

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Compiles a SQL statement and returns the estimate time costThis function provides dynamic SQL capabilities in Virtuoso PL. The first argument is an arbitrary SQL statement, which may contain parameter placeholders. The function returns as output parameters a SQL state, error message and returns the estimate time cost in milliseconds.

Function: exp

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

calculate exponentThe function raises e to the power of x, it works with double precision floating point numbers, converts its argument to an IEEE 64-bit float and returns a result of that type.

Function: explain

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

describe SQL statement compilation The explain function compiles a SQL statement and returns a description of that compilation as a result set, return value or parse tree. The result set consists of one VARCHAR column with one line of the description in each row. Any given line may be quite long, even several hundred characters. The output is not a complete disassembly of the query graph, but it is detailed enough to show the join order, the sub-query structure, and the order of evaluation of query predicates, as well as the splitting of a distributed VDB query over different data sources. The optional cursor type can be one of the SQL_CURSOR_ constants, or one of the special values listed below. The default is 0, for FORWARD ONLY. The special values each have special effect, as listed. If the statement is a SELECT and the cursor type is not FORWARD ONLY, the auxiliary SQL statements used by the cursor implementation are shown.

Function: file_delete

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Delete a file from the file systemThis function requires dba privileges. This function is used to delete a file from file system. This function has a silent mode, where no errors will be signalled upon failure.

Function: file_dirlist

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns list with content of file system directoryThis function requires dba privileges. This returns the list of the contents of a given file system directory.

Function: file_mkdir

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a directory in the file systemThis function requires dba privileges. This function creates a file system directory.

Function: file_mkpath

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Make a directory chainThis function requires dba privileges. This is to create a directory chain i.e. 'a/b/c/d', where one or more elements in the path may not exist.

Function: file_stat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get various OS statistics about a filefile_stat returns various information for an OS file by calling stat () system call and converting the relevant value to a varchar. The path is relative to the server's working directory. The what is an integer value selecting what information to return. If you don't supply second argument to the function it defaults to mode = 0. The DirsAllowed and DirsDenied lists in Parameters section of the virtuoso configuration file (virtuoso.ini by default) are not used to control disk access.

Function: file_to_string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the contents of a file as a varcharThis function requires dba privileges. Returns the contents of a file as a varchar value. The file's length is limited to 16 MB. The path is relative to the working directory of the database server.

Function: file_to_string_output

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get contents of a file as a string output streamThis function requires dba privileges. This function returns a string output stream initialized to contain the text of the file or its segment, on local file system path relative to the server's working directory. file_to_string_output can handle longer files than file_to_string and the resulting string output, if too long to be converted into a varchar, can be stored inside a blob.

Function: file_unlink

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Delete a file from the file systemThis function requires dba privileges. This function deletes a file from the file system. sys_unlink is a synonym of this function.

Function: fk_check_input_values

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

alter default foreign key checking behavior Enforcing foreign key constraints is enabled by default. This function allows globally disabling it without however disabling all triggers. This may be useful for large data imports or other special circumstances. The return value is the previous state of this setting, 0 for off, 1, for on. The effect of this function is persistent and survives server restart.

Function: floor

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Round a number to negative infinity.floor calculates the largest integer smaller than or equal to x.

Function: ftp_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

FTP get command; Virtuoso FTP clientVirtuoso has FTP client functionality, that can be used inside Virtuoso/PL. This Virtuoso function mimics the FTP get command. As with any PL, this can be combined with Web Services and SOAP.

Function: ftp_ls

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

FTP dir command; Virtuoso FTP clientVirtuoso has FTP client functionality, that can be used inside Virtuoso/PL. This Virtuoso function mimics the FTP dir command. As with any PL, this can be combined with Web Services and SOAP.

Function: ftp_put

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

FTP put command; Virtuoso FTP clientVirtuoso has FTP client functionality, that can be used inside Virtuoso/PL. This Virtuoso function mimics the FTP put command. As with any PL, this can be combined with Web Services and SOAP.

Function: gz_file_open

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the contents of a gzipped fileReturns the contents of a file. The path is relative to the working directory of the database server.

Function: get_certificate_info

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns information about the current client X509 certificate This function will return information about the current client X509 certificate (if successfully verified). If there is no valid X509 certificate or the requested information is not available it will return NULL. If the optional cert_or_key_name is supplied it should contain a encoded certificate (by default format is PEM). The certificate info is read from the first certificate in that string. If the optional cert_or_key_name is supplied and in_format is equal to 3 (integer) the function will try to retrieve the certificate registered in the current user's key store by name contained in cert_or_key_name.

Function: get_keyword

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Find a value in keyword vectorget_keyword performs a case sensitive seek for the occurrence of keyword from each even position of searched_array. If found,this returns the element following the occurrence of the keyword. If the keyword is not found this returns the default argument or NULL if the default is not supplied.

Function: get_keyword_ucase

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Find a value in keyword vector (search uppercase)Identical to get_keyword except all comparisons are performed case insensitively.

Function: get_timestamp

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the timestamp of the current transactionget_timestamp is merely an alias for now and is provided for backward compatibility.

Function: getdate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the current transaction timestamp, alias of nowgetdate() returns the timestamp associated with current transaction. This is an alias of now().

Function: gz_compress

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Compress data using gzip algorithm The gz_compress returns its argument compressed with the gzip algorithm. The argument and return values are arbitrary strings, possibly including any 8 bit characters.

Function: gz_uncompress

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Uncompress a string using gzip algorithmgz_uncompress takes a string argument, uncompresses it using the gzip algorithm, writing it to a string_output given as the second argument.

Function: hour

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get hour from a datetimehour takes a datetime and returns an integer containing a number representing the hour of the datetime.

Function: http

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

write to HTTP client or a string output streamhttp writes val_expr to HTTP client or, if parameter stream is given, to the given string output stream. val_expr may be any scalar object, i.e. string, date or number and will automatically be cast to varchar before further processing. http will print out the string without escapes. http_value uses HTML escapes and http_url URL escapes.

Function: http_acl_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Set conditions against web server ACL'sThis function can be used within application logic to set ACLs rule.

Function: http_acl_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Test conditions against web server ACL'sThis function can be used within application logic to test that an internet client would not violate the ACL.

Function: http_acl_remove

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Removes conditions against web server ACL'sThis function can be used within application logic to remove ACLs rule.

Function: http_body_read

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Reads the HTTP body from the client HTTP connection and returns it as a string. This function reads the HTTP body from the client HTTP connection and returns it as a string output. This is suitable for processing POST requests with bodies encoded differently than multipart/* and application/x-www-form-urlencoded as in SOAP requests where the POST body is encoded as text/xml).

Function: http_client

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a varchar containing the body of the request uriThis function is used to perform HTTP operations to retrieve generic content and/or to perform generic operations over HTTP/HTTPS protocols. It also supports HTTP authentication based on username/password credentials. If the URL is https: an no x509 certificate given then it will operate as https client w/o client certificate.

Function: http_client_ext

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Function: http_client_ip

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the IP address of the calling client.This function is used to determine the IP address or DNS name of the calling client. Please note that this function is slow when resolving a DNS names. It is advisable to use IP addresses to to make applications faster.

Function: http_debug_log

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

set WebDAV HTTP request loggingWhen an valid path string is supplied and it is allowed in file ACL list, the WebDAV HTTP requests and responses will be logged in append mode in to that file. When an open logging session is encountered the second call will produce an error. Specifying a NULL instead of file_path string stops the logging. The log file consists of lines with following fields:

Function: http_enable_gz

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Enable / Disable "Content-Encoding: gzip" for HTTP server Enable (1)/ Disable (0) "Content-Encoding: gzip" for HTTP server.

Function: http_file

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Send a file to the HTTP client This function causes the contents of the file specified by path to be sent as the response of the calling request. The file is not sent until the code calling this returns. Content types etc. are defaulted based on the file's extension. If this function is called, other output to the HTTP client by the caller is discarded.

Function: http_flush

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Flush internal HTTP stream and disconnect client; Flush HTTP stream and try sending data in chunked mode. This flushes the internal buffer where output of a VSP page is stored pending the execution of the page's code. This sends the content of the page output buffer along with headers and disconnects the client. The status is 200 OK by default, unless overridden by http_status. The purpose of this function is to allow a page to send output before terminating , thus the page can continue processing for an indefinite time without requiring the client to wait. This is useful for starting long running background tasks from HTTP clients. VSP pages that use this function must be sure to supply appropriate content (or response headers) if needed before calling this function. Virtuoso supports HTTP 1.1 Chunking Encoding which allows Virtuoso to send the user agent chunks of output as the page is still processing. Chunking is enabled by calling http_flush(1) within the VSP page. By default chunks are sent for every 4k worth of output generated, but in some cases the output needs to consist of smaller chunks, for example when run-time status needs to be shown in a status page. So to achieve this the http_flush (try_what=1) could be invoked in places where chunk must be flushed to the User agent.

Function: http_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a varchar containing the body of the request urihttp_get returns a varchar containing the body of the requested target_uri or NULL if the body is not received.

Function: http_header

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Specifies non-default HTTP response headers This function is used to add additional HTTP header lines to the server response. The http_header parameter MUST finish with characters. Warning: Each call of this function cancels the effect of the previous call. In order to add to previously set header lines, use the http_header_get function to retrieve the current headers. A Content-Type or Media-Type header specified as a part of the headers given with this function will override the default. Otherwise the header lines set using this function add to but do not replace the default response headers. Note that this function cannot set the status line. Use http_request_status for that.

Function: http_header_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns header of current HTTP request Returns the response header associated with the current HTTP request. This will not return the default header lines, only those explicitly set with http_header. This is useful for incrementally modifying response headers during processing of a URL.

Function: http_kill

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Kill VSP process whose details match parameter inputsThis function requires dba privileges. This function is used to kill the process whose details match that of the input parameters. If Client's IP and URL are specified, then it will try to kill all matching pending HTTP requests for that peer requesting that URL. If all three parameters are given, then it will try to kill only that pending HTTP request.

Function: http_listen_host

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Starts, stops and retrieves the state of a user-defined HTTP listenerThis function requires dba privileges. This function is used to start, stop or lookup the state of user-defined HTTP and HTTPS listeners. The return value is 0 or 1 and indicates state of the listener, 1 for started and 0 for stopped.

Function: http_map_table

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Update internal HTTP mapping tableThis function requires dba privileges. This function inserts an entry defining a virtual directory into the HTTP maps table.

Function: http_map_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get values from HTTP virtual host path mapping table Retrieves information associated with the virtual host / HTTP path mapping in effect for the VSP page being processed. Values valid in current connection or URL context may be retrieved by element_name. Calling http_map_get has no use outside of http context. In this case an error will be signalled.

Function: http_param

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns value of a HTML form parameter in VSP contextThis function is used to return value of a HTML form parameter in VSP context. It's almost like call get_keyword ('name', params) used in VSP programming. When 'name' parameter is not supplied, the result of http_param() call will be all parameters, as they are contained in 'params' parameter of the VSP pages. This function is useful in HTTP authentication PL hook, as in this place there is no 'params' argument.

Function: http_path

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the absolute path to the logical path location of the current http request This function returns the absolute path to the logical path location of current HTTP request.

Function: http_pending_req

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

return array describing running VSP threadsThis function requires dba privileges. http_pending_req returns an array of arrays of data on running VSP requests. Each array contains the Client IP Address, URL, and Process Request ID. These values can be used with the http_kill() function.

Function: http_physical_path

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the physical path location of the requested URL This function returns the absolute path to the physical path location of current HTTP request

Function: http_proxy

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

proxy request to another host and return content to calling client This function is used to retrieve content from a foreign host and send the response to the HTTP client of the page calling this. This is useful for re-routing a request to another server in the middle of a VSP page.

Function: http_request_header

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns array of HTTP request header lines This function provides access to the HTTP request header lines.

Function: http_request_status

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

set the status sent to the client in an HTTP response This allows a VSP page to control the status sent to the client in the HTTP response. The argument will be presented as the first line of the reply instead of the default "HTTP/1.1 200 OK". The string should not contain a CR or LF at the end. This allows a page to issue redirects, authentication challenges etc. Use it with http_headers to control the content of the HTTP reply headers.

Function: http_request_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Access to the HTTP request line This function is used to access the HTTP request line within VSP or VSPX context. It returns 'CGI' style variables for protocol version, HTTP method and query string.

Function: http_rewrite

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Clears output written to a string output or to an HTTP This clears any previous output to the stream. If the stream is omitted or 0 the stream is the HTTP client stream of the calling procedure. All output from VSP page procedures is buffered into a local string stream before being sent out. This is done so as to support the HTTP/1.1 required content length and to allow recovery from errors.

Function: http_root

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the absolute path of the server root directory.

Function: http_value

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

write to HTTP client or string output stream with HTML escapesThe http_value is used to write to an HTTP client (when in a VSP context) or a specified string output stream. http_value uses HTML-escapes for characters that should be escaped according to the HTML spec.

Function: http_url

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

write to HTTP client or string output stream with URL escapesThe http_url is used to write to an HTTP client (when in a VSP context) or a specified string output stream. http_url uses URL escapes for special characters.

Function: http_xslt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

applies an XSLT stylesheet to the output of a VSP page This function can be called inside a VSP page to apply an XSLT stylesheet to the output of the page once the page is complete. This function will return immediately and the stylesheet will not be applied until the page is successfully formed. Any errors arising in the stylesheet processing will be reported to the web client. The stylesheet does not have to be previously defined. The URI supplied will be used to locate the stylesheet. This can be a file, an HTTP URL or a virt:// URI for a stylesheet stored in a local table. Virtuoso will cache the stylesheet after first use. You can clear the cache entry with the xslt_stale() function. For this to work the text generated by the VSP page should be well-formed XML.

Function: URLREWRITE_CREATE_REGEX_RULE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates regex rules.

Function: identity_value

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the last assigned identity column valueThis function returns the value assigned to an identity column by the previous insert statement. Insert statements that do not assign identity columns do not affect this. Note that tables that have no primary key have n invisible identity column called _IDN. The scope is the connection. This function may be called from a client or from a stored procedure and will return the last given identity column value wherever it was given. The value stays set until overwritten by the next insert operation. This value is not set by rexecute or inserts to remote tables with autoincrement columns declared on the remote database since there is no standard way of getting this information from remote data sources. The same value can be more efficiently accessed from clients using the SQLGetStmtOption ODBC call with the option SQL_GETLASTSERIAL. In this case the value is of type SQLINTEGER.

Function: import_clr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function automatically creates the SQL Type wrappers based on the CLR Reflection API.This function automatically creates the SQL Type wrappers based on the CLR Reflection API.

Function: import_jar

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates SQL wrapper types of selected Java classesThis function calls the jvm_ref_import() function to produce the XML, then transforms it to a set of CREATE TYPE statements and executes them. The SQL names of the types are generated by retrieving the fully qualified name of the Java class and substituting the . with _ (e.g.: java.lang.System becomes java_lang_System). The names of the static members observer functions are composed by prepending the name of the static member with 'get' so the static Java member stat_m is mapped to a SQL static method getstat_m(). As a result it creates SQL type wrappers for the specified Java classes.

Function: initcap

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns its argument with the first letter capitalizedinitcap returns a copy of string str with the first character, if it is a lowercase letter, converted to the corresponding uppercase letter. Otherwise, an identical copy of the string is returned. Notes about ucase apply also here.

Function: internal_to_sql_type

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the integer standard SQL type of its argumentinternal_to_sql_type returns an integer value representing the standard SQL type converted from internal_type given as its argument.

Function: internal_type

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns internal integer datatype of its argumentinternal_type returns an integer value representing the internal type of its argument. These values are the same as what Virtuoso uses in the column COL_DTP of the system table SYS_COLS for keeping the track of the default types of each column of each table.

Function: internal_type_name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the internal type name of the argumentinternal_type_name returns a string which is a human-readable name for an internal_type integer given as its argument. The function dv_type_title() is an alias of internal_type_name().

Function: isarray

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Check for a valid arrayisarray is true if the argument is a valid argument to aref. This is the case for any string or vector.

Function: isblob

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is of type long varcharisblob returns one if its argument as a handle to an object of the type LONG VARCHAR, zero otherwise.

Function: isbinary

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is of type varbinaryisbinary returns one if its argument is of type VARBINARY, zero otherwise.

Function: isdouble

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true is argument is a double isdouble returns one if its argument is of type double precision float, zero otherwise.

Function: isentity

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is an XML entityisentity is true if the argument is an XML entity object, such as that returned from XPATH expressions etc.

Function: isfloat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is a floatisfloat returns one if its argument is of type single float, zero otherwise.

Function: isinteger

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is of type integerisinteger returns one if its argument is of type integer, zero otherwise.

Function: isnull

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is NULLisnull returns one if its argument is NULL, zero otherwise.

Function: isnumeric

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if argument is of numeric typeisnumeric returns one if its argument is of type integer, single float or double precision floating point number, zero otherwise.

Function: isstring

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if its argument is of type varcharisstring returns one if its argument is of type VARCHAR, zero otherwise.

Function: iszero

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns true if argument is numeric zero iszero returns one if its argument is an integer 0, a float 0.0 or a double 0.0 For any other arguments, of whatever type, it will return zero.

Function: java_call_method

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Calls a class method using the supplied parameters (if any) and returns the return value (if any). If instance_obj is supplied (not NULL) then this function searches for a non-static method otherwise for static.

Function: java_set_property

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Sets a Java class propertyAssigns a new value to either a Java class instance property referenced by instance_obj, or if instance_obj is not supplied (NULL) then sets a static Java class property.

Function: java_get_property

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Gets a property value from a Java class instance.Gets a property value from a Java class instance referenced by instance_obj. If instance_obj is not supplied, ie NULL, then it is returned as a static Java class property value.

Function: java_load_class

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Declares a Java class to a Java VMDefines a java class into the running Java VM. This is useful for loading .class/.jar/.zip files from a BLOB column or from the Virtuoso WebDAV repository.

Function: java_new_object

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates and instance of a Java class.Creates an instance of a java class, makes a global reference in the Java VM and returns it to Virtuoso as a PL object reference value.

Function: java_vm_attach

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Ensures that the current working thread is attached to the Java VM. It operates as follows: The java_vm_attach() function is called implicitly in each of the other VSEs, and also when allocating, copying or deleting a Virtuoso/PL reference to a Java VM object values. If the Java VM is already initialized and the classpath is supplied it will throw a SQL error. If the Java VM is not initialized, but it is required to execute a statement the server will implicitly call java_vm_attach (NULL);. The Virtuoso Java VM integration binary works with JDK 1.2 and later.

Function: java_vm_detach

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Detaches the current Virtuoso working thread from the Java VM.Detaches the current Virtuoso working thread from the Java VM.

Function: jvm_ref_import

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates XML description of Java classThis function will returns an XML description of the selected classes from the source files. The XML produced by the JVM_REF_IMPORT can be supplied to the predefined XSL style sheet __javavm_type to produce the CREATE TYPE statements: This can also be achieve directly using a single call to:

Function: lcase

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts string argument to lower caselcase returns a copy of string str with all the uppercase alphabetical characters converted to corresponding lowercase letters. This includes also the diacritic letters present in the ISO 8859/1 standard in range 192 - 222 decimal, excluding the character 223, German double-s which stays the same. lower is an alias for lcase.

Function: ldap_search

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Search in an LDAP server. This function performs a search in the LDAP server. It returns control to the Virtuoso/PL environment only after all of the search results have been sent by the server or if the search request is timed out by the server. The result of the search (attributes, names of the attributes, etc.) will be returned as an array result. Options to the LDAP search can be passed as an array.

Function: ldap_delete

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove a leaf entry in the LDAP Directory Information Tree. This function removes a leaf entry in the LDAP Directory Information Tree.

Function: ldap_add

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds a new entry to an LDAP directory.This function adds a new entry to the LDAP directory.

Function: ldap_modify

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Modifies an existing LDAP directory.This function modifies an existing LDAP directory entry.

Function: left

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns substring taken from left of string argumentleft returns a subsequence of string str, taking count characters from the beginning of the string. If count is zero an empty string '' is returned. If length of str is less than count then a copy of the whole str is returned.

Function: length

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get length of argumentReturns the length of its argument.

Function: LFS_EXP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Export retrieved web site to the local file systemThis function is used to export local content retrieved from a Web Robot Copy to the local file system.

Function: lh_get_handler

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns language handler

Function: lh_load_handler

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Loads given handler in global table of the server Loads given handler in global table of the server, using ISO 639 and RFC 1766 language IDs of the handler as keys for future table lookups. If another handler was already specified for given RFC 1766 id, table entry will be updated and will refer to new handler. If another handler was already specified for given ISO 639 id, it will be replaced only if new handler has ISO 639 language ID equal to its RFC 1766 ID. Please do not load custom versions of 'x-any' and 'x-ftq-x-any' handlers.

Function: locate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the starting position of the first occurrence of an substring in a string Returns the starting position of the first occurrence of string_exp1 within string_exp2. The search for the first occurrence of string_exp1 begins with the first character position in string_exp2 unless the optional argument, start, is specified. If start is specified, the search begins with the character position indicated by the value of start. The first character position in string_exp2 is indicated by the value 1. If string_exp1 is not found within string_exp2, the value 0 is returned.

Function: log

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

calculate natural logarithm of an expressionlog calculates the natural logarithm of its argument and returns it as a IEEE 64-bit float.

Function: log10

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Calculate 10-based logarithmslog10 calculates the 10-based logarithm of its argument and returns it as a IEEE 64-bit float.

Function: log_enable

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

controls transaction logging and in-statement autocommitThe log_enable function allows turning off or on regular transaction logging or autocommit after every changed row. The parameter bits is a bitmask. Two bits that are in use in current versions are 1 and 2. When bit 1 is not set (e.g. parameter value 0) then the function call terminates logging of DML statements inside the calling transaction. A value of 1 resumes logging of DML statements. If bit 2 is set then automatic commits take place after every change in every row in every DML statement. Thus a parameter value of 2 disables logging and enables row-by-row autocommit. A value of 3 enables row-by-row autocommit and enables logging. While log on and off setting alone is reset at the end of the transaction so that one does not end up with logging disabled by accident, the row-by-row autocommit mode causes the setting to be permanent inside the calling connection or web request. That is, for a SQL client the setting stays in effect until changed or disconnected and for a web request it stays in effect until the request is completed. The function do nothing if the bits is NULL. The function also do nothing when called inside atomic section. The function always returns the bitmask that describes old configuration of the log.

Function: log_text

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

inserts statements into the roll forward logThe log_text function can be used to insert a SQL statement into the roll forward log. The log_text function causes the SQL text given as first argument to be executed at roll forward time with the following arguments as parameters, bound from left to right to the parameter markers in the statement ('?'). There can be a maximum of 8 parameters but these can be arrays.

Function: lower

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a lower case version of its argument lcase returns a copy of string str with all the uppercase alphabetical characters converted to corresponding lowercase letters. This includes also the diacritic letters present in the ISO 8859/1 standard in range 192 - 222 decimal, excluding the character 223, German double-s which stays the same. lower is just an alias for lcase.

Function: ltrim

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

removes specific characters from a stringltrim returns a copy of subsequence of string str with all the characters present in trimchars trimmed off from the beginning. If the second argument is omitted, it is a space ' ' by default. rtrim is similar except that it trims from the right. trim trims from both ends.

Function: make_array

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a new arrayThis returns an array of length elements with the content element type. The initial content of the array is undefined.

Function: make_string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

make a stringmake_string returns a new string of length count, filled with binary zeros. If count is zero, an empty string '' is returned.

Function: md5

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the md5 checksum of its argumentmd5 calculates the MD5 checksum of its argument. The md5 message digest algorithm is defined in RFC1321.

Function: md5_init

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the string serialization of a new md5 context This function initializes an MD5_CTX, converts it into varchar form and returns this representation. Should be used with md5_update/md5_final.

Function: md5_update

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the updated md5 context serialized as varchar This function updates MD5_CTX with data parameter and returns the (deserialized from ctx parameter) updated context.

Function: md5_final

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the md5 checksum given an initialized md5 contextThis function finalizes the MD5_CTX and returns the final checksum.

Function: mime_body

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

used to compose multipart/mixed MIME message bodyThe mime_body() procedure is used to compose a multipart/mixed MIME body. it takes only one parameter, mime_parts, an array of mime_part elements such as those produced by the mime_part() function.

Function: mime_part

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

used to compose a MIME message body part.This function is used to make a MIME part that can be used with the mime_body() function.

Function: mime_tree

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

parses MIME messages into an array structure This function is intended to parse MIME (RFC2045) messages (coming from a RFC822 or HTTP sources). It parses the text and produces an array structure representing the structure of the MIME message. It copies into the structure MIME headers, but for the MIME bodies it only stores start and end offsets, thus optimizing space usage. The parameters to mime_tree are: If flag is 1, the "root" message follows RFC822. This means mime_tree will unfold the attributes, will scan for MIME registered header fields and will take their attributes. Alternately this can be a MIME message which needs no unfolding and has attributes separated with semicolon.

Function: minute

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get minute from a datetimeminute takes a datetime and returns an integer containing a number representing the minute of the datetime.

Function: mod

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the modulus of its argumentsmod returns the modulus (i.e. remainder) of the division dividend/divisor. If the divisor is zero the SQL error 22012 "Division by zero" is generated.

Function: month

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get number of month from a datetimemonth takes a datetime and returns an integer containing a number representing the month of year of the datetime.

Function: monthname

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get name of month from a datetimemonthname takes a datetime and returns a string containing name of the month represented by the datetime

Function: msec_time

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get number of milliseconds from system epochmsec_time returns the number of milliseconds since system epoch. It is useful for benchmarking purposes, timing operations, etc.

Function: mts_connect

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

connects Virtuoso server to MS DTC. If reconnect flag is set to non-zero value then forces Virtuoso to connect even it have been connected already. Returns zero if succeeds. If MS DTC service is not available (W2K) or MTS is not running (NT4.0) signals error with code "MX000".

Function: mts_get_timeout

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns timeout of distributed transaction in milliseconds.

Function: mts_set_timeout

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

sets timeout of distributed transaction. sets distributed transactions timeout. 'timeout' parameter indicates amount of timeout in milliseconds. If it equals -1 then default timeout of Virtuoso transaction is used (SQL_QUERY_TIMEOUT). This function must be called directly after "SET MTS_2PC=1". The time countdown begins at moment of changing first branch.

Function: mts_status

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

checks status of current transaction or server. Checks status of subject. Subject can be either 'MTS' or 'TRANSACTION'. In the first case this checks if the server is connected to MTS. In the second case, checks if 2pc control is enabled for the current transaction. This function returns status string. For 'MTS' it could be either 'connected' or 'disconnected'. For 'TRANSACTION' - either '2pc enabled' or '2pc disabled'.

Function: name_part

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns portion of dotted name such as a fully qualified table name.The name_part() can be used to dissecting parts of a three part names (string where items are divided by dots ".") such as table names or columns names. The table name "DB"."DBA"."SYS_USERS" contains three parts which can be extracted individually using this function providing the correct index from a 0 base: 0 would return "DB", 1 would return "DBA", 2 would return "SYS_USERS".

Function: nntp_auth_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns information about an NNTP server with authorizationThe nntp_auth_get() is used to retrieve messages from a server requiring authorization. See nntp_get for more information.

Function: nntp_auth_post

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Post message to NNTP server with authorization Nntp_auth_post is used to post a message to the server require authorization.

Function: nntp_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns information about an NNTP server. nntp_get() is used to retrieve messages from a server running the Network News Transfer Protocol (NNTP) as defined in RFC977. It returns an array whose structure depends on the command parameter, thus:

Function: nntp_post

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Post message to NNTP server Nntp_post is used to post a message to the server running the Network News Transfer Protocol as defined in the rfc977.

Function: now

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the current transaction timestamp Now returns the timestamp associated with current transaction as a DATETIME. This value is guaranteed to differ from the timestamp of any other transaction.

Function: os_chmod

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

changes the file access mode of a fileos_chmod set the file mode bits by calling the system function chmod() with the arguments supplied. Not all the host OSes support all the file modes. That's why the function will not throw an SQL error if the function fails. It will return DB NULL value when the function was called successfully and the error message as a string if it failed.

Function: os_chown

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

changes the owning group/user of a fileThis function requires dba privileges. os_chown set the owning user/group of an OS file by calling the system function chown() with the arguments supplied. Not all the host OSes support the concept of owner users and groups. That's why the function will not throw an SQL error if it fails.

Function: pem_certificates_to_array

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

converts a PEM file to an array of PEM stringsThis gets a PEM file with (possibly) many X509 certificates among others and constructs an array containing each X509 certificate as a separate PEM string. This can serve for splitting a PEM file containing multiple certificates (for example CA file) to single certificate entries so it can be examined with get_certificate_info function. Note that the array can contain NULL elements in places where in the PEM file there are blocks other than X509 PEM certificates.

Function: pldbg_stats

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Makes an array of line/count information based on current coverage.This function is used to make an array of line/count information based on the current coverage statistics. If the procedure name is given (first param), then the result will contain only coverage statistic for that procedure. if the procedure name is not supplied or supplied as NULL then the result will contain coverage data for all procedures having statistic. The add_line_info flag is used to add code excerpt on line info.

Function: pldbg_stats_load

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Used to load a coverage of a single procedure record as an array.This function is used to load coverage information for a single procedure record. The expected format is an array. The data expected is exactly that which can be produced by pldbg_stats(). Only one record will can be accepted, an array of several procedure records will not be acceptable.

Function: pop3_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get messages from a POP3 serverPop3_get is used to retrieve and delete messages from a server running the Post Office Protocol version 3 as defined in rfc1725. In its default form it returns a vector of vectors containing messages retrieved from the POP3 server. Each vector within the vector contains a pair of VARCHAR UIDL and VARCHAR Message body, i.e. to get the message body of the second message retrieved, one would use aref (aref (msg_vec, 1), 1). Total length of messages retrieved will not exceed the value of buffer_size parameter in bytes. The optional parameter command can be used to control output or delete messages. When command is passed a VARCHAR 'uidl', pop3_get outputs single vector containing VARCHAR UIDLs. The buffer_size constraint is effective here. Thus, the vector will only contain UIDLs of messages whose total message text length does not exceed buffer_size bytes. These message lengths are accumulated in the order returned by the POP3 server. Command 'delete' will cause retrieved messages to be deleted from the server after retrieval.

Function: position

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the index of an element within an array or stringposition returns the one-based index for the first occurrence of element within an array or string, beginning from offset start_index and iterating with step. If the second argument is a string, the first argument must be a string with a single character. If the second argument is an array of any, then depending of type of it's elements same type is expected as the first argument.

Function: power

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

return value of expression raised to specified power.power raises x to the yth power and returns the value as a IEEE 64-bit float.

Function: prof_enable

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Control virtuoso profilingprof_enable is used to enable or disable profiling of execution times, SQL statements and web requests. Passing flag value 1, enables profiling, causing times of statement executions, which begin and end while profiling is on, to be accumulated. When called with a flag of 0, the accumulation is stopped and results gathered so far are written into file named virtprof.out in the server's working directory. For a description of the file, see section about SQL Execution Profiling in Performance tuning part of Virtuoso documentation.

Function: prof_sample

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds a profiling sample to a profile being accumulated.prof_sample is used to adds a profiling sample to a profile being accumulated. The first argument is the name of the sampled section, the times called and cumulative times will be totaled under this heading. The second argument is the time in milliseconds. The third argument is a flag indicating whether the section was successfully executed. 0 indicates success, 1 indicates execute of the statement, 2 indicates fetch on a statement's resultset, 4 indicates error. For more description of profiling capabilities see the section about SQL Execution Profiling in Performance tuning part of Virtuoso documentation.

Function: quarter

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get number of quarter of year from a datetimequarter takes a datetime and returns an integer containing a number representing the quarter of year of the datetime.

Function: quote_dotted

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns an quoted identifier.The quote_dotted() function will return the identifier (table name or column name) appropriately quoted for the remote data source. This function will obtain the appropriate quote characters from the remote data source. This function can be used in conjunction with rexecute function.

Function: randomize

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

initializes the random number generator The rnd function returns a random number between zero and n - 1, inclusive. randomize initializes the random number generator. The random number generator is initialized after the clock at first usage, so the produced sequences will be different each time unless specifically initialized.

Function: rclose

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Closes cursor created by rexecute()Closes the cursor opened to a remote DSN by the rexecute() function.

Function: regexp_match

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a substring matching the regular expression to the supplied string The regexp_match function returns a copy of substring of string str which matches the regular expression pattern. Previous behavior of this function would cut the first characters of str until the end of regular expression matched substring. In this way str could be passed to this function again to find the next occurrence of substring that matches the regular expression. By default this behavior is not adopted by this function, but can be enabled for pre 3.2 compatibility by supplying the optional third parameter. If either the pattern or str parameter contain wide characters this function will operate in wide mode, first converting any narrow characters to wide and returning a wide character response. Otherwise this function operates in narrow mode by default.

Function: regexp_parse

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns substrings that match the regular expression in supplied string after an offset It applies regular expression to target_str with offset. This function returns a vector containing 2 elements for first match of the pattern and if there a sub expressions : 2 elements for each of subexpression match. The first (even numbered) element of each pair is the start index and the second (odd numbered) is the end index of the match. The regexp_parse function is more efficient than regexp_match and regexp_substr, because it doesn't allocate strings. Where: 2-14 is a range matched by whole expression, 2-4 is a range where '(2[34])' is matched , and 12-14 is a range where '(2[35])' subexpression matched.

Function: regexp_substr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a single captured substring from matched substringThis function will return the whole string value of the first substring in "str" that matches the regexp in "pattern" or a sub part of the first match. The regexp syntax allows subexpressions to be marked in the regular expression (using the braces syntax). An example of such type of expression will be: '(2[34]).*(2[35])' which means a regular expression having two subexpressions: '2[34]' and '2[35]'. Let's apply the above regexp to the following source string: 22232225222323 This returns the hole matched string from the expression.

Function: DB.DBA.RDF_AUDIT_METADATA

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Fix RDF metadata corruption.This function can detect and automatically fix most popular sorts of metadata corruption.

Function: DB.DBA.RDF_BACKUP_METADATA

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Makes a backup copy of RDF metadata (i.e., descriptions of RDF Views and the like). This saves all RDF metadata to file or to some graph in RDF storage, depending on first argument (nonzero for file, zero for graph). If the function gets nonzero as first argument then it creates two files, called, say, 'example.ttl', and 'example-DEBUG.ttl'. It's enough to save only the former file in order to restore metadata later, but the latter contains important additional debug information so both files should be attached to any bug report related to RDF metadata. There are no functions to make copies of backups. File backup consists of plain TURTLE RDF files only. Backup graph is just a regular RDF graph in the default storage so it can be serialized into a file or copied into other graph. However it is important to remember that the system graph, whose name is returned by JSO_SYS_GRAPH() stored procedure, should not be edited directly. The content of the system graph is not necessarily equal to the content of a backup graph and it should be touched only by API function calls.

Function: DB.DBA.RDF_VOID_STORE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Collects statistics for a given graph and saves it.Collects statistics for the first given graph and saves the result into the second graph. For correct results, the first graph should be loaded in the database before executing the function.

Function: DB.DBA.RDF_RESTORE_METADATA

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Restores RDF metadata (descriptions of RDF Views and the like) from previously saved backup.This restores RDF metadata from specified file or graph in RDF storage. The file or graph should be previously created by DB.DBA.RDF_BACKUP_METADATA(). It is usually safe to restore metadata from backup made by some previous version of Virtuoso server but it is good idea to call DB.DBA.RDF_AUDIT_METADATA() after such restore. When the procedure is executed on the server that continues to serve user requests during the maintenance then SPARQL query compiler may interrupt query compilations or create queries that will return incomplete result sets. These queries may be cached till the end of metadata update procedure but the cache is flushed when the update is complete, so possible errors will be transient. If even transient errors are not appropriate then do RDF metadata update with all precautions usual for changing database schema of an application.

Function: DB.DBA.RDF_LOAD_RDFXML_MT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Parses the content of large RDF/XML text as a sequence of separate RDF triples.For loading large resources when transactional integrity is not important (loading of a single resource may take more than one transaction). The function may or may not leave a transaction log, depending on log_mode. Hence, after successful load, one may need to execute the checkpoint statement to make sure that a server restart does not wipe out the results.

Function: DB.DBA.RDF_LOAD_RDFXML

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Parses the content of RDF/XML text as a sequence of separate RDF triples.

Function: DB.DBA.TTLP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

parses TTL (TURTLE or N3 resource) and places its triples into DB.DBA.RDF_QUAD.Parses TTL (TURTLE or N3 resource) and places its triples into DB.DBA.RDF_QUAD.

Function: DB.DBA.TTLP_MT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

parses TTL (TURTLE or N3 resource) and places its triples into DB.DBA.RDF_QUAD on multiple threads.Loads the TTL (TURTLE or N3 resource) file on multiple threads, using parallel I/O and multiprocessing if available. The function commit partial transactions while it runs so the transaction log may contain part of loading. Moreover, the function may or may not leave a transaction log, depending on log_mode. Hence, after successful load, one may need to execute the checkpoint statement to make sure that a server restart does not wipe out the results.

Function: DB.DBA.TTLP_MT_LOCAL_FILE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Function: DB.DBA.RDF_TRIPLES_TO_RDF_XML_TEXT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Serializes vector of triples into a session, in RDF/XML syntax.Serializes vector of triples into a session, in TURTLE syntax. In current version, every triple is printed in separate top-level record (say, in rdf:Description tag), without any pretty-print or nesting optimization.

Function: DB.DBA.RDF_TRIPLES_TO_TTL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Serializes vector of triples into a session, in TURTLE syntax.Serializes vector of triples into a session, in TURTLE syntax. In current version, every triple is printed in separate top-level record (say, in rdf:Description tag), without any pretty-print or nesting optimization.

Function: DB.DBA.RDF_64BIT_UPGRADE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Alters IRI_ID columns to get IRI_ID_8.There are two data types. IRI_ID is 4-byte and IRI_ID_8 is 8-byte. Initially, IRI_ID columns are created. DB.DBA.RDF_64BIT_UPGRADE() alters them to get IRI_ID_8. Note that this is to hold more that 4G of distinct IRIs, number of distinct quads is not limited by 4G even without the upgrade. The function should be called once.

Function: DB.DBA.RDF_CONVERT_RDFXML_TO_TTL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts rdf xml to ttl.Converts rdf xml to ttl.

Function: rdfs_rule_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds the applicable facts of the graph into a rule set.This function specifies a logical name for the rule set plus a graph URI. It is possible to combine multiple schema graphs into a single rule set. A single schema graph may also independently participate in multiple rule sets.

Function: DB.DBA.ANN_PHRASE_CLASS_ADD

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns APC_ID of a phrase class.The returned value is APC_ID of a class if positive or an error code if negative. To update phrase class, no special DB.DBA.ANN_PHRASE_CLASS_UPDATE() exists, use DB.DBA.ANN_PHRASE_CLASS_ADD() with parameter "mode" equal to 'replacing'.

Function: DB.DBA.ANN_PHRASE_CLASS_DEL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Deletes phrase set.The returned value is APS_ID of a deleted phrase set if positive or an error code if negative. A phrase set can not be deleted while used by some advertiser (as described here).

Function: AP_BUILD_MATCH_LIST

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns report of all occurrences of phrases from the specified sets in the text.Forms a report that lists all occurrences of phrases from the specified sets in the text. The report describes "phrase hits", i.e. occurrences of annotation phrases in the text, using "arrows" that point to specific fragments in the text, such as words of found phrases or HTML tags. The structure of the report is complicated, due to contradiction in requirements. It is compact to provide reasonable performance and scalability, so common data should not be repeated, saving memory. It is complete enough to prevent application from reading omitted data from system tables, saving time.

Function: AP_ADD_PHRASES

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds phrases to given set.The function gets two arguments, the integer ID of annotation phrase set and a vector of $ descriptions of phrases that should be edited in that phrase set. Every item of vector of descriptions is in turn vector of one or two values; first value is the text of the phrase, second value is associated application specific data, the absence of second value indicates that the phrase should be removed. If same text of phrase appears in the vector of description more than once, and associated data differ then any version of data can be stored for future use; it is the roll of dice because the vector is reordered for faster processing.

Function: iri_split

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Splits into the namespace prefix and the local part according to the TTL rules.Iri is a qualified name. It is split into the namespace prefix and the local part according to the TTL rules. The prefix is returned. If a second argument is given, it is set to the local part.

Function: __xml_get_ns_prefix

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns prefix by given URI.If str is a globally known namespace URI, its prefix is returned, else null. Flags is a bit mask where 1 means to look in the connection, 2 in the global set of known prefixes.

Function: __xml_get_ns_uri

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns URI by given namespace prefix.If str is a globally known namespace prefix, its URI is returned, else null. Flags is a bit mask where 1 means to look in the connection, 2 in the global set of known prefixes.

Function: DB.DBA.SPARQL_EVAL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Local execution of SPARQL via SPARQL protocol, produces a result set of SQL values.Local execution of SPARQL via SPARQL protocol, produces a result set of SQL values.

Function: DB.DBA.SPARQL_EVAL_TO_ARRAY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Local execution of SPARQL via SPARQL protocol, produces a vector of vectors of SQL values.Local execution of SPARQL via SPARQL protocol, produces a result set of SQL values.

Function: DB.DBA.SPARQL_REXEC

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remote execution of SPARQL via SPARQL protocol, produces a result set of SQL values.Remote execution of SPARQL via SPARQL protocol, produces a result set of SQL values.

Function: DB.DBA.SPARQL_REXEC_TO_ARRAY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remote execution of SPARQL via SPARQL protocol, produces a vector of vectors of SQL value.Remote execution of SPARQL via SPARQL protocol, produces a vector of vectors of SQL value.

Function: DB.DBA.SPARQL_REXEC_WITH_META

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remote execution of SPARQL via SPARQL protocol. Fills in output parameters with metadata (like exec metadata) and a vector of vector s of 'long valmode' values.Remote execution of SPARQL via SPARQL protocol. Fills in output parameters with metadata (like exec metadata) and a vector of vector s of 'long valmode' values.

Function: DB.DBA.RDF_REGEX

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns 1 if string s matches pattern p, 0 otherwise.Returns 1 if string s matches pattern p, 0 otherwise

Function: DB.DBA.RDF_LANGMATCHES

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns 1 if language identifier r matches lang pattern t.Returns 1 if language identifier r matches lang pattern t

Function: DB.DBA.RDF_TTL2HASH

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a dict of triples in 'long valmode'.Returns a dict of triples in 'long valmode'.

Function: DB.DBA.RDF_QUAD_URI

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Performs simple insertion of a quad where object is a node.Performs simple insertion of a quad where object is a node. The arguments g_uri, s_uri and p_uri should be IRI strings or IRI_IDs. All string arguments should be in UTF-8 encoding, otherwise they will be stored but are not queryable via SPARQL.

Function: DB.DBA.RDF_QUAD_URI_L

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Performs simple insertion of a quad where object is a literal value in 'SQL valmode'.Performs simple insertion of a quad where object is a literal value in 'SQL valmode'. The arguments g_uri, s_uri and p_uri should be IRI strings or IRI_IDs. All string arguments should be in UTF-8 encoding, otherwise they will be stored but are not queryable via SPARQL.

Function: DB.DBA.RDF_QUAD_URI_L_TYPED

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Performs simple insertion of a quad where object is a literal value in 'SQL valmode' and can be specified datatype and language.Performs simple insertion of a quad where object is a literal value in 'SQL valmode' and can be specified datatype and language. The arguments g_uri, s_uri and p_uri should be IRI strings or IRI_IDs. All string arguments should be in UTF-8 encoding, otherwise they will be stored but are not queryable via SPARQL.

Function: regexp_replace

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Replaces occurrence(s) of the matching pattern in the source_string with a specified replace_string.This function replaces occurrence(s) of the matching pattern in the source_string with a specified replace_string, allowing complex search-and-replace operations. The traditional REPLACE SQL function substitutes one string with another. Assume your data has extraneous spaces in the text and you would like to replace them with a single space. With the REPLACE function, you would need to list exactly how many spaces you want to replace. However, the number of extra spaces may not be the same everywhere in the text.

Function: regexp_instr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the first position of the occurrence of a regular-expression pattern in a given string.This function looks for a pattern and returns the first position of the pattern. Optionally, you can indicate the start_position you want to begin the search. The occurrence parameter defaults to 1 unless you indicate that you are looking for a subsequent occurrence. The default value of the return_option is 0, which returns the starting position of the pattern; a value of 1 returns the starting position of the next character following the match. This function returns the starting position of a pattern, so it works much like the familiar INSTR function. The main difference between the two functions is that REGEXP_INSTR lets you specify a pattern instead of a specific search string; thus providing greater versatility.

Function: regexp_like

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Allows a like comparison using regular-expression.The source_string supports character datatypes (CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2, and NCLOB but not LONG). The pattern parameter is another name for the regular expression. match_parameter allows optional parameters such as handling the newline character, retaining multiline formatting, and providing control over case-sensitivity.

Function: registry_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a current value of a registry settingregistry_get is used to retrieve values stored within database registry.

Function: registry_get_all

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a vector of all registry settingsThe function returns a vector of even length that contains two elements for every registry setting that is now stored in the database: the name and the current value of the setting. The order of 'name-value' pairs in the resulting vector may vary from call to call. To search such a vector by a setting name, the vector can be passed as a second argument to the function get_keyword(). The returned vector is a full copy of the content of the registry. To change the actual registry, use registry_set.

Function: registry_name_is_protected

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The function checks if a given registry variable is read-only or protected from occasional changes.Some registry variables are used solely by internal server routines so they should not be changed by any application. Some of these "protected" variables can be updated by DBA only (in built-in Virtuoso/PL routines) whereas some can not be updated by any Virtuoso/PL routine at all. The function gets a variable name as a parameter and returns zero if such a variable variable can be created/modified/removed by any application, one if a variable can be modified by DBA but can not be removed and two if the variable can not be altered even by DBA. The returned value does not indicate that the variable exists or not exists. The name of not yet existing variable can be protected anyway to prevent future misuse of an variable by an application.

Function: registry_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Associates a value to the name in the Database registryThis associates a value to the name in the Database registry. The name should be a string and the value must be also string. Registry settings are kept in Database, therefore they are persistent. Some registry variables are used solely by internal server routines so they should not be set by any application. Some of these "protected" variables can be updated by DBA only (in built-in Virtuoso/PL routines) whereas some can not be updated by any Virtuoso/PL routine at all. If the function is called by DBA then a third argument can be specified to indicate how the function should try to update such a variable, but you will probably never use this feature.

Function: registry_remove

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove a variable from registryThe function removes a given variable from registry, so future calls of registry_get returns zero. Some registry variables are used solely by internal server routines so they should not be changed by any application. Nobody can remove such a "protected" variable even if some of them can be updated by DBA.

Function: repeat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a new string consisting of its string argument repeated a given number of times repeat returns a new string, composed of the string str repeated count times. If count is zero, an empty string '' is returned.

Function: replace

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This replaces every occurrence of the second argument in the first argument with the third argument. This replaces every occurrence of the second argument in the first argument with the third argument. The arguments can be narrow or wide strings.

Function: replay

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

starts the roll forward of the given logThis starts a roll forward of the given log. The log may have been produced by normal transaction logging, backup or crash dump. Logs may not be transferred between databases and thus cannot be rolled forward anywhere except on the database that generated them. This function is for example useful after restoring a backup. It should be called for each archived transaction log produced since the backup, including and starting with the one that was current when the backup was made. The operation blocks until the roll forward is complete. Other clients are not affected.

Function: repl_disconnect

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

terminates communication with a replication publisher This terminates any communication with the publisher. Any pending synchronization communication is disconnected and all subscribed publications are marked as 'OFF'. The effect is reversed on a subscription by subscription basis by calling repl_sync for each.

Function: REPL_GRANT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

grant privileges for subscription to a publicationThis function is used to grant privilege for subscription to a SQL account for particular publication. The DBA accounts always have right for subscription to all available publications.

Function: REPL_INIT_COPY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create initial subscription state This function is called on the subscriber to copy the current state of the elements of the publication from the publishing server. Copied data can include DAV collections, tables, procedures etc. Syncing the subscription using repl_sync will synchronize the subscription once it has been initialized with this function. The state copied corresponds to the state of the published data as of the last checkpoint completed on the publisher.

Function: repl_new_log

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create new publication log This function switches to a new file for logging data for the publication. If the file is NULL a new file name will be generated based on the previous file name by appending or replacing a datetime field in the file name.

Function: REPL_PUBLISH

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create publication on publisher This function starts a publication and associates a file system file to it. The file will be used to log transaction records associated to the publication. The server will periodically start new files, so that replication log files do not grow indefinitely. New files will go to the same directory as the initial one and will have names suffixed with the date and time of their creation.

Function: REPL_PUB_ADD

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

add item to a publicationThis function is used to add items to a pre-existing publication and to set replication options for the published items. Operations concerning the added item will henceforth be logged into the publication's log. Performing this operation will copy the item and optionally its definition to existing subscribers.

Function: REPL_PUB_INIT_IMAGE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create initial image of publication on publisherThe image creation process forces checkpoint and runs in atomic mode. If image_file_path does not contain path components (slashes or backslashes), image slices are stored in one of backup directories defined in virtuoso.ini using round-robin strategy. This function is used to create image of publication to be replayed on a subscribed upon initial setup. This can be used when publication data is so large to be copied via repl_init_copy() which uses VDB operations. The image file(s) created by this function must be loaded on subscriber with replay() function in order of their creation (if image is split on to a several files).

Function: REPL_PUB_REMOVE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

remove item from publication.This function is used to remove an item from existing publication. It's action is performed on publisher side and depending of flag it can send replication message to subscribers to remove this from subscription.

Function: REPL_REVOKE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

revoke privileges for subscriptionRevokes Privileges for Subscription. This is called on the publisher to revoke access to the publication from the user account on the publisher. The subscriber will no longer gain access to the publication with this account.

Function: REPL_SCHED_INIT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

adds scheduled job to synchronize subscriptionsAdds scheduled job to synchronize all subscriptions. The server will attempt to start synchronization of all non-synchronized subscriptions at a 1 minute interval. The action can be reversed by deleting the corresponding row from the SYS_SCHEDULED_EVENTS table.

Function: REPL_SERVER

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

defines a server that will participate in replicationThis function defines a server that will participate in replication. The name is a symbolic name that should match the name specified as the ServerName configuration parameter in the replication section of the virtuoso.ini file of the server being defined. The address is the where the server designated by the name is listening. The DSN is an ODBC data source name referring to the server, so that the subscriber can retrieve schema and other information. Note that replication communication itself does not take place through ODBC but that ODBC access to the publisher is required to initiate the subscription. In order to subscribe to publications from a server the server must first be declared with this function. If this function is called to define the local server, i.e. the given server name is the ServerName in the Replication section of the local ini file the function has no effect.

Function: repl_server_rename

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

rename the publishing server instance This function is useful to rename the publishing servers data (that stored in to the replication tables) after renaming the server in virtuoso.ini file. The call of the procedure will associate the all data belong to the old server name to the current server name. It will also set the appropriate transaction levels. In case of duplicate publications (publications with the same name exists in old and new server definitions) it will reject the operation.

Function: REPL_STAT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

retrieve status of all subscriptions and publicationsRetrieves status of all subscriptions and publications. This function is for interactive use (via ISQL tool).

Function: repl_status

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns status of a published or subscribed publicationGiven a publisher and publication name this returns the status of the publication on the local server.

Function: REPL_SUBSCRIBE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

add a subscriptionThis function is used to subscribe to an existing publication, and to specify the local WebDAV owner for replicated WebDAV content. Before making a subscription the repl_server() function must be called in order to define the publishing server. After making a subscription it becomes off-line awaiting synchronization from a scheduled task or call to the repl_sync() function. Also the initial data of the subscription will be not loaded until repl_init_copy() is called or the initial image has been loaded.

Function: repl_sync

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

starts the syncing process against an existing subscription This starts the syncing process against an existing subscription. The function returns as soon as the request has been successfully sent. The synchronization will take place in the background. If the syncing process is already underway or if the subscriber is already in sync and connected to the publisher this function has no effect. If there is no connection to the publisher at the time of calling this function and the connection fails and an error is immediately signalled. To initiate a synchronization a valid SQL account must be specified. Also the account must have rights to the publication unless publisher DBA's account is used to connect.

Function: repl_sync_all

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

synchronize all subscriptionsThis function is used to synchronize all subscriptions. It make a synchronization requests to the all publisher and will return immediately after that. The status of subscriptions can be tested with repl_stat() function.

Function: repl_text

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

adds a SQL statement to the log of the replicationThis SQL function adds the SQL statement to the log of the publication. The statement will typically be a procedure call but can be any SQL statement. There can be a parameters, which are bound to ?'s in the statement's text from left to right. There is no restriction on the number of parameters.

Function: repl_this_server

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns calling servers name

Function: REPL_UNPUBLISH

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

drop publication on publisher This function is used to remove from current replication set an existing publication. The replication messages for all existing items will be stopped, so the last replication message will instruct the subscribers that this publication is dropped. On subscriber side depending of the copy mode of items they can be removed or not, but the description entry for that publication will be removed explicitly. Any existing grants to the publication being dropped will be revoked.

Function: REPL_UNSUBSCRIBE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

drop subscriptionThis function is used to stop receiving a replication messages from a publisher server for a item or whole subscription. It will be invoked automatically when a publication is dropped. The subscriber can also invoke this function to stop receiving replication messages. The existing items can be dropped or not depending on the copy mode flag. The description entries for that subscription will be removed. There is no "undo" ability. To temporally halt the replication messages you can use repl_disconnect().

Function: repl_purge

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

purges transactional replication logs for specified account This procedure purges transactional replication logs for specified account. Logs whose start replication level lags more than REPL_MAX_DELTA (1000000000) transactions behind current replication level of a specified account are removed. After repl_purge() is finished next repl_purge() run is scheduled using SYS_SCHEDULED_EVENT facility. Account sync requests from subscribers are delayed while repl_purge() is running for this account.

Function: REPL_CREATE_SNAPSHOT_PUB

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Create bi-directional snapshot publicationThis procedure should be used to create a bi-directional snapshot publication. If the item parameter is a table then this procedure creates an updateable snapshot log and generates an updating procedure.

Function: REPL_CREATE_SNAPSHOT_SUB

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Create bi-directional snapshot subscription to an existing publication.This procedure should be used to create a bi-directional snapshot subscription.

Function: REPL_DROP_SNAPSHOT_SUB

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Drops a subscription to a bi-directional snapshot publicationThis procedure drops a subscription to a snapshot publication.

Function: REPL_DROP_SNAPSHOT_PUB

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Drop bi-directional snapshot publicationThis procedure drops a snapshot publication.

Function: REPL_INIT_SNAPSHOT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Initializes a bi-directional snapshot publicationThis procedure should be used to initialize a bi-directional snapshot publication. Note: This function should be run on publisher.

Function: REPL_UPDATE_SNAPSHOT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Updates a bi-directional snapshot publicationThis procedure should be used to update a bi-directional snapshot publication. This procedure pulls all the updates from subscribers (with conflict resolution) and then pushes all the updates from publisher to all the subscribers.

Function: REPL_SNP_SERVER

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Define bi-directional snapshot replication server nameThis function should be used to define a server for bi-directional snapshot replication.

Function: REPL_SERVER_NAME

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Return bi-directional snapshot replication server name for specified DSNThis function should be used to determine bi-directional snapshot replication server name.

Function: REPL_ADD_CR

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates conflict resolver for bi-directional transactional replicationSimple conflict resolvers can be generated by calling this function.

Function: REPL_ADD_DAV_CR

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates conflict resolver for bi-directional replication in DAVSimple conflict resolvers for DAV bi-directional replication can be generated by calling this function.

Function: REPL_ADD_SNAPSHOT_CR

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates conflict resolver for bi-directional replicationSimple conflict resolvers can be generated by calling this function.

Function: result

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Sends one row of results to the calling client.The result_names() predefines variables to be used in a result set to follow. The variables must be previously declared, from which the column data types are ascertained. This assigns the meta data but does not send any results. The result() function sends its parameters as a single row of results. These parameters should be compatible with those in the previous result_names(). The end_results() function can be used to separate multiple result sets. The result_names() can then be used to alter the structure of the next result set. The result_names() call can be omitted if the application already knows what columns and their types are to be returned.

Function: result_names

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The result_names() predefines variables to be used in a result set to follow. The variables must be previously declared, from which the column data types are ascertained. This assigns the meta data but does not send any results. The result() function sends its parameters as a single row of results. These parameters should be compatible with those in the previous result_names(). The end_results() function can be used to separate multiple result sets. The result_names() can then be used to alter the structure of the next result set. The result_names() call can be omitted if the application already knows what columns and their types are to be returned.

Function: rexecute

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

execute a SQL statement on a remote DSNThis function can be used to execute SQL on a remote data source directly. The result_set parameter is useful for obtaining a result-set quickly and easily. However, if the result-set is going to be large, this comes at a cost in terms of time and resources, particularly memory, since Virtuoso will have to obtain all results from the statement and build the result-set arrays in memory before returning back to the caller. A more efficient way is to obtain a cursor handle and iterate through the result set one row at a time:

Function: rstmtexec

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

execute a SQL statement on a remote DSN, provides a result set where applicable.This function can be used to execute SQL on a remote data source directly. It returns a result set where one is expected. This function is wrapper for the rexecute() provided for convenience as a shortcut. Unless explicitly granted, only the DBA group is permitted to use the rstmtexec() to maintain security. Caution is required here since any user granted use of rstmtexec() has full control of the remote data source set-up by the DBA, albeit limited to the overall abilities of the remote user on the remote data source. Users can be granted and denied access to this function using the following commands:

Function: right

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get n rightmost characters of a stringright returns the count rightmost characters of string str. If count is zero an empty string '' is returned. If length of str is less than count then a copy of the whole str is returned.

Function: rmoreresults

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

move to next result set of rexecute()This function moves to the next result set when handling result sets returned by statement executed with rexecute.

Function: rnd

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a random number between 0 and n - 1 inclusive The rnd function returns a random number between zero and n - 1, inclusive. randomize initializes the random number generator. The random number generator is initialized after the clock at first usage, so the produced sequences will be different each time unless specifically initialized.

Function: rnext

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get next result from a remote result setUse rnext in combination with rmoreresults to iterate over a result set produced by a statement run in a remote data source with rexecute.

Function: row_count

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns number of rows affected by the previous DML statement in a procedure bodyThis function returns the count of rows affected by the previous DML statement in a procedure body. The scope is local to the procedure. Calling this from ODBC will always return 0. This is the PL equivalent of the SQLRowCount ODBC function. The count is set after any in-line searched or positioned update, insert or delete. This is also set by the exec function. The count stays set until overwritten by the next DML operation. This is not set by rexecute.

Function: rtrim

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

trims given characters from right of given string ltrim returns a copy of subsequence of string str with all the characters present in trimchars trimmed off from the beginning. If the second argument is omitted, it is a space ' ' by default. rtrim is similar except that it trims from the right. trim trims from both ends.

Function: search_excerpt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns excerpts with hit words from textThis function produces representative samples for use in displaying a query hit. There are two modes: html mode and text mode. In html mode everything looks like html tags is ignored and searching of excerpt begins from tag. All found hit words highlighted by html_hit_tag. In text mode text is treated as plain text, html tag detection is disabled and hit words is not highlighted.

Function: second

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get second from a datetimesecond takes a datetime and returns an integer containing a number representing the second of the datetime.

Function: sequence_get_all

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a vector of states of all sequence objectsThe function returns a vector of even length that contains two elements for every sequence object that is now stored in the database: the name and the current state. The order of 'name-state' pairs in the resulting vector may vary from call to call. To search such a vector by a setting name, the vector can be passed as a second argument to the function get_keyword(). Changes in the returned vector will not alter sequence objects of the database. To change actual sequence objects, use sequence_set().

Function: sequence_next

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the current state of the specified sequence and increments it by one.This function returns the current state of the specified sequence and atomically increments it by one. The next call will thus return a number one greater than the previous. The sequence is shared between all connections and all transactions so an increment that is is made in one of connection will be seen in other connection immediately. Using a sequence never involves locking.

Function: sequence_remove

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Removes a sequence objectThe function removes a sequence object created before by sequence_set or sequence_next.

Function: sequence_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Sets and returns the state of a sequence object. The function sets and returns the state of a sequence object. The mode specifies whether a check for order of values should be made. If mode equals 0, the state is set regardless of the previous state. If mode is non-zero, the state is changed only if the new state is greater than the previous state. This gives some (weak) protection from occasional 'rewind' the sequence back to values that are already in use.

Function: serialize

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

convert any heterogeneous array or tree of arrays into a binary string and back These functions will convert any heterogeneous array or tree of arrays into a binary string and back. The format is platform independent. is the identity function. These functions are useful for persisting heterogeneous arrays.

Function: serialize_to_UTF8_xml

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts argument to its UTF-8 string representation.The function converts its argument to a narrow string in UTF-8 encoding. The way conversion is done depends on the type of the argument. If value is a wide (national) string or a LONG NVARCHAR then it is directly converted to UTF-8 string. If value is a string or a LONG VARCHAR then it is converted from current charset of client connection to the UTF-8.

Function: SERV_QUEUE_TOP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieve target website and store within VirtuosoWeb Robot site retrieval can be performed with the WS.WS.SERV_QUEUE_TOP PL function integrated in to the Virtuoso server. To run multiple walking robots all you simply need to do is kick them off from separate ODBC/SQL connections and all robots will walk together without overlapping. From a VSP interface, after calling the retrieval function you may call http_flush to keep running tasks in the server and allowing the user agent to continue with other tasks.

Function: ses_connect

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Opens a TCP session and returns its handle.This function requires dba privileges. This function is used to establish a new TCP connection to the target host. It returns a special datatype which represents the session handle.

Function: ses_disconnect

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Disconnections a TCP session.This function is used to disconnect from a session and destroy the session handle. After this function is called the session handle becomes invalid and hence cannot be used for reading or writing as an error will occur.

Function: ses_read_line

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Read a line of character data from a TCP session.This function is used to read a line of character data from an open TCP session. This function will read characters until it reaches an end of line up to a maximum of 1024 characters. The session can be passed as a session_handle. If the session_handle is omitted then execution is in current session/VSP context and will read from the open HTTP session. Ses_read_line() will suspend execution while attempting to read from the session until the timeout period of 100 seconds expires. When the timeout expires an error will be produced to indicate that the operation was unsuccessful.

Function: ses_write

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Write character data to an open TCP session.This function is used to write character data taken from the buffer parameter to an open TCP session. Attempts to write to a close session will result in an error being returned.

Function: set_row_count

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

sets the affected rows counter in the current context or in the context of the callerThe function set_row_count () is used to set the affected rows counter in the current context or in the context of the caller. Therefore it can be used to set the affected rows counter (returned by row_count()) in places where an instead of trigger is used. If result of decrement of the affected rows counter is an negative integer it will be set to zero.

Function: set_user_id

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

sets the current user for executionThis function changes the effective user and group to that of the user defined by user_name parameter. When called by a user with DBA group privileges, the optional password may be omitted. Otherwise it has to be the valid password for user_name. The mode parameter determines persistence (context) of effects of the call: If omitted or set to integer value 1, the effective user privileges will remain in effect within current stored procedure context only - upon returning, the effective user privileges will be automatically reset to state effective before set_user_id. When mode is equal to integer value 0, the effective user privileges will remain set for duration of current ODBC session, current request in web server context, or until next call of set_user_id. This function is analogous to the UNIX 'su' command.

Function: set_identity_column

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

sets the sequence starting value for an identity columnThis function takes the table name, the column name and the new sequence value as parameters. It checks for the existence of the identity column, and then sets the sequence value (using the sequence_set) and returns the old sequence value. The table and column names must be properly qualified to ensure the correct resource is located. The effect of calling this function is immediate.

Function: sign

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns -1, 0, or 1 depending on the sign of its numerical sign returns either -1, 0 or 1 depending whether its numeric argument is negative, zero or positive.

Function: signal

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Signal an exception in the calling procedure This signals the given SQLSTATE with the message. The calling procedure will transfer control to the most appropriate local handler. In the absence of a local handler the procedure terminates and signals the exception in the scope where it was called from, until there either is a handler or there are no more calling procedures. If there is no handler in the entire stack of call contexts the error is signalled to the client. Handlers can be declared with whenever .. goto and the declare handler for construct. See the Virtuoso/PL documentation.

Function: sinv_create_key_mapping

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a key mapping function & table (as described in the doc section SQL Inverse Functions).

Function: sinv_create_inverse

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates inverse mapping for the mentioned functions (as described in the doc section SQL Inverse Functions).

Function: sinv_drop_inverse

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Reverses the effect of sinv_create_inverse procedure.

Function: smime_sign

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts a MIME message to a signed S/MIME message

Function: smime_verify

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Verifies signature of signed MIME message This function takes the RFC822 text of an e-mail containing an S/MIME signed message and verifies it's signature using the CA certificates in certs, which is an array of strings containing single or multiple PEM-encoded certificates.

Function: smtp_send

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

send message to SMTP serverVirtuoso can act as an SMTP client. This means that Virtuoso is able to send emails directly to a mail SMTP server. Virtuoso has a simple function to facilitate this. This can be called from stored procedures, VSP pages, triggers etc. The sender and recipient email addresses must be enclosed with <..> and separated by commas i.e. string ',' The message Body contains headers such as Subject, From, To, Cc, Bcc and then continues with the actual message text itself. New lines can be added using '\r\n'

Function: soap_box_xml_entity

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts an XML entity to an SQL value given the desired SQL type. This function converts an XML entity to an SQL value based on the type of the entity and the desired SQL type. This function is called internally to convert a SOAP request parameter to a PL procedure parameter when a SOAP request is being processed by the SOAP server.

Function: soap_dt_define

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

define re-define or erase the complex datatype definition for SOAP callsThis defines a new complex SOAP datatype (usually array of structure) named 'name'. The schema_string string represents definition as complexType element from XML Schema. The only complexContent, all and sequence elements can be used within the complexType. This means that optional elements in the defined datatype are not supported as a variant of the SOAP parameter datatype. If the schema descriptions contains an unsupported element , the SQL error will be signalled and error message will explain what element is wrong.

Function: soap_call

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

calls a function from a SOAP server and returns the result. value; deprecated, use SOAP_CLIENT () instead This calls a function from a SOAP server and returns the result as a return value. Params is an array of (Parameter name, Value) pairs representing the parameters passed in the SOAP call. Each of these pairs become an XML sub-entity of the procedure entity. The return value of the function is the entity inside the SOAP body of the response. In debug mode the return value is an array of 3 elements; the non-debug return value (if any) as element 0, the XML text of the request as element 1 and the XML text of the server response as element 2. This function does not use any XML types when creating the XML. It represents types as a cast to varchar would, with one exception - dates and times according to ISO8061. The Virtuoso SOAP client can work with complex datatypes, in which case the parameters array must conform to the following convention: This will cause type checking and validation of the values to be encoded for SOAP request.

Function: soap_client

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Invoke a SOAP service and returns result value.This will invoke the specified SOAP service.

Function: soap_make_error

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a SOAP error reply XML message based on its parameters. This function creates a SOAP error reply based on the given parameters. It returns the generated XML as a varchar value.

Function: soap_print_box

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Formats an SQL value and returns it as a generated XML fragment. This function formats an SQL value as an XML fragment and returns it. This is used internally by the SOAP server to encode the output parameter values and return values when processing a SOAP request.

Function: soap_sdl

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Generate SDL document for a PL module and return it as a varchar.This function generates a SDL for the procedures in a PL module the same way as /SOAP/services.xml is generated for the procedures in WS.SOAP.

Function: soap_server

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Execute SOAP request and return XML reply as a varchar. This function executes the SOAP request in the same way as it it was directed to the /SOAP physical path. It returns the XML SOAP reply as a varchar value.

Function: soap_wsdl

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Generate WSDL document for a PL module and return it as a varchar. This function generates WSDL for the procedures in a PL module the same way as /SOAP/services.wsdl is generated for the procedures in WS.SOAP.

Function: soap_wsdl_import

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The soap_wsdl_import() function is used to import operations and types definitions from an WSDL file on a remote server. The retrieved file will be parsed and PL (procedure language) wrappers will be generated for each SOAP operation that is described. The SOAP service will be represented by a PL module which will be the overall container the generated PL wrappers. Once the WSDL file has been imported the PL wrappers are automatically generated and available for use.

Function: soap_box_structure

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function provides a way to encapsulate a structure suitable for soap serialization. It accepts a name/value pairs which represents name and value of elements of a structure. For example structure : will be represented as soap_box_structure ('varString', 'hello', 'varInt', 1234); furthermore value returned from soap_box_structure passed as an output parameter to the procedure (named structname) working as SOAP method will return :

Function: soap_current_url

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns URL used to access particular HTTP resource. This function is used to get in VSP/VSPX context the URL used to access current resource (page). It check whether 'Host' header field is specified, if not will return as a host information the IP address resolved via connected socket information.

Function: space

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a new string of count spacesspace returns a new string, composed of count spaces. If count is zero, an empty string '' is returned.

Function: split_and_decode

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

converts escaped var=val pairs to a vector of strings split_and_decode converts the escaped var=val pair inputs text to a corresponding vector of string elements. If the optional third argument is a string of less than three characters, then does only the decoding (but no splitting) and returns back a string.

Function: sprintf

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a formatted stringsprintf returns a new string formed by "printing" a variable number of arguments arg_1 - arg_x according to the format string format, that is, exactly the same way as with the sprintf function of C language. However the sprintf function enforces some additional limitations over the sprintf C function. It does not allow for single value output to take more than 2000 characters. It does support the following additional format characters: diouxXeEfgcs - as in the C language printf S - as 's' but escapes the single quotes by doubling them (as per SQL/92). This is suitable for constructing dynamic SQL statements with string literals inline.

Function: sprintf_inverse

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns vector on a specified pattern.sprintf_inverse gets a string to parse, a format string and an integer (0,1 or 2) that indicates error recovery method. If the first argument matches the format string then it returns vector of the pattern values.

Function: sprintf_iri

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a formatted string that is marked as an IRI string.sprintf_iri is similar to sprintf and returns a new string formed by "printing" a variable number of arguments arg_1 - arg_x according to the format string format. The difference is that the returned string is marked as being IRI string so some applications and clients may distinguish between RDF reference string and RDF literal.

Function: sprintf_iri_or_null

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a formatted IRI string or null if any of the arguments except the first is null.sprintf_iri_or_null is similar to sprintf_iri and returns a new string formed by "printing" a variable number of arguments arg_1 - arg_x according to the format string format. The difference is that the function can return null if any of the arguments except the first one is null. The returned string is marked as being IRI string so some applications and clients may distinguish between RDF reference string and RDF literal.

Function: sprintf_or_null

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a formatted string or null if any of the arguments except the first is null.sprintf_or_null is similar to sprintf and returns a new string formed by "printing" a variable number of arguments arg_1 - arg_x according to the format string format. The difference is that the function can return null if any of the arguments except the first one is null.

Function: sql_columns

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get column information from table on a remote DSNThis function corresponds to the ODBC catalog call of similar name. It and related functions are used by the virtual database to query remote data dictionaries. The dsn argument must refer to a dsn previously defined by vd_remote_data_source or ATTACH TABLE. For instance, the qualifier argument corresponds to the szTableQualifier and cbTableQualifier arguments of an ODBC catalog function. The SQL NULL value corresponds to the C NULL value. The arguments can contain % signs, which are interpreted as in LIKE.

Function: sql_data_sources

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get list of available DSNssql_data_sources is used to get the list of datasources available to the dsn. It returns a vector of 2 element vectors containing Data source name and type pairs.

Function: sql_gettypeinfo

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

return type information from a remote DSNYou can use the functions described here to find out information about the remote datasources that you are using. These could be especially useful in Virtuoso PL later on if you are not able to know everything about the remote tables ahead of time for the ATTACH TABLE statement. statement These SQL functions correspond to the ODBC catalog calls of similar name. The dsn argument must refer to a dsn previously defined by vd_remote_data_source or ATTACH TABLE.

Function: sql_primary_keys

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get primary key information about a table on a remote DSNYou can use the functions described here to find out information about the remote datasources that you are using. These could be especially useful in Virtuoso PL later on if you are not able to know everything about the remote tables ahead of time for the ATTACH TABLE statement. statement These SQL functions correspond to the ODBC catalog calls of similar name. These are used to access the data dictionary of remote data sources inside the ATTACH TABLE process. The dsn argument must refer to a dsn previously defined by vd_remote_data_source or ATTACH TABLE.

Function: sql_statistics

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

retrieve statistics information on remote DSNThis SQL function corresponds to the ODBC catalog call of similar name. It is used to access the data dictionary of remote data sources inside the ATTACH TABLE process. The dsn argument must refer to a dsn previously defined by vd_remote_data_source or ATTACH TABLE. The qualifier argument corresponds to the szTableQualifier and cbTableQualifier arguments of an ODBC catalog function. A SQL NULL value corresponds to the C NULL value. The arguments can contain % signs, which are interpreted as in LIKE.

Function: sql_tables

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get list of tables from remote DSNThis function corresponds to the ODBC catalog call of similar name. It and related functions are used by the virtual database to query remote data dictionaries. The dsn argument must refer to a dsn previously defined by vd_remote_data_source or ATTACH TABLE. The qualifier argument corresponds to the szTableQualifier and cbTableQualifier arguments of an ODBC catalog function. A SQL NULL value corresponds to the C NULL value. The arguments can contain % signs, which are interpreted as in LIKE.

Function: sql_special_columns

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get special column information from table on a remote DSNThis function corresponds to the ODBC catalog call of similar name. It and related functions are used by the virtual database to query remote data dictionaries. First argument of the ODBC SQLSpecialColumns is always SQL_BEST_ROWID. The dsn argument must refer to a dsn previously defined by vd_remote_data_source() or ATTACH TABLE.

Function: sql_procedures

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get procedures information for a remote DSNThis function corresponds to the ODBC catalog call of similar name. It and related functions are used by the virtual database to query remote data dictionaries. The dsn argument must refer to a dsn previously defined by vd_remote_data_source() or ATTACH TABLE. For instance, the qualifier argument corresponds to the szTableQualifier and cbTableQualifier arguments of an ODBC catalog function. The SQL NULL value corresponds to the C NULL value. The arguments can contain % signs, which are interpreted as in LIKE.

Function: sql_write_private_profile_string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Sets a DSN's attribute valueThis function corresponds to the ODBC catalog call of similar name. It and related functions are used by the virtual database to query remote data dictionaries. The type argument must be either 'system' or 'user'. Sets a data source attribute by calling SQLWritePrivateProfileString from the ODBC Installer API.

Function: sql_get_private_profile_string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Gets the DSN's attributes listThis function corresponds to the ODBC catalog call of similar name. It and related functions are used by the virtual database to query remote data dictionaries. The type argument must be either 'system' or 'user'. Gets the data source attributes by calling SQLGetPrivateProfileString from the ODBC Installer API.

Function: sql_config_data_sources

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Configures a remote DSN as in the DSN attribute stringThis function creates or modifies a user or system data source based on the semicolon separated list of DSN attributes. The type argument must be either 'system' or 'user'. Configures the data source by calling SQLWriteDSNToIni/SQLWritePrivateProfileString/SQLSetConfigMode from the ODBC Installer API.

Function: sql_get_installed_drivers

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get column information from table on a remote DSNThis function corresponds to the ODBC Installer call of similar name. It and related functions are used by the virtual database to query remote data sources.

Function: sql_remove_dsn_from_ini

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

removes a DSN from the ODBC registryThis function corresponds to the ODBC installer call of similar name. It and related functions are used by the virtual database to handle remote data sources.

Function: sql_transact

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get list of available DSNsThis procedure can be used to control the commit/rollback behavior of a particular remote data source during a Virtuoso transaction such as in a stored procedure. Under normal circumstances Virtuoso will correctly commit or rollback all associated work as expected, however it may be desirable intervene. When issued without the second parameter a commit will be forced upon the current transactions of the dsn_name above the call to sql_transact regardless of overall outcome. When rollback = 1 is set then a rollback will be forced likewise, hence this will not rollback work on the remote dsn_name prior to sql_transact.

Function: sql_write_file_dsn

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a new file DSNThis function calls the SQLWriteFileDSN as follows : SQLWriteFileDSN (dsn, 'ODBC', string, value)

Function: sql_driver_connect

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Tries connecting using supplied connection stringThis function calls SQLDriverConnect with the supplied connection string and immediately disconnects after the call.

Function: sqrt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

calculate square rootsqrt calculates the square root of its argument and returns it as a IEEE 64-bit float.

Function: status

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns statistics for a running server as a result setDepending of input parameter displays a statistics for running server. Note that counters reported by status will be reset after server startup.

Function: key_estimate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Get an estimate of row count for a given set of leading index key partsGiven a table and an index, this function takes a random sample of the index, with the first key part equal to the third argument, the second equal to the fourth argument and so on. If only the table and index are given, the returned value is the approximate count of the entire index. Normal cast rules are applied to convert the arguments to the types of the corresponding key parts. If the cast fails, -1 is returned. The estimates are typically within 10% of the real count. If there have been random deletions or inserts leading to uneven page filling or if index entries are of greatly varying $ length, the estimates may be less precise.

Function: strcasestr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

case-insensitive substring searchstrcasestr performs a case-insensitive substring search, returning a zero-based index pointing to beginning of first occurrence of sub or NULL if not found.

Function: strchr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

strchr returns a zero-based index to the first occurrence of the character. strchr returns a zero-based index to the first occurrence of char. If char is not found NULL is returned. char can be given either as an integer ASCII value or a string, in which case the first character of that string is searched fo.

Function: stringdate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Convert a string to a datetimestringdate converts dates and timestamps from text to the internal DATETIME type. The external format is: YYYY.MM.DD hh:mm.ss uuuuuu where uuuuuu represents number of microseconds. If trailing parts are omitted from the string given to stringdate, they are assumed to be zero. The three first parts are mandatory. Note that use of cast (x as datetime) is preferred over this function.

Function: stringtime

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

converts string to a timeConverts the argument to a time. Same as

Function: string_output

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

make a string output streamA string output stream is a special object that may be used to buffer arbitrarily long streams of data. They are useful for handling data that would not otherwise fit within normal varchar size limitations. The HTTP output functions optionally take a string output stream handle as a parameter and then output to said stream instead of the HTTP client. A string output stream can be assigned to a database column in insert or update, causing the characters written to the stream to be assigned to the column as a narrow string. The function string_output_string can be used to produce a varchar out of a string output stream. It may be called repeatedly to obtain several copies of the data. http_rewrite can be used to flush a string output stream. If a string output stream is passed to the function result the data stored in it is sent to the client.

Function: string_output_flush

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

resets the state of the string_output object This function resets the state of the string output object. The string associated with the string output is dropped and is of 0 characters after this call.

Function: string_output_gz_compress

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

compress a string_output with gzip algorithmThe string_output_gz_compress compresses its string_output argument using the gzip algorithm and writes the result to another string_output given as an argument. When successful, the number of bytes written to str_out_out is returned.

Function: string_output_string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

produce a string out of a string output streamThis function is used to produce a string from contents of a string output stream. See string_output for more information about string output streams.

Function: string_to_file

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

writes a varchar to a fileThis function requires dba privileges. string_to_file writes a varchar value or string session to a file. The path is relative to the server's working directory. The mode is an integer value interpreted as a position. A mode of 0 writes the content starting at offset 0. A mode of -1 appends to the end of the file. The append option is probably the most useful for producing application level logs, etc. The string argument can also be a string output object. In this case the content is used as the string.

Function: strrchr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a zero-based index to the last occurrence of the char in str. strchr returns a zero-based index to the last occurrence of char in string. If char is not found NULL is returned. char can be given either as an integer ASCII value or a string, in which case the first character of that string is searched for in str.

Function: strstr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

substring searchstrcasestr performs a substring search, returning a zero-based index pointing to beginning of first occurrence of sub or NULL if not found.

Function: subseq

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns substring of a string or sub-vector of a vectorsubseq returns a copy of subsequence of string or vector str using zero-based indices from (inclusive) and to (exclusive) to delimit the substring or the vector extracted. If to is omitted or is NULL, then it equals by default to the length of str, i.e. everything from from to the end of str is returned. If to and from are equal, an empty string ''(empty vector) is returned.

Function: substring

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a substring of a string substring returns a substring of string str. The start index is 1 based. The substring is sublen characters long. This function follows SQL 92.

Function: sub_schedule

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

add scheduled job for periodic synchronization of a subscriptionAdd scheduled job for periodically synchronizing a subscription.

Function: system

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

runs a shell command from SQL The system function will run a shell command from SQL. The shell command is executed in the server's current directory as the user that owns the database server process. This function is available to dba users only. Since this is a security risk this feature is normally disabled. It can be enabled by setting the AllowOSCalls setting in virtuoso.ini to 1.

Function: SYS_DB_STAT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

gathers common statistical information about the database.The SYS_DB_STAT procedure gathers common information about the whole Virtuoso database, including attached remote tables. It traverses each table and populates the SYS_COL_STAT table with data collected. SYS_DB_STAT can be used in random mode when not all rows of the tables are used to gather statistics of the database. SYS_DB_STAT gathers the following information for each column, COL, traversed in the database:

Function: sys_lockdown

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Set virtuoso in lockdown state and back.You must have DBA privileges to run that function. Calling this with lock_mode = 1 causes the server not to accept any new client connections, except ones coming from localhost (127.0.0.1). This will also shut down any other listeners and terminate any possibly pending processing, rolling back all open transactions and disconnecting all clients, except ones from localhost. Calling thi with lock_mode 0 reverses the effect.

Function: sys_stat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Return statistical information about the Virtuoso server.This function returns the statistic related to the requested statistic name give as a parameter to the function.

Function: sys_stat_analyze

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Collects statistics on a table and its columns for use in SQL optimization This function collects (or updates) column statistics for the table columns. It collects minimum, maximum average and distinct values for a column and a row count for the table and inserts the data into the DB.DBA.SYS_COL_STAT table. It does not make histograms for the columns. The statistics are then used by the Optimized SQL compiler. All the cached compilations are discarded, because some of them may compile differently in the light of the new data. This function will normally consider the entire database with the exception of remote tables. Since you may be concerned about time or remote tables this operation is configurable using the optional parameters, pcnt and ignore_vdb.

Function: sys_stat_histogram

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Collects a column value histogram for use in SQL optimization This function collects (or updates) values distribution data for a given column. It splits the sorted column values in n_buckets intervals and collects the last value of each interval. The values are then inserted into the SYS_COL_HIST table. If the table in question has not been analyzed, then it calls SYS_STAT_ANALYZE for the table.

Function: table_set_policy

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Sets policy function to table.

Function: table_drop_policy

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Drops policy function from table.

Function: tcpip_gethostbyname

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns IP address by host domain nameThis calls the system function gethostbyname() and returns h_addr from the hostent structure or empty string if no hostent structure returned (host not exists).

Function: tcpip_gethostbyaddr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns fully qualified DNS name of the host associated with given IP addressThis calls the system function gethostbyaddr() and returns h_name from the hostent structure returned by it. If no hostent structure returned, then it returns it's argument.

Function: tmp_file_name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the unique file name within temporary directory of the operating system The following function is used to obtain unique name of a file, which is located in temporary directory on file system. The two optional parameters can be supplied: prefix of the file and extension for it. These will be prepended and appended (dot MUST be omitted) to the unique string. The directory where this file is located depends of $TMPDIR or %TMP% environment settings for UNIX's and Windows platforms respectively. If these environment settings are not available or empty, the defaults will be used for the operation system. (in practice for most UNIX's it's /tmp or /var/tmp directory). Note that this function do NOT open the file, it only give us a name.

Function: tidy_html

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Invoke built-in version of HTML Tidy utility to fix typical errors in HTML text This function improves the given source HTML text, by invoking a custom version of HTML Tidy utility. To learn more about Tidy see http://www.w3.org/People/Raggett/tidy/ . Some particular combinations of errors in source HTML may cause Tidy to misinterpret the source so the output may be incomplete or corrupted. This is an unavoidable problem, due to heuristic nature of the procedure. On the other hand, Tidy will process almost any HTML suitable for some "popular" browser, e.g. Internet Explorer or Netscape Navigator.

Function: tidy_list_errors

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Invoke built-in version of HTML Tidy utility to get list of errors in given input HTML textThis function lists errors in given source HTML text, by invoking some custom version of HTML Tidy utility. To learn more about Tidy see http://www.w3.org/People/Raggett/tidy/.

Function: timezone

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get timezone difference from a datetimetimezone takes a datetime and returns an integer containing localtime - GMT in minutes.

Function: trace_off

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Disable extra logging for Virtuoso serverYou must have DBA privileges to run that function. This function is used to disable logging of various information enabled by default with the TraceOn ini file option or with the trace_on() function.

Function: trace_on

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Enable extra debug loggingThis function requires dba privileges. This function enables logging specified server operations for debugging purposes. The log entries will be shown at the server console (if started with foreground option) and will be written into the server message log file. The traceable events are divided into several groups: user activity, transactions, compilation of the SQL statements, DDL statements, statements execution and VDB actions.

Function: trace_status

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

show current trace settingsYou must have DBA privileges to run that function. This function returns an array of all available trace options and current status of the traces.

Function: tree_md5

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns MD5 checksum of array argumentReturns a string of 16 characters representing the binary MD5 checksum of the argument. The argument can be any array or scalar.

Function: HS_Resolve

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns URL that represents the given DOIReturns URL that represents the given DOI. The function is installed from the hslookup plugin which uses http://www.handle.net/. Note that you need to have in your Virtuoso database ini file in section Plugins added the hslookup.dll file, which location should be in the plugins folder under your Virtuoso server installation. For ex:

Function: trigonometric

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

trigonometric functions All these functions work with double precision floating point numbers. They convert their argument to an IEEE 64-bit float and return a result of that type.

Function: trim

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

removes characters from both ends of string argumenttrim returns a copy of subsequence of string str with all the characters present in trimchars trimmed off from the beginning. If the second argument is omitted, it is a space ' ' by default. rtrim is similar except that it trims from the right. trim trims from both ends.

Function: txn_error

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

poison current transaction forcing rollback Calling this function will poison the current transaction. This means that it is forced to roll back at when committed. The code can be in integer that selects the error message generated when trying to commit. This is useful before signalling application errors from SQL code that runs in manual commit mode. This can ensure that even if the client attempts a commit after getting the error signalled by the application the transaction will not commit. The code should be the constant 6, resulting the in the 'transaction rolled back due to previous SQL Error'.

Function: txn_killall

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

kill all pending transactions This function will terminate all pending transactions. This can be used for resetting infinite loops in stored procedures etc. The code determines the error reported to the client. Number 6 is preferable, corresponding to the 'transaction rolled back due to previous SQL error'. Once any SQL statement or procedure notices that its transaction is dead, e.g. deadlocked, it signals the error and takes appropriate action, which is typically to signal the error to the caller and ultimately to the client.

Function: ucase

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns upper case version of string argumentucase returns a copy of string str with all the lowercase alphabetical characters converted to corresponding uppercase letters. This includes also the diacritic letters present in the ISO 8859/1 standard in range 224 - 254 decimal, excluding the character 255, y diaeresis, which is not converted to a German double-s. upper is just an alias for ucase.

Function: uddi_delete_binding

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Causes one or more bindingTemplate structures to be deleted.

Function: uddi_delete_business

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove one or more businessEntity structures.

Function: uddi_delete_service

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove one or more businessService structures.

Function: uddi_delete_tModel

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove or retire one or more tModel structures.

Function: uddi_discard_authToken

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Inform a UDDI server that the authentication token can be discarded. The uddi_discard_authToken message is used to tell a UDDI-enabled server that the authentication token can be discarded. Subsequent calls that use the same authToken may be rejected. This message is optional for UDDI-enabled servers that do not manage session state or that do not support the get_authToken message.

Function: uddi_find_binding

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieves matching bindings The uddi_find_binding message returns a bindingDetail message that contains a bindingTemplates structure with zero or more bindingTemplate structures matching the criteria specified in the argument list.

Function: uddi_find_business

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieves a businessList message matching supplied criteria.

Function: uddi_find_service

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieves serviceList message matching search criteria

Function: uddi_find_tModel

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

locate list of tModel entries matching supplied criteria This uddi_find_tModel message is for locating a list of tModel entries that match a set of specific criteria. The response will be a list of abbreviated information about tModels that match the criteria (tModelList).

Function: uddi_get_authToken

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Obtain authentication token. The uddi_get_authToken message is used to obtain an authentication token. Authentication tokens are opaque values that are required for all other publisher API calls. This message is not required for UDDI-enabled servers that have an external mechanism defined for users to get an authentication token. This API is provided for implementations that do not have some other method of obtaining an authentication token or certificate, or that choose to use password-based authentication.

Function: uddi_get_bindingDetail

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Request run-time bindingTemplate location information. The uddi_get_bindingDetail message requests the run-time bindingTemplate information for the purpose of invoking a registered business API.

Function: uddi_get_businessDetail

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns complete businessEntity information for one or more specified businessEntities

Function: uddi_get_businessDetailExt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns extended businessEntity information for one or more specified businessEntities. The uddi_get_businessDetailExt message returns extended businessEntity information for one or more specified businessEntities. This message returns exactly the same information as the get_businessDetail message, but may contain additional attributes if the source is an external registry that is compatible with this API specification, rather than a UDDI-enabled server.

Function: uddi_get_registeredInfo

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieve an abbreviated list of all businessEntity keys. The uddi_get_registeredInfo message is used to get an abbreviated list of all businessEntity keys and tModel keys controlled by the entity associated with the credentials passed.

Function: uddi_get_serviceDetail

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

request full information about a known businessService structure

Function: uddi_get_tModelDetail

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Request full information about a known tModel structure.

Function: uddi_save_binding

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

save or update a complete bindingTemplate structure The uddi_save_binding message is used to save or update a complete bindingTemplate structure. This message can be used to add or update one or more bindingTemplate structures to one or more existing businessService structures.

Function: uddi_save_business

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Save or update information about a complete businessEntity structure. The uddi_save_business message is used to save or update information about a complete businessEntity structure. This message has the broadest scope of all of the save calls in the publisher's API, and can be used to make sweeping changes to the published information for one or more businessEntity structures controlled by an identity.

Function: uddi_save_service

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds or updates one or more businessService structures.

Function: uddi_save_tModel

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds or updates one or more tModel structures.

Function: udt_defines_field

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Determines whether a user defined type contains a specified member.This function is used to determine whether the supplied member_name is a member contained by the supplied udt.

Function: udt_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieves a copy of the requested member from a user defined type instanceThis function returns a copy of the member named member_name, if any, for type instance udt_inst. It is the functional equivalent of member observer.

Function: udt_implements_method

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

provides a handle to the first method with specific name in a user defined type.This returns a non-zero value (true) if the udt has an instance method with a name equal to the value of method_name. For methods with the same name, but with different signatures this function will return the handle of the first method in order of definition. If a method is not found, 0 will be returned. The return value can be used to call the method using the indirect call statement. In which case an instance should be passed as a first argument to the indirect call statement.

Function: udt_instance_of

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the type name of supplied type or compares two input types.This function returns information about the supplied type(s). There are two versions of this function, one returns the name of the type of the supplied argument, and the other than compares two supplied arguments for matching types. An error will be signalled if either of the types is not defined.

Function: udt_set

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This copies the instance udt_inst, sets new_value to the member with a name equal to the value of member_name (if any) and returns the modified instance copy. This is a functional equivalent of a member mutator.

Function: unimport_clr

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function automatically drops the SQL Type wrappers based on the CLR Reflection API.This function automatically drops the SQL Type wrappers based on the CLR Reflection API. If there is compiled Virtuoso/PL code that references the type it will fail to execute (with a compilation error) when executed or compiled.

Function: unimport_jar

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Drops SQL wrapper types of selected Java classesThis function calls the jvm_ref_import() function to produce the XML, then transforms it to a set of DROP TYPE statements and executes them.

Function: updateXML

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Create a changed copy of given document by replacing some nodes.This is a synonym name for XMLUpdate() function. This name is added for compatibility with Oracle 9i.

Function: upper

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Function: USER_CHANGE_PASSWORD

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Change the password of an existing user account.This function is used to change the password of an existing user account.

Function: USER_CREATE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create a new user accountThis function creates a new user account. The account is valid for SQL and/or DAV, depending n options.

Function: USER_DROP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This deletes a user ccount, optionally including schema objects, DAV resources and other possible resources owned by the user. This is used to remove an existing user account from local security schema.

Function: USER_GET_OPTION

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieve a user option for a given user account.This function is used to retrieve an existing user option.

Function: USER_GRANT_ROLE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Assign an existing role to an existing security object.This function is used to assign an existing role to an existing security object. This is the same as the GRANT statement. All roles assigned to the role object will be inherited.

Function: USER_REVOKE_ROLE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Removes a role from an existing security object.This function is used to remove a role from the specified security object. This is equivalent to using the REVOKE statement.

Function: USER_ROLE_CREATE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

create a new SQL role. Same as the create role statemen.. Creates a new SQL role.

Function: USER_ROLE_DROP

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove an existing role (group).This is used to remove an existing role (group) from the local security schema.

Function: USER_SET_QUALIFIER

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Change the default catalog (qualifier/database) of a user account.This function is used to change the default catalog (qualifier/database) of a given user account.

Function: USER_SET_OPTION

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Set a user option for a given user account.This function is used to set a User Option. The options can be any one of those described in User Options section or any other option. Note that existing option will be replaced.

Function: user_set_password

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Allows dba to change a user's password.Explicitly sets a new password for the SQL account user_name to new_password. Only users in the dba group may execute this function. It allows the database administrator to reset lost passwords of SQL accounts. The new password will be set without further confirmation, so the DBA must be sure of the new password.

Function: username

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns the login name of the current userReturns the login name of the user of the connection. Selecting >user is equivalent.

Function: uudecode

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Decodes a string previously encoded by uuencode Uudecode transforms uuencoded data into original form. Uuencode may return a number of sections as a vector of them, each of these sections should be decoded by separate call and results should be concatenated in order to compose original text. The mode of decoding should match to the mode used for encoding, of course. RFC 2045, (N. Borenstein, N. Freed. MIME (Multipurpose Internet Mail Extensions) Part One: The Format of Internet Message Bodies), contains detailed description of most important encodings used by mail systems. Older RFC 1521 is now obsoleted. Currently, eight conventions are used for mail attachments. In Virtuoso, they are enumerated by integer IDs.

Function: uuencode

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Encodes string or string session into sequence of printable characters, suitable for transfer via "ASCII-only" data channels There are many protocols, like classic UNIX uuencode, which are used to transmit binary files over transmission mediums that do not support other than simple ASCII data. The epoch of physical lines of such sort is in past but file attachments in most popular mail systems still follow old regulations. Encoded data are transmitted as a sequence of one or more "sections". They may be stored or sent as independent documents. Every section contains some range of original document's data. They may be decoded one after another, and original document may be composed by concatenation of decoded fragments. If the document is small (or if there's no limit on the size of message), it may be sent as single section. Every section has some header and footer and a set of lines with data between them. Headers and especially footers are usually optional and may vary from system to system whereas data lines are described by standards. Data lines of any two consequent sections may be concatenated together, if needed, to create longer section.

Function: uuvalidate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Encodes string or string session into sequence of printable characters, suitable for transfer via "ASCII-only" data channels This function tries to ensure what applied data have a pointed encoding mode. If mode parameter is 0 (ie unknown) or if the validation fails, it will try to determine which mode was used in fact. RFC 1521, (N. Borenstein, N. Freed. MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies), contains detailed description of most important encodings used by mail systems. RFC 2045, (N. Borenstein, N. Freed. MIME (Multipurpose Internet Mail Extensions) Part One: The Format of Internet Message Bodies). Currently, eight conventions are used for mail attachments. In Virtuoso, they are enumerated by integer IDs.

Function: VAD_CHECK

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Checks the package has not been altered since installationThis checks to see if the elements of the package are as they are defined in the original distribution. A list of differing elements is returned. This does not always indicate a corruption since a later version or another package may add columns to tables, and some resources may be customized after installation.

Function: VAD_CHECK_INSTALLABILITY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Checks the presence and correct versions of required packages and of the Virtuoso platformChecks the presence and correct versions of required packages and of the Virtuoso platform. It does not execute any pre-install Virtuoso/PL code from the package, so there is no guarantee that installation will be successful if the check found no error.

Function: VAD_CHECK_UNINSTALLABILITY

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Checks if the package can be uninstalled.Checks if the package can be uninstalled. It does not executes any pre-uninstall Virtuoso/PL code from the package, so there is no guarantee that uninstallation will be successful if the check found no error.

Function: VAD_FAIL_CHECK

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Signals package check failuremakes "rollback work", exits from atomic mode and fails server with raw_exit(-1)

Function: VAD_INSTALL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Invoke VAD installation processInvoke the install operation from interactive SQL or from the web user interface. This will: If there was a failure in mid-install, such as running out of disk or some other serious unrecoverable database error, the server exits. The installation can be undone manually by halting the server, deleting the transaction log file and restarting. The server will start from the checkpoint as if the installation was never attempted.

Function: VAD_LOAD_FILE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

executes statements of a SQL fileThis splits a plain sql file into single statements and executes them one by one. The root directory for this procedure is the 'code' root of VAD's repository.

Function: VAD_PACK

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get VAD resourceThis function gets the resource identified by the sticker_uri, which contains the vad:package root element. The URIs present there are interpreted in the context of the base_uri_of_resources and the individual resources are fetched. These are parsed to make sure that they are syntactically correct and the resources are appended to the generated package resource, which is stored into the result_uri. vad_pack() returns a human-readable log of error and warning messages, vad_pack() will signal errors if some resources or database objects will be unavailable. By convention, VAD package files have the extension '.vad'.

Function: VAD_SAFE_EXEC

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

execute without signalling errorsSafe way to do something without generating an exception, e.g.: when it is necessary to drop a table without insurance of it's existence.

Function: VAD_UNINSTALL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Vad package uninstallationInvokes the uninstall operation from interactive SQL or from the web user interface. This will:

Function: vd_remote_data_source

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

prepares a remote DSN for use A remote data source is uniquely identified by its DSN, the dsn argument to this function. The connstr argument is presently ignored. The user and password are the login name and password to use when communicating with the remote data source. All Virtuoso users dealing with the remote data source will appear as this user to the remote data source. Virtuoso will make as many connections as there are concurrent users of the data source. Connections are cached by Virtuoso. The default qualifier of the user of the remote data source is usually not relevant. This function connects to the DSN in order to retrieve various meta data, which it stores locally. The DSN should be defined in the server's environment and the DSN's database should be on line.

Function: vd_remote_proc_wrapper

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creating a PL wrapper for remote procedure executionThis is to create a PL stored procedure to execute a Remote Stored Procedures. It returns results as a SQL result set as well as an array(vector) depending of the 'make_resultset' flag.

Function: vd_remote_table

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

declares an existing table as resident on a DSN previously declared with vd_remote_data_source Declares an existing table as resident on a data source previously declared with vd_remote_data_source(). This function declares the table local_name as table remote_name on the dsn. The tables names should be full, names with qualifier and owner. The names are case sensitive and must be in the exact case where they appear in the local and remote schemas. If remote_name is NULL, the effect of a possible previous vd_remote_table is reversed. The table is thereafter treated as a local table, except in procedures and statements compiled when the remote declaration was in effect.

Function: vd_statistics

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Update VDB RPC cost statistics for given DSNThis procedure will update the RPC round-trip statistics for selected data sources.

Function: vdd_disconnect_data_source

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Disconnects a data source if no active transactions are using resources from it.You must have DBA privileges to run that function. This function disconnects all the idle opened connections to a VDB datasource. If there are active transactions server-side, using connections to that datasource, they are not closed. After they finish, this function can be called again to disconnect the new idle connections. The datasource continues to be valid and any subsequent transactions using this datasource will open a new connection to it.

Function: vdd_measure_rpc_time

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Estimate VDB RPC round-trip for a given DSN in millisecondsThis function will return the estimated number of milliseconds to perform an RPC round trip on the DSN supplied.

Function: vector

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

make a vectorvector returns a new vector (one-dimensional array) constructed from the given arguments.

Function: vector_concat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

concatenate vectorsvector_concat takes a variable number of vectors (heterogeneous arrays) and constructs a new vector containing copies of each (top level) element in the arguments.

Function: VHOST_DEFINE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

define a virtual host or virtual directoryVHOST_DEFINE is used to define virtual hosts and virtual paths on the Virtuoso HTTP server. Effectively this procedure inserts a row in table DB.DBA.HTTP_PATH Virtuoso supports both flavours of virtual hosting: IP-based and name-based.

Function: VHOST_REMOVE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

remove a virtual host or virtual directoryvhost_remove is used to remove virtual hosts and virtual paths on the Virtuoso HTTP server. Effectively this procedure deletes a row in the table DB.DBA.HTTP_PATH. Virtuoso supports both flavours of virtual hosting: IP-based and name-based.

Function: virtuoso_ini_path

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Return full name of configuration INI fileThis function returns the complete path to the configuration INI file. It is typically used by the cfg_ functions that modify or read the contents of the INI file.

Function: server_root

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns server working directory.This function returns the complete physical path to server working directory.

Function: vsp_calculate_digest

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

calculate on server-side a digest to perform a HTTP digest authentication The vsp_calculate_digest() function is used to calculate on server-side a digest to perform a HTTP digest authentication. When the authentication type is 'digest' the function will return a md5 checksum based on credentials , user name and password. The checksum calculation will be made as required for HTTP Digest authentication to compare against 'response' element of credentials. If the authentication is basic a NULL will be returned.

Function: vt_batch

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a vt batch object. This object can be used to update a free text index by feeding document information into it using vt_batch_d_id to set the free text document ID and vt_batch_feed to feed actual words. This object may not be assigned to other variables and may only be passed as an inout parameter. The batch is applied to the index by calling the VT_BATCH_PROCESS__ function generated by CREATE TEXT INDEX.

Function: vt_batch_d_id

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Specify a document to update in a vt batch. Multiple documents may be indexed or unindexed with a single batch. In this case this function will be called for each document id, in ascending order of ID.

Function: vt_batch_feed

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Add words to a free text update batch.This function allows you to add words to a free text update batch. It can be called in sequence to feed group of documents that share a common document ID and the result is similar to the single call whose text_or_xml parameter is concatenation of documents of that group. It is even allowed to mix XML and non-XML documents by feeding an XML document and some text documents: the first document to feed may be an XML document, other documents should be only texts. If one wishes to mix XML and non-XML documents, knowledge of details of the indexing method is needed. vt_batch_feed assigns a sequence number to every word of the provided document using an internal counter. The call of vt_batch_d_id not only sets document id but also resets this counter to 0. The first element of an XML document should have number 0 so it is impossible to feed an XML document if there were other calls of vt_batch_feed after the last vt_batch_d_id. Moreover, xcontains will ignore words from text documents that were fed after the first XML document, only contains will use all data.

Function: vt_batch_feed_offband

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Add offband information to a free text update batch.This function allows you to add offband information to a free text update batch. This should be done by index and unindex hook functions of the free text index if and only if the index is created with both "CLUSTERED WITH (...)" and "USING FUNCTION" options and the hook function returns non-zero value, i.e. disables standard indexing of the document. This function is needed only for very unusual free text indexes.

Function: VT_BATCH_UPDATE

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Set batch mode update of free text indexing. This function controls the time of update of a text index. If flag is ON, changes are accumulated into a change tracking table and applied as a batch. If flag is OFF, the text index is updated in the same transaction as the indexed data itself. The change tracking table is automatically created and is named VTLOG___

, in the qualifier and owner of the indexed table, where q, o and table are the qualifier, owner and name of the table. The changes accumulated into that table can be explicitly applied to the index using the VT_INC_INDEX___

function.

Function: vt_create_text_index

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Add text index to an existing table The vt_create_text_index procedure adds a text index to an existing table. There can at most be one text index per table, including super tables and subtables. The table argument is a string naming the table. The column is the name of the column to index. The id_col should be the name of a unique integer row identifier column. If null, the system will either add such a column or use an existing integer primary key if one is available. The is_xml argument, if non-0, specifies that the values of the indexed column should be checked for XML well formedness and that the XML structure should be taken into account in indexing the values. Use the CREATE TEXT INDEX statement as an alternative to the vt_create_text_index function.

Function: VT_DROP_FTT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

drop free text trigger

Function: vt_is_noise

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

determines whether input is a noise word

Function: week

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

get number of week from a datetimeweek takes a datetime and returns an integer containing a number representing the week of year of the datetime.

Function: wsdl_import_udt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a string containing a UDT definitionThis function is used to create a user defined type (UDT) definition automatically based on a WSDL file. The source WSDL is supplied via a URL. The returned definition can be saved to a file and/or executed automatically to provide instant access to the new UDT.

Function: wst_cli

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Request a security token from WST endpointThis function is for use with a SOAP client contacting a WS-Trust endpoint for a security token.

Function: dsig_template_ext

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Generates a Digital signature template based on a XML document. The function is used to generate dynamically a digital signature template containing references to be signed.

Function: x509_certificate_verify

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Verifies X.509 certificate This function takes a X.509 certificate and verifies it against list of CA certificates. It checks for various certificate attributes such as self signed, expiration date etc. If an error is detected it will be signalled. The certificates are passed as a strings containing X.509 certificate binary data in DER (raw) format.

Function: xenc_X509_certificate_serialize

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Exports a X.509 certificate from user's repository This function is used to export X.509 from user's space.

Function: xenc_decrypt_soap

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Decrypt and verify a SOAP message The function is used to decrypt and optionally verify signature (depends of a validate_flag parameter) of a SOAP message.

Function: xenc_delete_temp_keys

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove the temporary keys from user's space When signing an XML document or doing the reverse work like verification etc. number of temporary keys are created in user's space. These keys at some point may not needed anymore, so they can be removed from memory.

Function: xenc_encrypt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Encrypt and optionally sign a SOAP message Encrypt SOAP message and optionally attach an XML signature. The keys are retrieved from the key store of the calling user account.

Function: xenc_get_key_algo

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Determine XML signature algorithm of a keyThe function is used to determine signing algorithm supported by given key.

Function: xenc_get_key_identifier

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Determine a key identifierThe function returns key identifier.

Function: xenc_key_3DES_read

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Importing a triple-des key into user's repository This function is used to import a triple-des serialized key into user's repository and register it with a name supplied. Note that key will not be persisted. It is loaded in the memory only.

Function: xenc_key_3DES_create

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Used to make a symmetric key.Used to make a symmetric session key for triple-des algorithm.

Function: xenc_key_3DES_rand_create

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Used to make a temporary session key.Used to make a temporary session key.

Function: xenc_key_DSA_read

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Importing a DSA key into user's repository This function is used to import a DSA serialized key into user's repository and register it with a name supplied. Note that key will not be persisted. It is loaded in the memory only.

Function: xenc_key_RSA_read

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Importing a RSA key into user's repository This function is used to import an RSA serialized key into user's repository and register it with a name supplied. Note that key will not be persisted. It is loaded in the memory only.

Function: xenc_key_AES_create

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Used to make a symmetric key.Used to make a symmetric session key for AES encryption algorithm.

Function: xenc_key_AES_rand_create

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Used to make a temporary session key.Used to make a temporary session key for AES encryption.

Function: xenc_key_create_cert

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Import a key from a certificate The function is used to import a key (usually an asymmetric key like RSA or DSA) into user's space from a certificate.

Function: xenc_key_DSA_create

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Used to make asymmetric DSA key.Used to make asymmetric DSA key for digital signatures. The generated key will contain private and public keys.

Function: xenc_key_exists

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Check if named encryption key is in the user's repositoryThe function checks if key with given name exists in the user's keys.

Function: xenc_key_inst_create

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Key instance generation The function is used to make a key reference used in encryption functions.

Function: xenc_key_remove

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This will delete a key from current user's space.This will delete a key from current user's space.

Function: xenc_key_serialize

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Extracts a key from user's repository The function returns a string containing base64 encoded binary key data. It is used to extract symmetric or asymmetric keys. So if key is asymmetric (RSA or DSA) the second parameter designate which part to extract private or public.

Function: xenc_set_primary_key

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Associate a X.509 certificate with a key This function is used to associate a key (to be used as primary) with a X.509 certificate. Usually this function is called after key import from a X.509 certificate.

Function: xenc_x509_ss_generate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a self-signed X.509v3 certificateThis function is used to create a self-signed X.509 certificate by given private key

Function: xenc_x509_generate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Generates a X.509v3 certificate using client's public keyThis function creates a X.509v3 certificate from a public key and sign the certificate with CA private key

Function: xenc_pkcs12_export

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Export of a certificate and private key into Personal Information Exchange Syntax (PKCS#12) format.

Function: xenc_pem_export

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Export of a certificate and optionally private key in PEM formatThe function is used to export certificate in PEM format, optionally it can export also private key (if present)

Function: xenc_SPKI_read

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Imports a public key from simple public key infrastructure (SPKI)This function is used to read an RSA public key from SPKI content.

Function: xenc_bn2dec

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Prints as a string a big number serialized as binary using base64 encoding

Function: xte_head

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the vector corresponding to a head of a XML element This function takes odd number of parameters and creates vector which corresponds to a head of a XML element. The first parameter is a tag name of the head. The remaining parameters are optional. Each even parameter is a name of an attribute, each next odd parameter is a value of this attribute. If two or more attributes have the same name, the head would have only the last pair.

Function: xte_node

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the vector corresponding to a XML element This function returns the vector which corresponds to a XML element. The first parameter is a head of the element. The remaining parameters are optional. Each optional parameter either is a XML element or a string. Two or more successive strings are concatenated.

Function: xte_node_from_nodebld

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the vector corresponding to a XML element This function replaces the first item of the second argument by the first argument and returns a vector corresponding to an XML element.

Function: xte_nodebld_acc

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds to the first arguments all remaining arguments The xte_nodebld_acc() function successively adds the remaining arguments to the first one. If the last items of the first argument and some following arguments are strings, they are concatenated. All successive strings are concatenated. The value of the first item is the number of the non-empty items in the returned vector. The length of the returned vector is the sum of the length of the first argument and number of the remaining arguments.

Function: xte_nodebld_final

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Corrects input vector By default this function reduces all last empty items from the first argument and returns it, but supplied a second argument it also replaces the first item of the first argument by the second argument, but does not commit the return.

Function: xte_nodebld_init

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates the empty vectorThis function creates the empty vector and assign it to the argument.

Function: XMLAGG

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Produces a forest of elements from a collection of XML values XMLAGG is aggregate function that produces a forest of XML elements from the given list of xml elements. It concatenates the values returned from one column of multiple rows, unlike XMLCONCAT, which concatenates the values returned from multiple columns in the same row. The order of element in the result of XMLAGG is defined by the order of retrieval of the source data rows. It is important to remember that the order of rows in an SQL resultset defined only if there's an explicit ORDER BY clause. Hence if the order of elements in the resulting forest is important then XMLAGG should be applied to data that comes from inner SELECT statement that has an ORDER BY clause, not e.g. from a table reference. Note that XMLAGG is actually declared as DB.DBA.XMLAGG but it is not important for plain use: for compatibility with other systems, any call of XMLAGG in any SQl statement is always replaced with the call of DB.DBA.XMLAGG, no matter which qualifier and user name are in use.

Function: XMLATTRIBUTES

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a list of attributes and their values This function creates a vector that may be used only as argument of XMLELEMENT function. The vector has an even number of elements, each odd element is a name of an attribute, an even element is its value. If the attribute value is NULL, then no attribute and no value is created. If none of the attribute is created, then the function returns NULL. If string_expr is a column name, then you can omit the AS clause, and Virtuoso uses the partially escaped form of the column name as the attribute name.

Function: XMLAddAttribute

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Add an attribute to the given node of an XML tree documentThe function modifies the source document by adding an attribute to the current node of source entity. The source should be an XML tree entity, not "persistent XML" one, should be an element entity (not attribute, text etc.) and should not be a root entity. Parameters attr_name and attr_value can be of any types that can be casted to string. attr_name can be an attribute entity, in this case both the name and the value of attr_name attribute is used and attr_value parameter must be omitted. The mode specifies how to resolve duplicate attribute names, if an source entity already has an attribute whose name is equal to attr_name. Mode 0 is similar to "insert into": the function signals an error if an attribute already exists. Mode 1 is similar to "insert soft": the function do nothing if an attribute already exists and not signalling an error. Mode 2 is similar to "insert replacing": the function either adds a new attribute or replacing the value of existing attribute.

Function: XMLAppendChildren

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Modify an XML document by adding new children to the given entity.The function modifies the XML document of the given source XML tree entity by adding new children to the node specified by the entity. The source entity should be XML tree entity, not "persistent XML" entity. The value of source can be either an element entity or a root entity; source can not be an attribute entity or a leaf entity like text or processing instruction. The values passed in parameters insertion1... insertionN will be converted into XML nodes according to rules described in section Composing Document Fragments From DOM Function Arguments. After calling the function, parameter source is still a valid XML entity that points to the modified node. The value passed as source can be used in the rest of caller procedure.

Function: XMLCONCAT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a forest of elements by concatenating a list of XML values XMLCONCAT accepts a list of XML value expressions as its arguments, and produces a forest of elements by concatenating the XML values that are returned from the same row to make one value. XMLCONCAT works like XMLFOREST, except that XMLCONCAT parameters is a list of XML elements. Null expressions are dropped from the result. If all the value expressions are null, then the function returns NULL.

Function: XMLELEMENT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates XML element XMLELEMENT takes an element name for identifier, an optional collection of attributes for the element, and arguments that make up the element's content. It returns a XML element. The second parameter may be omitted and at that time the rest parameters may be present. If one of the arguments is a call of the xpath_eval returning an attribute value, then this value would be added to element's content (not to element's attributes).

Function: XMLFOREST

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Produces a forest of XML elements XMLFOREST produces a forest of XML elements from the given list of arguments. The arguments may be string expressions with optional aliases. If string expression is a column name, then you can omit the AS clause, and Virtuoso uses the partially escaped form of the column name as the name of the enclosing tag. If the expression evaluates to NULL, then no element is created for that expression. If none of the element is created, then the function returns NULL.

Function: XMLInsertAfter

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Modify an XML document by inserting new children after the node specified by given entity.The function modifies the XML document of the given source XML tree entity by adding new siblings to the node specified by the entity. Siblings will be added right after the node. The source entity should be XML tree entity, not "persistent XML" entity. The value of source should be a node entity; source can not be an attribute entity or a root entity. The values passed in parameters insertion1... insertionN will be converted into XML nodes according to rules described in section Composing Document Fragments From DOM Function Arguments. After calling the function, parameter source is still a valid XML entity that points to the same node. The value passed as source can be used in the rest of caller procedure.

Function: XMLInsertBefore

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Modify an XML document by inserting new children before the node specified by given entity.The function modifies the XML document of the given source XML tree entity by adding new siblings to the node specified by the entity. Siblings will be added right before the node. The source entity should be XML tree entity, not "persistent XML" entity. The value of source should be a node entity; source can not be an attribute entity or a root entity. The values passed in parameters insertion1... insertionN will be converted into XML nodes according to rules described in section Composing Document Fragments From DOM Function Arguments. After calling the function, parameter source is still a valid XML entity that points to the same node. The value passed as source can be used in the rest of caller procedure.

Function: XMLReplace

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Modify a given XML document by replacing some nodes.The function takes of the XML document referenced by source XML tree entity and modifies it by replacing nodes specified by location1, location2, ..., locationN with values specified by replacement1, replacement2, ...,replacementN. At the end of function call, the source points to the root of a modified entity. The source parameter should be an XML tree entity whose document is not locked (see Changing XML Entities in DOM Style for details). Every replacementI may be an XML tree entity, a NULL or a value of some other type that will be converted to varchar before use.

Function: xml_auto

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

prepares and executes given SQL for XML string output This function prepares and executes the given SQL string, which should be a query expression with the FOR XML clause at the end of the last term. The query is passed the parameters from the params vector, which should have one element for each ? in the query text, values assigned from left to right. Consider the query: select a, b from table where a = ? and b = ?; then the params vector could reasonably be: vector(1, 'myfilter'). The result set is converted to XML and appended to the string_output. If the string_output is omitted and the function executes in the context of a VSP page, the output is sent to the stream going to the user agent.

Function: xml_auto_dtd

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an XML DTD for the result of a SQL query with a FOR XML clause This function returns an XML DTD for the results of a SQL query with a FOR XML clause. The returned DTD will apply to the output generated by xml_auto with the query in question after wrapping it into the specified root element.

Function: xml_auto_schema

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an XML schema for the result of an SQL query with a FOR XML clause This function returns an XML schema for the results of an SQL query with a FOR XML clause. The returned schema will apply to the output generated by xml_auto() with the query in question after wrapping it in the specified root element.

Function: xml_create_tables_from_mapping_schema_decl

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a vector containing strings. Each string is a command to drop a table or a foreign key or to create table. xml_create_tables_from_mapping_schema_decl takes a file containing mapping schema and returns a vector containing strings. Each string is a command to drop a table or a foreign key or to create table. All tables and fields are mentioned in the mapping schema. If a field type is not defined in the mapping schema, the VARCHAR type is used.

Function: xml_cut

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

creates a new XML document which contains a copy of data pointed by given XML tree- or XPER- entity In some special cases, some part of XML document, being pointed by a XML entity, should be copied into a new separate document with new entity pointing to the top-level element or the root of this document. One reason for doing this is optimization of XPER processing (see xper_cut). Another way to use this functionality is passing of some XML entity to a function, when function uses XPath operations with references to the "document's root". The current node of the resulting entity is the node that is a copy of the current node of the source entity. In common, the top-level node of the copied subtree becomes the current node of the result. There are two special cases, however. If the source entity is an attribute entity, then the result is also an attribute entity and the attribute name remains the same. If the source entity points to the root of the document, the resulting entity also points to the root of the copied document, not to its top-level node. With XPER entity given, xml_cut() works exactly as xper_cut().

Function: xml_doc_output_option

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function reads or updates the specified XSLT output option value of the given xml_entity. The function updates the option if parameter option_value is provided, otherwise it returns the current value of the option without any side effects. Supported options are 'method', 'version', 'encoding', 'omit-xml-declaration', 'standalone', 'doctype-public', 'doctype-system', 'indent' and 'media-type', but do not support'cdata-section-elements'. When the entity is serialized, the effect is very similar to the effect of the same option specified in xsl:output element of an XSLT that created the entity.

Function: xml_load_schema_decl

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a string with list of errors detected by XML Schema processor on reading given XML Schema definition document.

Function: xml_load_mapping_schema_decl

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

creates a xml view from mapping schema. xml_load_mapping_schema_decl takes a file containing mapping schema and creates a xml view.

Function: xml_namespace_scope

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a vector of all namespace declarations in all ancestors of the given XML entity.The function returns a vector of even length that consists of all declared namespace prefixes and namespace URIs from the ent and all its ancestors. This information is needed for processing XML documents that contains a mix of data and XPath expressions, such as BPEL documents.

Function: xml_add_system_path

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Adds path to the internal list of system paths. When validating XML parser tries to resolve system entities it searches in http_root directory. If it fails parser iterates internal list of system paths and tries to find required files there. The function adds new path in this list. List of system paths contains one directory item by default - "file://system/". NOTE: List of system paths is not persistent. It means that you must add desired path each time when server starts. An ideal place for this operation in "autoexec.isql" file.

Function: xml_get_system_paths

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns vector of all system paths.

Function: xml_persistent

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an entity object ('XPER entity') created from given XML document This parses the argument, which is expected to be a well formed XML fragment and returns a parse tree as a special object with underlying disk structure, named "persistent XML" or "XPER" While the result of xml_tree() is a memory-resident array of vectors, the XPER object consumes only a little amount of memory, and almost all data is disk-resident. This function is equivalent to xper_doc, and the only difference is in the order of arguments; xper_doc() has the same order of arguments as xml_tree.

Function: xml_template

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Execute XML template from Virtuoso PLThe xml_template() function was introduced to enable PL programming to make use of XML templates. This function expects an XML entity for the first argument, that will be the XML template file contents. Usually this entity is composed making use of the xtree_doc() function from the XML template file. The second argument should be a vector of name-value pairs of the parameters for XML template. The last argument is an output string stream for the result. If the output stream is not specified the HTTP internal stream will be used if it is available, otherwise an error will be signalled.

Function: xml_tree

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Parses an XML fragment and returns the parse tree as nested vectors.This parses the argument, which is expected to be a well formed XML fragment and returns a parse tree as a structure of nested heterogeneous vectors.

Function: xml_tree_doc

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an entity object given a tree from xml_tree This returns an entity object given a tree of the form returned by xml_tree. If it is given a string as an argument, it will automatically generate the parse tree and use it to make the entity instead requiring you to run the string through xml_tree first. Note that it is better to use xtree_doc or xper_doc for converting source XML text directly to an XML entity. If the argument is an XML tree entity, the function will return it as is, so e.g. redundant calls of xml_tree_doc will have no effect. The only thing xml_tree_doc can alter in the returned value is base URI of the document entity: if base_uri is provided and is not NULL, and argument entity has no base URI set then the provided URI is assigned to the returned entity.

Function: xml_tree_doc_media_type

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function returns the media type in effect for the result of the xslt() (XSL-T) transformation , based on xsl:output "media-type" and "method" attributes of the XSL-T style-sheet applied. It accepts an entity (potentially resulting from using xslt()) as a argument and will return a string containing the media-type.

Function: xml_uri_get

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieve a resource based on a URI This function combines a base URI and a relative URI and returns the referenced resource. The supported protocol identifiers are http: file: and virt:. The virt: allows referencing data stored in local Virtuoso tables without passing through HTTP. See 'Entity References in Stored XML' for details. The effective URI will be the reference if the URI of the reference is absolute. Otherwise it will be the base URI modified by the relative reference.

Function: xml_validate_dtd

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a string with list of errors detected by DTD validator on reading given XML document This parses the argument, which is expected to be an XML fragment (possibly with syntax errors, violations of validity conditions etc.) and returns a human-readable list of errors as a string. DTD validation may be performed during any reading of XML source in functions xml_tree(), xml_persistent() or xper_doc(), so that an application may check XML source on the fly; severe constraint violations in source XML will be signalled as SQL runtime errors.

Function: xml_validate_schema

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a string with list of errors detected by DTD and XML Schema validator on reading given XML document. This parses the argument, which is expected to be an XML fragment (possibly with syntax errors, violations of validity conditions etc.) and returns a human-readable list of errors as a string. If there is a "schemaLocation" attribute in root element, XML Schema declaration will be loaded and partial schema validation will be performed. If this attribute does not exist and the Validation option below is not set to DISABLED, then an error will be returned: ('FATAL : Schema declaration is not loaded'). The XML Schema validation routines are tightly coupled with DTD validator. If the document contains both Schema and DTD information then both validations are made in the same time in order to provide as accurate diagnostics as possible. However, it is impossible to check whether the declared DTD matches or contradicts to the declared Schema, so the parser performs two independent validations to every item of source data. E.g. if DTD contradicts to the schema in description of some particular element and data in the document does not contain this element then no errors is reported; but if sun an element occurs in the document then either DTD validator or Schema validator will log an error.

Function: xml_view_dtd

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an XML DTD for the output of given XML VIEW This function will return an XML DTD for the output of a given XML VIEW. The returned DTD will be valid if the HTTP_... output of the view is wrapped into the specified root element.

Function: xml_set_ns_decl

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Registers the XML NS prefix as persistent or keeps it in properties of client connection depending on the persistance bits input value.Registers the XML NS prefix as persistent or keeps it in properties of client connection depending on the persistance bits input value.

Function: xml_view_schema

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an XML schema for the output of given XML VIEW This function return an XML schema for the output of given XML VIEW. The returned schema will be valid if the HTTP_... output of view wrapped into the specified root element.

Function: xmlsql_update

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Performs insert/update/delete operations based on an XML updategram.xmlsql_update() supports XML-based insert, update, and delete operations performed on an existing table in the database. See Updategrams basics in the "Web and XML section" for a detailed explanation.

Function: XMLUpdate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Create a changed copy of given document by replacing some nodes.The function takes of the XML document referenced by source XML tree entity, makes a copy of that document; then it modifies the copy by finding fragments that are values of path1, path2, ..., pathN XPATH expressions and replacing them with values specified by replacement1, replacement2, ...,replacementN; the modified copy is returned as the result of the function call. Every pathI should be a string that is a correct XPATH expression. Every such expression is evaluated according to the rules for XPATH expressions in XSLT (attribute entities are not cast to their string values). The context node is source, context size and position are both equal to 1. Every replacementI may be an XML tree entity, a NULL or a value of some other type that will be converted to varchar before use.

Function: xpath_eval

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Applies an XPATH expression to a context node and returns result(s). This function returns the result of applying the XPath expression to the context node. By default only the first result is returned, but supplying a third argument allows you to specify an index for the value; the default assumes a value of 1 here. A value of 0 returns an array of 0 or more elements, one for each value selected by the XPath expression. When this function returns an entity in a result set, the client will see an nvarchar value containing the serialization of the entity, complete with markup. When the entity is passed as an SQL value it remains an entity referencing the node of a parsed XML tree, permitting navigation inside the tree. The expression can be passed parameters by specifying a fourth argument to xpath_eval(). This will be a vector of name/value pairs. The values can be referenced from inside XPath expression by using their names with '$' prefix. You may use any Virtuoso data type. The names in the parameter vector should appear without the '$' sign. If any of the parameter values is NULL the parameter will be ignored because NULL has no XPath counterpart. If the same name appears more than once in the vector, the last name/value pair is used and all preceding pairs with this name are silently ignored. Obviously, names should be strings that are valid XPath variable names.

Function: xper_cut

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

creates a new "persistent XML"document which contains a copy of data pointed by given XPER entity As noted in the Storage in Database section, a subtree may be extracted from a document during writing of "persistent XML" entity into field of type LONG VARCHAR. The procedure of converting a subtree into complete document is known as "cutting". Cutting is performed only for "persistent XML" documents, it has nothing common with serialization of XML entities in form of plain XML text. Usually it is the job of the Server itself who decides whether a cutting operation should be performed or not, without any specific activity at application level. The CPU time occupied due to cutting is up to 10 times greater than the CPU time of plain copying of LONG VARCHAR, but the amount of disk I/O is about the same, so the optimization rules discussed below are important only for time-critical, memory-located database applications. The Virtuoso Server tries to reduce the number of cuttings to an absolute minimum. First of all, cutting is not performed when a given XML entity refers to the root of the document, or to the only child of the root, because the result of such cutting will be identical to original document. In addition, every document remembers the result of last cutting performed on data from this document, so if data of some XML entity are saved in many places without saving of other XML entities between them, cutting will be done only once and plain copying will be done for every subsequent saving.

Function: xper_doc

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an entity object ('XPER entity') created from an XML document This parses the argument, which is expected to be a well formed XML fragment and returns a parse tree as a special object with underlying disk structure, named "persistent XML" or "XPER" While the result of xml_tree is a memory-resident array of vectors, the XPER object consumes only a little amount of memory, and almost all data are disk-resident. XPERs are better then "XML trees" for large documents and for "write once -- read many" stores such as a table with one XML document per row used as a "library" of documents. To be saved in a LONG VARCHAR column, "XML tree" entity will be converted back to plain text of XML syntax; but "XPER" entity will be saved as a ready-to-use disk structure.

Function: xper_locate_words

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns a smallest fragment of persistent XML entity object ('XPER entity') such that it contains some range of words in its textThis receives the XML entity and returns its fragment or signals an error.

Function: XPER navigation

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

low-level navigation functions for persistent XMLs, useful for import of huge amounts of XML data All these functions work with "persistent XML" (XPER) entities only, signalling errors if given entity points to "XML tree". They are useful when applications need to read a huge XML document, especially something like a datasheet dump or event log with a large number of uniform records, and is required to process all records of the document, e.g. import them into the database. Consider a real sample of import all data from ODP's content.xml dump which contains more than 2,000,000 descriptions of various Web-sites, and the length of the file is more than 600Mb. The file has root element named 'RDF' and all descriptions are their children named either 'Topic' or 'ExternalPage'. This code looks suitable for importing these children: It looks fine and it passes small tests but it will not work on real data!

Function: xpf_extension

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

declare an XPath extension function This function is used to declare a new XPath extension function or redefine an existing function. It can be used in XPath queries and XSLT stylesheets. You should use QNames for extension functions. Note that the standard XPath functions cannot be redefined. xpf_extension() stores the functions into the SYS_XPF_EXTENSIONS system table. The input parameters will be retrieved as a strings and then will be converted to the datatype of the corresponding argument of the stored procedure.

Function: xpf_extension_remove

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

discards an XPath extension functionRemoves a user-defined XPath function.

Function: xquery_eval

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Applies an XQUERY expression to a context node and returns result(s). The xquery_eval function returns the result of applying the xquery expression to the context node. By default only the first result is returned, but supplying a third argument allows you to specify an index for the value, the default assumes a value of 1 here. A value of 0 returns an array of 0 or more elements, one for each value calculated by the xquery expression. When an entity is returned in a result set to a client the client will see an nvarchar value containing the serialization of the entity, complete with markup. When the entity is passed as a SQL value it remains an entity referencing the node of a parsed XML tree, permitting navigation inside the tree. The expression can be passed parameters by specifying a fourth argument to xquery_eval(). This will be a vector of name/value pairs. The values can be referenced from inside XPath expression by using their names with '$' prefix. You may use any Virtuoso data type. The names in the parameter vector should appear without the '$' sign. If any of the parameter values is NULL the parameter will be ignored because NULL has no XPath counterpart. If the same name appears more than once in the vector, the last name/value pair is used and all preceding pairs with this name are silently ignored. Obviously, names should be strings that are valid XQuery variable names.

Function: xslt

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an XML document transformed by an XSLT stylesheet This function takes the URI of a stylesheet and an XML entity and produces an XML entity representing the transformation result of the given entity with the given stylesheet. The result tree is separate from the argument tree and the only reference to it is the returned entity. Errors occurring in the transformation will be signalled as SQL states, with XML or XSLT specific conditions beginning with XS or XP. The stylesheet can be passed parameters by specifying a third argument to xslt(). This will be a vector of name/value pairs. The values can be referenced from inside XPath expressions in the stylesheet. You may use any Virtuoso data type. The names in the parameter vector should appear without the '$' sign. If any of the parameter values is NULL the parameter will be ignored because NULL has no XPath counterpart. If the same name appears more than once in the vector, the last name/value pair is used and all preceding pairs with this name are silently ignored. Obviously, names should be strings that are valid XPath variable names. xslt() applies the transformation in the sheet to the specified entity. The result is the root element of the result tree, an XML entity. This entity can be used as input to another transformation, can be serialized and sent to an HTTP client or stored, etc.

Function: xslt_format_number

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns formatted string representation of a numeric valuexslt_format_number is an function wrapper for the format-number() XSLT function. It always uses the default formatting parameters described in the XSLT standard.

Function: xslt_sheet

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

declares an XSL stylesheet for use This function takes a name and the root element of a parsed XML document and defines these as a stylesheet. The unique element child of the entity object's document should be an xsl:stylesheet element. Included or imported stylesheets will be located relative to the base URI of the entity passed to xslt_sheet(). Once a stylesheet thus defined it can be used as the stylesheet argument of xslt.

Function: xslt_stale

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

force reload of XSL stylesheet This function can be used to force Virtuoso to reload a cached stylesheet from the URI when next used with xslt() or http_xslt(). Using this function before every application of the stylesheet is extremely inefficient. If stylesheets are stored in the database, you can use this function in an update trigger on the table storing the stylesheets but you don't have to use it before every application of the sheet. This function never needs to be applied to a stylesheet URI with the file:// protocol since xslt() and http_xslt() will automatically detect a stale cache entry. However if the stylesheet is stored on a remote web server, or if the stylesheet contains subdocuments ( e.g. external XML entities, xsl:include or xsl:import statements) this function is needed to force a reload.

Function: xtree_doc

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

returns an entity object created from an XML document This parses the argument, which is expected to be a well formed XML fragment and returns a parse tree as a special memory-resident object. While xper_doc creates some disk-resident data structure, xtree_doc() will work faster but it may require more memory. You may wish to use xtree_doc for small documents (e.g. less than 5 megabytes and xper_doc for larger documents.

Function: xmlStorageSystem.registerUser

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Register a user with the XML Storage SystemThis method allows users to register within XML Storage System. The actions performed on the server are:

Function: xmlStorageSystem.mailPasswordToUser

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Mail password to user.This method is used to send the password for user identified by email. To work properly the default SMTP server Virtuoso INI file setting must be set properly.

Function: xmlStorageSystem.getServerCapabilities

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Retrieve server specific information.This method is used to obtain information about the capabilities of the server, such as files size limitations, supported types, etc...

Function: xmlStorageSystem.deleteMultipleFiles

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Remove files from XML Storage System DirectoryThis method is used for removing files from the repository.

Function: xmlStorageSystem.saveMultipleFiles

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Upload a set of files to XML Storage System directory.This method allows users to upload a set of files. The files will be stored in WebDAV repository and will be accessible via HTTP.

Function: XMLType.XMLType

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The method creates an XMLType instance from src XML entity. If parameter src is not an XML entity then it is converted to it via internal call of xtree_doc() or xml_tree_doc(). A schema may be associated with an XML entity by passing its URI as schema_uri; this schema can be used later to validate the structure of the document.

Function: XMLType.createNonSchemaBasedXML

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a copy of the given instance with the schema reference removed.The function returns a copy of the given instance with the schema reference removed.

Function: XMLType.createSchemaBasedXML

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a copy of the given instance with new schema reference.The function creates a new instance of XMLType by copying the given one and assigning a new schema URL to it. Parameterschema_url specifies a new URL; if it is omitted then a non-schema based instance is created like the XMLType.createNonSchemaBasedXML() function. The returned copy has an internal "validated" flag set to 0, even if the new URL is equal to the URL of the original instance.

Function: XMLType.createXML

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates an XML Type instance.The static method creates an XMLType instance from the src XML entity. If the parameter src is not an XML entity then it is converted to it via an internal call of xtree_doc() or xml_tree_doc(). A schema may be associated with an XML entity by passing its URI as schema_uri; this schema can be used later to validate the structure of the document.

Function: XMLType.existsNode

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Tests node existence having evaluated given XPATH expression.The member function calculates the given XPATH expression xpath_expn using the XML entity of the instance as a context node. If a namespace_map parameter is given then the function adds namespace declarations from this parameter into the beginning of xpath_expn before the evaluation. The function returns 1 if the first result of XPATH evaluation is a node or 0 if there are no results or if the first result is not a node.

Function: XMLType.extract

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Evaluates given XPATH expression.The member function calculates the given XPATH expression xpath_expn using the XML entity of the instance as a context node. If a namespace_map parameter is given then the function adds namespace declarations from this parameter into the beginning of xpath_expn before the evaluation. The function returns the first result of the XPATH evaluation or NULL if there are no results. If the result is an XML entity then it is converted into a non-schema based instance of XMLType.

Function: XMLType.getClobVal

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function returns the serialization of the current node like XPATH function 'serialize()', i.e. a text in XML syntax.This function returns the serialization of the current node. This is similar to the XPATH function 'serialize()', i.e. a text in XML syntax.

Function: XMLType.getNamespace

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the namespace of the top level element providing the instance is schema-based rather than a fragment.The member function returns the namespace URI of the top level element providing that the given instance is schema-based and is well-formed. This function returns NULL if the instance is a fragment. If there are many top level elements then they may have different namespace URIs and if there is no top level element then there is nothing to return. It also returns NULL if the instance is non-schema based for compatibility.

Function: XMLType.getNumVal

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This function returns the integer-value of the current node like XPATH function 'number()'.This function returns the integer-value of the current node. This is similar to the XPATH function 'number()'.

Function: XMLType.getRootElement

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns top-level element of the given instance (NULL for fragment)If the given instance is well-formed then this function will return the top-level element of the document that is stored within the instance. If the given instance is a fragment then NULL will be returned because there may be no top-level elements or too many of them. Note that in spite of this functions name this function actually returns the a top-level node rather than not a root node. According to the W3C XPATH standards, the root element is an implicit node whose children are top-level elements, comments, processing instructions and maybe text nodes. E.g. if a correct HTML document is started by tag and ended by corresponding tag then the only top-level node is the "HTML" element node and this node is a single child of the root node. If the given instance is well-formed then the function returns a top-level element of the document that is stored in the instance. If the given instance is fragment then NULL is returned, because there may be no top-level elements or too many of them.

Function: XMLType.getSchemaURL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the URL of the XML schema definition for schema based instances, NULL for non-schema based.The function returns the URL of the XML Types associate XML schema. This applies only to schema based instances. It will return NULL for non-schema based types.

Function: XMLType.getStringVal

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The function returns the string-value of the current node like XPATH function 'string()'.The function returns the string-value of the current node. This is similar to the XPATH function 'string()'.

Function: XMLType.isFragment

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The function returns 1 if the instance is an XML generic entity or 0 if it is a plain document.The function checks the number of children elements of the root of the document root of the given instance. If there are no such documents or there are many of them then the document is not well-formed, for example it can not be fully validated against an XML schema. However it can be used as a fragment of a larger document: it can be declared as an external generic entity and then referenced in a top-level document or in one of its subdocuments. For example a book can be stored in XML as a root document that includes subdocuments, one or more chapter per subdocument. The function returns 1 if the given XMLType instance is a fragment and returns 0 if it is a well-formed XML document.

Function: XMLType.isSchemaBased

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns 1 if the given XMLType instance is schema-based, otherwise returns 0.Returns 1 if the given XMLType instance is schema-based, i.e. if it has a URI of an XML schema that can be used for schema validation via XMLType.schemaValidate().

Function: XMLType.isSchemaValid

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Validates the given XMLType instance against an arbitrary XML schema, returns 1 if successful, 0 if errors are detected.The function validates the given XMLType instance against the XML schema located at schema_url. The name of the current node of the XML entity should match top_element_name if it is specified. The schema_url is optional for schema based instances: the default value is the URI of the associated schema of the instance. For non-schema based instances the schema_url is required, an error is signalled otherwise. The function does not use or modify internal "validated" flag that is e.g. used by XMLType.schemaValidate(). It is true even if the given schema_url is equal to the URI of own schema of the instance.

Function: XMLType.isSchemaValidated

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns 1 or 0 indicating if the XML entity has been validated against the associated schema.The function returns the value of a special internal "is validated" flag of the given XMLType instance.

Function: XMLType.schemaValidate

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Validates the schema based XMLType instance against its schema and signals an error in case of failed validation.The member function signals an error if called for a non-schema based instance. If an instance is schema-based but the validation has already been done, the call has no effect. Otherwise, a schema-based instance is validated against its schema. If the validation fails, an error is signalled. If the validation is successful then a special internal "validated"flag is set.

Function: XMLType.setSchemaValidated

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Changes the internal "is validated" flag of the given XMLType instance.Every XMLType instance has a special internal "is validated" flag; The first successful call of the member function XMLType.schemaValidate() will set this flag to 1 indicating that next such calls are redundant and should do nothing. If a given XMLType instance is made by a procedure that guarantees the match of the result to an expected schema then one can set this flag without running actual validation. It is also possible to reset this flag to 0 in order to force the next call of XMLType.schemaValidate() to perform a validation.

Function: XMLType.toObject

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This member function is not yet implemented.

Function: XMLType.transform

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This member function is not implemented and signals an error if called. Use xslt() built-in function instead.

Function: sql:column

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the value of a column from SQL result-set.This is actually not a function but a special macro that is converted to a reference to a global parameter.

Function: and

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns false if a value of some argument is false, otherwise returns true. This function calculates the values of its arguments from left to right. If the value of the calculated parameter is false, the function returns false immediately, without calculating the remaining parameters. If the list of arguments ends without any false value calculated, the function returns true (thus it will return true if called without arguments). The name of this function is the same as the name of "and" XPATH and XQUERY operator. Thus it must be surrounded by double quotes when used in XPATH or XQUERY expressions. Moreover, this function is not a part of XPATH standard, so it cannot be used if portability is important.

Function: append

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates an sequence of all items from given sequences. This function calculates all given arguments from left to right, and creates a sequence which contains all items of the first calculated sequence, then all items of the second calculated sequence and so on, preserving the order of items from every sequence. The result is identical to the result of XQUERY "comma operator". This function is not a part of XPATH 1.0 or XQUERY 1.0 libraries of standard functions.

Function: assign

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a local variable and assign a value to it. This function calculates the first argument, var_name, and converts it to the string, if needed. Then it checks if there is a local variable or parameter with such name. If not found, it checks if there is a global variable or parameter with such name. If nothing found in both cases, a new local variable is created with this name. The the value of found or created variable is changed to the value of the second argument, var_value. The value of the variable may be accessed like the value of any variable created by XSL element or FLWR operator of XQUERY. The same $name should be used to get the value. In XSLT, common rules for local variables are used for variables created by assign() function.

Function: avg

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns average value of all its arguments. The function returns the average of all values in all its arguments, For each node in every argument node-set, it converts the string-value of the node to a number and adds the result to the sum. If some arguments are not node-sets, they are converted to numbers first and added to the sum. Then sum is divided by number of values added and the result is returned. This function is not a part of XPATH 1.0 standard library.

Function: boolean

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts its argument to boolean The function converts its argument to a boolean as follows:

Function: ceiling

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the smallest integer that is not less than the argument. This function returns the smallest (closest to negative infinity) number that is not less than the argument and that is an integer. In other words, it "rounds up" the given value.

Function: fn:collection

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns parsed documents contained in given collections. This function takes one or more collection URI's and returns the parsed documents contained in these collections as a sequence. If no uri is specified, the function returns the sequence of the nodes in the default collection in the dynamic context. The default collection is a home DAV collection. If user does not have default DAV collection, an error is signalled. The recursive_mode arguments sets the mode for processing sub-collection. If recursive_mode is set to 0 all sub-collections are ignored. fn:collection collects documents recursively if the argument is set to 1. The recursive mode is the default.

Function: concat

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the concatenation of its arguments. The function converts all its arguments into strings using the same rules as XPATH function string(), then it performs concatenation and returns the resulting string. XPATH 1.0 standard states that concat() function must have at least 2 arguments, but in Virtuoso XPATH this restriction is eliminated. concat() may be called without arguments (it will return an empty string) or with one argument (it will work like string() function). This may be useful if the text of XPATH expression must be generated by an application.

Function: contains

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if the first argument string contains the second argument string, and otherwise returns false. For two given strings, this function checks if the first string contains the second string. If any argument is not a string, it is converted to string using rules from string() XPATH function. Thus if the second argument has no string value, the function returns true, because it will be converted to an empty string first.

Function: count

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the number of values in the sequence.Returns 1 if the argument is a single value or a count of elements in the given sequence of values. This function must be called with an argument, it do nothing with context. To count nodes in context node-set, use last().

Function: create-attribute

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a special "attribute descriptor" object. This is an internal XQUERY function and you will probably never need to call it explicitly. It is not a part of library of standard XQUERY 1.0 functions. This function creates an special object, called "attribute descriptor", which may be used only as argument of create-element() XQUERY function. Every attribute descriptor will force create-element() function to add an attribute with specified name and value into opening tag of the created element. If attribute with such name already exists, its value will be replaced.

Function: create-comment

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a "comment" XML tree entity. This is an internal XQUERY function and you will probably never need to call it explicitly. It is not a part of library of standard XQUERY 1.0 functions. This function creates an XML entity of sort "comment" that contains given text.

Function: create-element

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates an element with specified name, attributes and children This is an internal XQUERY function and you will probably never need to call it explicitly. It is not a part of library of standard XQUERY 1.0 functions. This function creates a new "XML Tree" element whose name is a string-value of the first item of head sequence, with attributes and children specified by the rest of head sequence and by the list of arguments child1, child2, ... childN.

Function: create-pi

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates a "processing instruction" XML tree entity. This is an internal XQUERY function and you will probably never need to call it explicitly. It is not a part of library of standard XQUERY 1.0 functions. This function creates an XML entity of sort "processing instruction". If pivalue is an empty string, the resulting processing instruction will have no value at all, exactly as if the pivalue is not passed at all.

Function: current

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a node-set that has the current node as its only member. The function returns a node-set that has the current node as its only member. For an outermost expression (an expression not occurring within another expression), the current node is always the same as the context node. For an expression occurring within another expression, e.g. within predicate in some path, the current node is the same as the context node of the first step in the path. Please refer XSL standard before the first use of this function, to understand exact difference between "current" and "context" node. XSLT 1.0 states that it is an error to use the current() function in a XSL "pattern", e.g. in "match" attribute of element, because patterns have no value assigned for current node assigned processing. Instead of reporting the error, Virtuoso's XSLT processor uses context node if current node is not set.

Function: distinct

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Removes double entities from the input sequence The function takes a single parameter which is sequence of XML entities (nodes or values) and returns the sequence that results from removing from input sequence all but one of a set of elements that are identical each other. If input sequence is the empty, the empty sequence is returned. Note that the distinct is not a part of XPATH 1.0 or XQuery 1.0 standard library, it is rather a generalization of standard distinct-nodes and distinct-values functions.

Function: doc

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns data from XML doc other than the main source document. The function tries to access an XML text at location specified by document_uri. If the document_uri argument is node-set, not a string, then a node-set is returned as if document() function is applied to string-value of the first node of the node-set. The result of call doc($uri) is similar to the call of function document() with default parameters:

Function: document

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns data from XML documents other than the main source document. The function tries to access an XML text at location specified by document_uri and optionally base_uri. On success, it parses the text and returns the root entity of the "XML Tree" document; the result is identical to the entity created by xtree_doc() Virtuoso/PL function. If the document_uri argument is node-set, not a string, then a node-set is returned as if document() function is applied to string-value of every node of the node-set. Note that the list of attributes of the function differs from specified in XSLT 1.0 standard. In XPATH 1.0, there is no such function at all.

Function: document-literal

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Parses given XML text and returns the resulting XML data. The function tries to parse an XML text as if it is obtained from a location specified by cache_uri. On success, it returns the root entity of the "XML Tree" document; the result is identical to the entity created by xtree_doc() Virtuoso/PL function. When XPath processor parses a document, it saves it in a temporary cache. If a cached document is accessed again then no actual retrieval or parsing is made and a cached value is returned. The cache persists till the end of execution of a XPath query or till the end of the XSLT transformation if the XPath expression is a part of XSLT stylesheet. The cache_uri specifies the URI used as a key if the parsed document is cached. If cache_uri is not specified or the specified value is equal to an empty string, then no caching is performed. If the specified cache_uri is not equal to an empty string then it should distinct from URIs of other XML resources that are sources of the XPath query, to prevent confusion. The cache_uri is also used by XML parser as a base URI to resolve relative URIs of external entities, so it is a good idea to specify some absolute URI if the parsed text is not a "standalone" document.

Function: empty

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if given argument is an empty sequence, false if it is any single value or nonempty sequence.Returns true if given argument is an empty sequence, false if it is any single value or nonempty sequence.

Function: ends-with

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if the first argument string ends with the second argument string, and otherwise returns false.For two given strings, this function checks if the first string ends with characters of second string. If any argument is not a string, it is converted to string using rules from string() XPATH function. Thus if the second argument has no string value, the function returns true, because it will be converted to an empty string first. Unlike start-with() XPATH function, this function is not described in XPATH 1.0 standard. To write portable XPATH expression, use substring().

Function: every

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if all items of given sequence matches given criterion. The function creates a temporary local variable, whose name is specified by varname argument. Then, for every item of test_set sequence it calculates the test_expn boolean expression having set the created variable to that "current" item. If the value of expression is false, the function immediately returns false without processing the rest of test_set sequence. If all items of the sequence are probed without getting false, true is returned. (So if the sequence is empty, the function returns true). In any case, temporary variable is destroyed on return. This function is used in the implementation of "EVERY" logical operator in XQUERY, so you will probably use that operator in XQUERY expressions, not the function. This function may be useful in XPATH expressions and in XSLT stylesheets. It is not a part of library of standard XQUERY 1.0 functions.

Function: except

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a difference of two setsThe function returns an unordered sequence that consists of all distinct items from the first sequence that are missing in the second sequence. Duplicate values from set1 are removed, the decision whether two values duplicate each other is made according rules used by distinct() function.

Function: false

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns false.This function returns boolean constant "false".

Function: filter

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Composes trees of shallow copies of given XML entities.The function takes a single parameter which can be any expression. The function evaluates its argument and returns a shallow copy of the nodes that are selected by the argument, preserving any relationships that exist among these nodes. Duplicate nodes are removed before the processing. The structure of the resulting node-set may be explained in the following way. First of all, all input entities are grouped by their documents, so we have a set of distinct documents and for every document we have a list of entities that refers to various nodes of the document. After that, every such document is processed separately, and the result of processing is a node-set; the union of these node-sets will be returned as the result of the call of filter() function. A copy of the document is made, and a "color" is assigned to every node of the copy: it's "black if the original node is listed in the selection sequence, otherwise it's "white". Then "white" nodes are removed from the copy, node after node: if a "white" node may be found, it is replaced with list of its children. Finally, we have a list of one or more "black" nodes whose descendants are all "black", too, and this list is added into the resulting node-set. (The actual algorithm is much faster and much more complicated than the described one, but the result is identical.)

Function: floor

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the largest integer that is not greater than the argument. This function returns the largest (closest to positive infinity) number that is not greater than the argument and that is an integer. In other words, it "rounds down" the given value.

Function: for

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Repeats some calculation for every item of a given sequence The function creates a temporary local variable, whose name is specified by varname argument. Then, for every item of source_set sequence it calculates the value of mapping_expn expression having set the created variable to that "current" item. It returns the "flattened" sequence of values returned by mapping_expn in the same order as they are calculated. "Flattened" means that if mapping_expn returns an sequence, items of this sequence will be added into the end of resulting sequence, one by one, instead of adding one item of type "sequence". The temporary variable is destroyed on return. This function is used in the implementation of "FOR" control operator in XQUERY, so you will probably use that operator in XQUERY expressions, not the function. This function may be useful in XPATH expressions and in XSLT stylesheets. It is not a part of library of standard XQUERY 1.0 functions.

Function: format-number

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

The function converts the num argument to a string using the format pattern string specified by the format_pattern and the decimal-format named by the decimal_format, or the default decimal-format, if there is no third argument. The format pattern string is in the syntax specified by the JDK 1.1 DecimalFormat class. The following describes the structure of the pattern. The pattern consists of one or two subpatterns, first is for positive numbers and zero, second is for negative numbers. Two subpatterns are delimited by semicolon. If there is only one subpattern, - is prefixed to the positive subpattern. Every subpattern consists of optional prefix characters followed by an integer part followed by an optional fraction part followed by an optional suffix characters. Prefix and suffix characters are any Unicode characters except special formatting characters described below, while integer and fraction part consist only from that special formatting characters. (As an exception, special characters may appear in prefix in suffix parts if enclosed in single quotes. If fractional present, it starts from '.' character, and only one '.' may occur in the subformat. Thus it is easy to find where each part begins. By default, the following characters are treated as special when used in the parts of the subpattern: SymbolMeaning 0A digit, zero will be printed. 0 must be the last character of integer part. #A digit, zero will not be printed. .Placeholder for decimal separator in the beginning of fraction part. ,Placeholder for grouping separator. It may appear only in integer part. All commas except the last will be ignored. ;Separates formats. It may appear only once in the pattern. -Placeholder for negative prefix. %Indicates that the value must be multiplied by 100 and shown as percentage. ?Indicates that the value must be multiplied by 1000 and shown as per mille. Note that character '�' have a special meaning in DecimalFormat of JDK 1.1, but not in XPATH.

Function: function-available

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if XPATH extension function with the requested name is defined in the XPATH Processor, otherwise returns false. The function returns true if XPATH Processor can execute XPATH extension function with the name specified by funname argument. If such function is not defined, function-available returns false.

Function: generate-id

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a string that uniquely identifies the node. The function returns a string that uniquely identifies the first node in the place argument node-set. The unique identifier will consist of ASCII alphanumeric characters and will start with an alphabetic character. Thus, the string is syntactically an XML name. It always generates the same identifier for the same node. It always generates different identifiers from different nodes. This function is under no obligation to generate the same identifiers each time a document is transformed. There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document. If the argument node-set is empty, the empty string is returned. If the argument is omitted, it defaults to the context node.

Function: id

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns an entities whose ID attributes are in the given list The function gets a list of strings, where every string is a list of IDs delimited by whitespace characters. For every listed ID, the function checks if the document that contains the context entity also contains an entity with such ID; if the entity with the listed ID exists, it is added into the sequence. To avoid searches of every ID inside the whole document, the function uses "ID cache" that is created if "IdCache=ENABLE" DTD configuration option is specified in the call of function that parses the XML document. In some cases, it is possible to build such cache on demand if it is not built by a parser, but it consumes time and in any case it requires the saved DTD information from the XML parser, so the parser should be specially configured anyway. Note that any attribute of types ID, IDREF or IDREFS is a good input string for the function id(). So while XQuery "pointer operator" is not available in XPath expression, the id() function is a good replacement for it.

Function: if

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

If the boolean value is true then calculates one expression, otherwise calculates another expression. This function calculates the value of test argument. If the value is true, the function calculates the then_branch expression and returns its value. If the value is false, the function calculates the else_branch expression and returns its value. Note that unlike other programming languages, else_branch is required argument, not optional. This function is used in the implementation of "IF" control operator in XQUERY, so you will probably use that operator in XQUERY expressions, not the function. This function may be useful in XPATH expressions and in XSLT stylesheets. It is not a part of library of standard XQUERY 1.0 functions.

Function: intersect

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns an intersect of two setsThe function returns an unordered sequence that consists of all distinct items such that every of source sequences contains every of the resulting items. Duplicates are removed, including duplicate occurrences of same value in one sequence, the decision whether two values duplicate each other is made according rules used by distinct() function.

Function: is_after()

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if the given entity is after the second given entity in document order, otherwise returns false. The function ensures that both ent1 and ent2 are XML entities and the returns true if ent1 and ent2 are both in the same XML document and ent1 is strictly after ent2 in document order. It returns false if one of them is not an entity but an empty node-set or if their documents differ or or if they're equal or if one of them is an ancestor of other or if ent1 is simply before ent2 in document order.

Function: is_before()

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if the given entity is before the second given entity in document order, otherwise returns false. The function ensures that both ent1 and ent2 are XML entities and the returns true if ent1 and ent2 are both in the same XML document and ent1 is strictly before ent2 in document order. It returns false if one of them is not an entity but an empty node-set or if their documents differ or or if they're equal or if one of them is an ancestor of other or if ent1 is simply after ent2 in document order.

Function: key

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

This XSLT 1.0 function is not implemented in the current version of Virtuoso.

Function: lang

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if the language of context node matches given language name. The lang function returns true or false depending on whether the language of the context node as specified by xml:lang attributes is the same as or is a sublanguage of the language specified by the argument string. The language of the context node is determined by the value of the xml:lang attribute on the context node, or, if the context node has no xml:lang attribute, by the value of the xml:lang attribute on the nearest ancestor of the context node that has an xml:lang attribute. If there is no such attribute, then lang returns false. If there is such an attribute, then lang returns true if the attribute value is equal to the argument ignoring case, or if there is some suffix starting with "-" such that the attribute value is equal to the argument ignoring that suffix of the attribute value and ignoring case.

Function: last

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the context size from expression evaluation context. Context size is the number of nodes in the node-set where the context node comes from. For the most popular case, when last() is used inside a predicate, and the predicate relates to some axis of the path, last() is the number of elements found by that axis at once; in other words, the number of elements to be tested by predicate.

Function: let

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Creates temporary variables and calculates an expression that uses these variables For every pair of arguments, the function calculates values of these arguments and then creates a new temporary local variable whose name is the string value of the first argument in pair and the value assigned is the value of the second argument in pair. Obviously, the argument for variable name is usually a constant string of alphanumeric characters. The expression for a value of variable number I may refer to variables created during steps 1 to I-1. When all pairs of arguments are turned into temporary variables, the last argument is calculated and its value is returned as the value of the whole expression. Temporary variables are destroyed on return. This function is used in the implementation of "LET" control operator in XQUERY, so you will probably use that operator in XQUERY expressions, not the function. This function may be useful in XPATH expressions and in XSLT stylesheets. It is not a part of library of standard XQUERY 1.0 functions.

Function: list()

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Selects the first item of every argument sequence and returns the sequence of the selected items This function calculates all given arguments from left to right, and creates a sequence which contains the first item of the first calculated sequence, then the first item of the second calculated sequence and so on. If the value of an argument is not a sequence, but a scalar, the scalar is treated as one-element sequence so it is added into the result. If the value of an argument is an empry sequence, nothing is added into the result (unlike function tuple() that adds an empty string in this case). This function is not a part of XPATH 1.0 or XQUERY 1.0 libraries of standard functions.

Function: local-name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the local part of the expanded name of the argument.For given node, it returns local part of the node, i.e. the name of given attribute or element with namespace prefix removed. If the argument is node-set, first node of the node-set will be considered. Empty string is returned if the argument is an empty node-set, a node without name or if the argument is not a node. If the argument is omitted, context node is used instead as if it is a node-set of one element.

Function: max

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns maximum value among all its arguments. The function returns the maximum value among all values in all its arguments, For each node in every argument node-set, it converts the string-value of the node to a number. If some arguments are not node-sets, they are converted to numbers. The maximum number found is returned. This function is not a part of XPATH 1.0 standard library.

Function: min

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns minimum value among all its arguments. The function returns the minimum value among all values in all its arguments, For each node in every argument node-set, it converts the string-value of the node to a number. If some arguments are not node-sets, they are converted to numbers. The minimum number found is returned. This function is not a part of XPATH 1.0 standard library.

Function: name

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the expanded name of the argument.For given node, it returns extended name of the node, i.e. the name of given attribute or element with namespace prefix replaced with namespace URI string. If the argument is node-set, first node of the node-set will be considered. Empty string is returned if the argument is an empty node-set, a node without name or if the argument is not a node. If the argument is omitted, context node is used instead as if it is a node-set of one element.

Function: namespace-uri

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the namespace URI of the extended name of the given nodeIf given argument is a node, the function returns the URI string of the namespace specified in the name of node. If the argument is node-set, first node of the node-set will be considered. Empty string is returned if the argument is an empty node-set, a node without name or if the argument is not a node. If the argument is omitted, context node is used instead as if it is a node-set of one element.

Function: normalize-space

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the argument string with whitespace normalized. The function returns the argument string with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of whitespace characters by a single space. Whitespace characters are the same as those allowed by the S production in XML, i.e. space (#x20), carriage returns (#xD), line feeds (#xA), and tabs (#x9). If the argument is omitted, it defaults to the context node converted to a string, in other words the string-value of the context node.

Function: not

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if its argument is false, and false otherwise. This function returns true if its argument is false, and false otherwise. If the argument is not a value of boolean type, it will be converted to boolean first.

Function: number

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Converts its argument to a number. The number function converts its argument to a number as follows: If the argument is omitted, it defaults to a node-set with the context node as its only member.

Function: or

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if a value of some argument is true, otherwise returns false. This function calculates values of its arguments, from left to right. If the value of calculated parameter is true, the function returns true immediately, without calculating of the remaining parameters. If the list of arguments ends without any true value calculated, the function returns false (Thus it returns true when called without arguments). The name of this function is the same as name of "or" XPATH and XQUERY operator. Thus it must be surrounded by double quotes when used in XPATH or XQUERY expressions. Moreover, this function is not a part of XPATH standard, so it cannot be used if portability is important.

Function: position

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the context position from expression evaluation context. Context position is the number of nodes in the node-set where the context node comes from. For the most popular case, when position() is used inside a predicate, and the predicate relates to some axis of the path, position() is the number of calls of the predicate, including the "current" call which is in progress when the function is called. Thus, context position cannot be greater than context size.

Function: processXQuery

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Calls an XQuery module from XPath expression, e.g. from some XSLT or BPEL code. This function takes a URI of an XQuery module and an XML entity and calls the module with the entity as a context. Depending on value of index parameter, either the result of the module is returned 'as is' or the sequence of results is returned. Parameters can be passed to the module by specifying additional arguments to processXQuery(). The names of parameters should appear in argument list without the leading '$' sign. Unlike xquery_eval() function, parameter can not be ignored depending on the type of its value. If the same name appears more than once in the vector, the last name/value pair is used and all preceding pairs with this name are silently ignored. Obviously, names should be strings that are valid XPath variable names. The XQuery standard does not offer a way of calling of a module from other XQuery expression. The reason is that there's no need for such calling if the code is designed properly. If an expression is re-used in various places then it should be turned into a function and placed into an XQuery library module; one should import the module and call the function instead of calling a non-library module. It is possible to use processXQuery() in XQuery expressions but it is much better to use library modules instead, and to use processXQuery() only for tricks in XPATH expressions.

Function: processXSLT

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Applies stylesheet to given XML entity and returns the result. This function takes the URI of a stylesheet and an XML entity and produces an XML entity representing the transformation result of the given entity with the given stylesheet. The result tree is separate from the argument tree and the only reference to it is the returned entity. Errors occurring in the transformation will be signalled as SQL states, with XML or XSLT specific conditions beginning with XS or XP. The stylesheet is applied to the value of source parameter. Obviously, source must be an entity. If source is not specified then the stylesheet is applied to the current entity. Parameters can be passed to the stylesheet by specifying additional arguments to processXSLT(). The values can be referenced from inside XPath expressions in the stylesheet. The names of parameters should appear in argument list without the leading '$' sign. Unlike xslt() function, parameter can not be ignored depending on the type of its value. If the same name appears more than once in the vector, the last name/value pair is used and all preceding pairs with this name are silently ignored. Obviously, names should be strings that are valid XPath variable names.

Function: processXSQL

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Executes XSQL page and returns the result. This function takes a URI of an XSQL page, compiles the page into a Virtuoso/PL procedure (if not compiled earlier) and executes the compiled procedure. The current entity is passed to the page procedure as "context XML" argument. The function returns the XML document composed by page procedure. The result tree is separate from the argument tree and the only reference to it is the returned entity. For compatibility, the processXSQL() function can also be called as http://schemas.oracle.com/xpath/extension:processXSQL().

Function: progn()

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Calculates all given expressions and returns the result produced by the last one. This function calculates its first argument, then second argument and so on. The results of these calculations are not used, except the result of the last expression which is returned. The only useful application for this function is calling XPath extension functions for side effects. This function is not a part of library of standard XQuery 1.0 functions.

Function: replace()

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Searches for an substring and replace its occurrences with other substring. The function searches for all occurrences of a search_strg in txt and replaces every occurrence with replace_strg. An error is signalled if search_strg is empty.

Function: round

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the integer that is the nearest to the argument. The function returns the number that is closest to the argument and that is an integer. If there are two such numbers, then the one that is closest to positive infinity is returned. If the argument is NaN, then NaN is returned. If the argument is positive infinity, then positive infinity is returned. If the argument is negative infinity, then negative infinity is returned.

Function: serialize

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Serializes a value of its argument following the rules of the host RDBMS.The serialize() function converts an object to a string as follows: If the argument is omitted, context node is converted instead as if it is a node-set of one element.

Function: shallow

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a shallow copy of the given XML entity The function returns a shallow copy of the given XML entity, i.e. a root of a new document that consists of only one node that is a copy of the given entity but have no children.

Function: some

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if at least one item of given sequence matches given criterion. The function creates a temporary local variable, whose name is specified by varname argument. Then, for every item of test_set sequence it calculates the test_expn boolean expression having set the created variable to that "current" item. If the value of expression is true, the function immediately returns true without processing the rest of test_set sequence. If all items of the sequence are probed without getting true, false is returned. (So if the sequence is empty, the function returns false). In any case, temporary variable is destroyed on return. This function is used in the implementation of "SOME" logical operator in XQUERY, so you will probably use that operator in XQUERY expressions, not the function. This function may be useful in XPATH expressions and in XSLT stylesheets. It is not a part of library of standard XQUERY 1.0 functions.

Function: starts-with

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns true if the first argument string starts with the second argument string, and otherwise returns false.For two given strings, this function checks if the first string starts with characters of second string. If any argument is not a string, it is converted to string using rules for string() XPATH function. Thus if the second argument has no string value, the function returns true, because it will be converted to an empty string first.

Function: string

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a string value of its argument.The string() function converts an object to a string as follows: If the argument is omitted, context node is converted instead as if it is a node-set of one element.

Function: string-length

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the number of characters in the string. The string-length() XPATH function returns the number of characters in the string. If the argument is omitted, it defaults to the context node converted to a string, in other words the string-value of the context node.

Function: substring

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the substring of the first argument starting at the position specified in the second argument with length specified in the third argument. The substring() XPATH function returns the substring of the strg starting at the position specified in start argument with length specified in length argument. If length is not specified, it returns the substring starting at the position specified in the start argument and continuing to the end of the string. XPATH 1.0 defines that "each character in the string... is considered to have a numeric position: the position of the first character is 1, the position of the second character is 2 and so on. This differs from Java and ECMAScript, in which the String.substring method treats the position of the first character as 0." The returned substring contains those characters for which the position of the character is greater than or equal to start and, if length is specified, less than the sum of start and length. If start and/or length are not integers, they are converted to integers following rules for round() XPATH function, before doing any other processing. So they will be rounded first, and the sum of rounded values will be used as "end position"

Function: substring-after

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string. If the source_strg does not contain sub_strg, the function returns the empty string. Otherwise, it finds the first occurrence of sub_strg and returns the pert of source_strg that follows the occurrence. If any argument is not a string, it is converted to string using rules for string() XPATH function.

Function: substring-before

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string. If the source_strg does not contain sub_strg, the function returns the empty string. Otherwise, it finds the first occurrence of sub_strg and returns the pert of source_strg that precedes the occurrence. If any argument is not a string, it is converted to string using rules for string() XPATH function.

Function: sum

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns sum of all its arguments The function returns the sum, for each node in every argument node-set, of the result of converting the string-values of the node to a number. If some arguments are not node-sets, they are converted to numbers first. Note that this definition differs from XPATH 1.0 standard, where sum() function must have exactly one argument of type node-set. It is important that other XPATH processors may quietly ignore all arguments except the first one, producing unexpected results. Being called without arguments, sum() will return zero.

Function: system-property

virtuoso.docs@openlinksw.com — Thu, 05 Nov 2009 00:30:50 GMT

Returns a value of the system property identified by the name The function returns an object representing the value of the system property identified by the name. If there is no such system property, the empty string is returned.