http://docs.openlinksw.com/virtuoso/sqlprocedures.html SQL Procedure Language Guide OpenLink Virtuoso Universal Server: Documentation virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com 2008-11-25T00:17:53Z OpenLink Software Documentation Team http://docs.openlinksw.com/virtuoso/../images/misc/logo.jpg http://docs.openlinksw.com/virtuoso/GENERALPRINCIPLES.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com General Principles 2008-11-25T00:17:53Z General Principles A stored procedure is a named piece of Virtuoso/PL code stored in the SYS_PROCEDURES table. Stored procedures are created with the create procedure statement and are used by executing a procedure call statement through the regular SQL API. A procedure takes zero or more arguments and optionally returns a value. Procedure arguments may be input, output or input and output. In this manner a procedure may modify a variable passed to it by its caller. If the procedure is called from a call statement executed by a client process, the client process gets back the procedure's return value and the values of output parameters. Procedures can be called with positional or keyword parameters. A call with positional parameters will bind the first argument in the call to the first parameter in the procedure parameter list and so on. A keyword parameter call allows specifying named parameters, where the argument of a given name is bound to the parameter of the same name in the procedure's parameter list. Procedure parameters may be required or optional. The combination of optional parameters and the keyword call notation make it convenient to have procedures with large numbers of parameters of which only part are used at any one time. http://docs.openlinksw.com/virtuoso/SCOPEOFDECLARATION.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Scope of Declarations 2008-11-25T00:17:53Z Scope of Declarations A declaration can appear anywhere inside a compound statement. It affects all statements in the compound statement following the declaration statement. http://docs.openlinksw.com/virtuoso/sqlplDATATYPES.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Data Types 2008-11-25T00:17:53Z Data Types Virtuoso/PL supports the regular SQL scalar data types as well as user-defined-types (UDTs). UDTs and structures can be composed of data types or classes made from any hosted language such C# or Java. Local temporary tables are not supported by the present Virtuoso but may be added in the future. Memory management is automatic. Parameters, cursors and intermediate results are automatically allocated and freed. A parameter or variable can be of any data type a column can. Variables are however typed at run time, so that the declared type is mostly for documentation. The declared types also affect how interactive SQL shows certain values. http://docs.openlinksw.com/virtuoso/RESULTSETS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Handling Result Sets 2008-11-25T00:17:53Z Handling Result Sets A single Virtuoso procedure may produce multiple result sets, each with different result columns. A normal procedure produces one empty result set, only returning a possible return value and values of output parameters to the application. 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. http://docs.openlinksw.com/virtuoso/ARRAYS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Result Sets and Array Parameters 2008-11-25T00:17:53Z Result Sets and Array Parameters A procedure may be called with array parameters, c.f. SQLParamOptions. Each call can yield multiple result sets. The SQLMoreResults function is used to get from one result set to the next and from one procedure call to the next. One may have to call this function an indeterminate number of times before all results from a procedure with array parameters have been received. Each procedure return is marked with SQL_SUCCESS_WITH_INFO with SQL state 'PMORE'. The next SQLFetch will retrieve the first row of the first result set of the next procedure invocation. http://docs.openlinksw.com/virtuoso/EXCEPTIONS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Exception Semantics 2008-11-25T00:17:53Z Exception Semantics Exceptions are of two types: Not Found and SQLSTATE. A not found exception occurs when a select - into or open statement finds no row or when a fetch statement reads past the last row of a cursor. A SQLSTATE exception may result from any operation, typically a manipulative SQL statement. The SQLSTATE '4001', deadlock is an example of this. A user-written procedure may signal a user defined exception with the signal function. Virtuoso/PL supports PSM 96 style exception handlers. These allow catching specific SQL states or ranges of SQL states, invoking a specific block of code when the state is signalled from within the scope of the handler. The handler may propagate the exception to an outer handler or transfer control to any appropriate point in the containing procedure. An unhandled exception will cause the procedure where it is detected to return the exception to its caller. If the caller is another procedure that has a handler for the specified exception that procedure invokes the handler. If the caller is a call statement issued by a client, the client gets the SQLSTATE and the SQLExecute function called by the client returns SQL_ERROR and the client application may retrieve the SQLSTATE and message with the SQLError function. http://docs.openlinksw.com/virtuoso/PLREF.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Virtuoso/PL Syntax 2008-11-25T00:17:53Z Virtuoso/PL Syntax http://docs.openlinksw.com/virtuoso/EXECSQLPROCSELECT.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Execute Stored Procedures via SELECT statement 2008-11-25T00:17:53Z Execute Stored Procedures via SELECT statement Stored SQL Procedures can be executed via SELECT statement: For ex.: http://docs.openlinksw.com/virtuoso/EXECSQLPROCFORK.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Execute Stored Procedures In Background 2008-11-25T00:17:53Z Execute Stored Procedures In Background You can start procedure in background using the [name of the procedure][params]& syntax. This feature forks another ISQL process and leaves the other on background so there will be two separate clients running separate client connections: See Asynchronous Execution and Multithreading in Virtuoso/PL for background jobs execution details. http://docs.openlinksw.com/virtuoso/createassembly.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CREATE ASSEMBLY Syntax - External Libraries 2008-11-25T00:17:53Z CREATE ASSEMBLY Syntax - External Libraries External CLR libraries can be hosted inside Virtuoso by creating an assembly from the library itself using the syntax as follows: Every .NET assembly deployed inside Virtuoso will be verifiable, which means it will contain code the CLR can verify to be safe in the way it writes to memory. Virtuoso also respects the Common Language Runtime's code access security model. By default, code does not have any permissions to create a graphical user interface, create threads, access the file system, or call unmanaged code. The only permissions implemented are those granted for in-process data access. http://docs.openlinksw.com/virtuoso/createexthostproc.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CREATE PROCEDURE Syntax - External hosted procedures 2008-11-25T00:17:53Z CREATE PROCEDURE Syntax - External hosted procedures Virtuoso provides a syntax shortcut for calling static method from hosted user defined types without first defining a Virtuoso external hosted user defined type: This compiles into an functional equivalent of : For more details see CREATE TYPE and Runtime hosting chapters. http://docs.openlinksw.com/virtuoso/ASYNCEXECMULTITHREAD.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Asynchronous Execution and Multithreading in Virtuoso/PL 2008-11-25T00:17:53Z Asynchronous Execution and Multithreading in Virtuoso/PL Many application tasks benefit from parallel execution. This is specially true of I/O intensive workloads where each thread spends a large amount of time waiting for the network or disks. Typical tasks include crawling the web and importing large data sets. The whole process must not stop just because there is a file cache miss or because there is round trip latency or a name resolution delay on the net. To this effect, Virtuoso/PL provides the async_queue object. A stored procedure may create an async_queue that will be served by a pool of worker threads. The size of this pool can be set when creating the queue. The thread which made the queue can use the queue to pass procedure/parameter list pairs to the threads. If a thread is available, the thread will execute the request, if not, the next thread of the pool to become free will take the oldest queued item and execute it. Thus the queue is served in a FIFO fashion multiplexed over n threads. http://docs.openlinksw.com/virtuoso/PERFTIPS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Performance Tips 2008-11-25T00:17:53Z Performance Tips http://docs.openlinksw.com/virtuoso/PROCEDURES_TRANSACTIONS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Procedures and Transactions 2008-11-25T00:17:53Z Procedures and Transactions A procedure call executed by a client is just like any other SQL statement. It executes in the context of the client's active transaction. If the connection is in autocommit mode the transaction is automatically committed if the procedure returns successfully and rolled back if the procedure returns with an error. If the connection is in manual commit mode, a possible procedure error has no effect on the client's transaction, unless the error is a transaction error, e.g. timeout or deadlock. For best performance, we recommend using procedures in autocommit mode. In this way, a single client-server exchange will suffice to carry out the whole transaction. This will also conveniently roll back the transaction if the procedure exited as a result of an unhandled SQLSTATE or a 'not found' condition. Procedures can commit or rollback transactions using commit work and rollback work statements. http://docs.openlinksw.com/virtuoso/twopcimplementation.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Distributed Transaction & Two Phase Commit 2008-11-25T00:17:53Z Distributed Transaction & Two Phase Commit 2PC is an acronym for 2 Phase Commit. This is a protocol by which data being committed to a database is committed in two phases. In the first phase, the transaction processor checks that all parts of the transaction can be committed. In the second phase, all parts of the transaction are committed. If any part of the transaction indicates in the first phase that it cannot be committed, the second phase does not occur. ODBC does not support two-phase commits. Transactions in SQL databases are expected to have "ACID" features: Atomicity, Consistency, Isolation, Durability. A two-phase commit (2PC) protocol is needed for guaranteeing ACID properties of transactions which involve changing data in more than one database. This can be the case in a transaction involving tables attached from other databases or explicit access to remote databases with rexecute(). The 2PC protocol needs to have a third party Distributed Transaction Coordinator (DTC). Virtuoso supports Microsoft Transaction Server (or MS DTC). http://docs.openlinksw.com/virtuoso/TRIGGERS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Triggers 2008-11-25T00:17:53Z Triggers A trigger is a procedure body associated with a table and an event. A trigger can take effect before, after or instead of the event on the subject table. Several before, after or instead of triggers may exist for a given event on a given table, which can be fired in a specified order. Triggers are useful for enforcing integrity rules, maintaining the validity of data computed from other data, accumulating history data etc. A trigger body has no arguments in the sense a procedure does. A trigger body implicitly sees the columns of the subject table as read-only parameters. An update trigger may see both the new and old values of the row of the subject table. These are differentiated by correlation names in the REFERENCING clause. http://docs.openlinksw.com/virtuoso/charescaping.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Character Escaping 2008-11-25T00:17:53Z Character Escaping The C style escape character can be used to include special characters inside literals. The backslash character, '\', followed by an octal character code or a special character provides a notation for characters that are normally not typable in a string literal such as tab or crlf. Backslash support can be turned on or off at the statement level, the connection level or server default level. http://docs.openlinksw.com/virtuoso/PLSCROLLCRSRS.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Virtuoso/PL Scrollable Cursors 2008-11-25T00:17:53Z Virtuoso/PL Scrollable Cursors Virtuoso/PL supports scrollable cursors, providing functionality similar to the ODBC scrollable cursor support. Scrollable Cursor support extends the basic (forward-only) syntax of DECLARE CURSOR and FETCH to support the various fetch directions & cursor modes. The Virtuoso/PL scrollable cursors always operate with a rowset size equal to 1. The keyset size (where applicable) is as per the default. http://docs.openlinksw.com/virtuoso/plmodules.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Virtuoso PL Modules 2008-11-25T00:17:53Z Virtuoso PL Modules Modules are packages of procedures which compile together. Procedure names in module definitions are not fully qualified names, but consist only of a single identifier that it is appended to the name of the module (which is a 3-part name) to make the 4-part module procedure name. Module procedures do not appear in SQLProcedures output. Module names are in the same domain as the procedure names, so it is not possible to have a procedure with the same name as an existing module. A single part procedure name in a call inside a module is first matched against procedures defined in the module. If the above example were executed by DBA (in the DB qualifier), then the below statements are equivalent: http://docs.openlinksw.com/virtuoso/handlingplcondit.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Handling Conditions In Virtuoso/PL Procedures 2008-11-25T00:17:53Z Handling Conditions In Virtuoso/PL Procedures Condition handlers determine the behavior of a Virtuoso/PL procedure when a condition occurs. You can declare one or more condition handlers in your Virtuoso/PL procedure for general SQL conditions or specific SQLSTATE values. If a statement in your procedure raises an SQLEXCEPTION condition and you declared a handler for the specific SQLSTATE or SQLEXCEPTION condition the server passes control to that handler. If a statement in your Virtuoso/PL procedure raises an SQLEXCEPTION condition, and you have not declared a handler for the specific SQLSTATE or the SQLEXCEPTION condition, the server passes the exception to the calling procedure (if any). If the procedure call is at the top-level, then the exception is signalled to the calling client. http://docs.openlinksw.com/virtuoso/pldebugger.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Procedure Language Debugger 2008-11-25T00:17:53Z Procedure Language Debugger Virtuoso has step by step PL debugging capabilities and a call stack trace option. When Virtuoso is running with a console or with stdout going somewhere like a file you can print debug messages directly to that using dbg_printf() and dbg_obj_print() functions. Procedure source code can be written to an ASCII file using any text/programming editor. This file can be loaded into ISQL using the load command or directly from the command line using the ISQL batch mode: ISQL can then be used to test the procedures functionality. Procedures can return result sets to ISQL for data debugging purposes too. When dealing with results sets in ISQL remember to call procedures using the CALL keyword to ensure that ISQL outputs all result sets: http://docs.openlinksw.com/virtuoso/rowlevelsecurity.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Row Level Security 2008-11-25T00:17:53Z Row Level Security Organizations often need to compartmentalize access to data. This may be implemented at the level of physically segregating systems, building specific application logic or within the database. Physically disconnected systems can be troublesome in an increasingly integrated corporate IS environment. Building access rules into application logic, typically in a middle tier is possible and flexible but the protection runs the risk of being circumvented by direct access to the database, through business intelligence tools for example. For these reasons some database level security enforcement is needed in most applications. SQL provides table and column level privileges which can be granted to users and roles. These do not address issues where one department's data should be accessible when another department's data should not. Such segregation within a table is usually done with views which hard-code selection criteria. The table itself will not be granted but views to specific ranges of rows will be granted to users.