<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="Function: DAV lock manipulation functions - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: DAV lock manipulation functions - Virtuoso Functions Guide" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="functions.html" title="Chapter Contents" />
<link rel="prev" href="appendixa.html" title="Appendix" />
<link rel="next" href="functions.html#.html" title="" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>Function: DAV lock manipulation functions - Virtuoso Functions Guide</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="fn_dav_api_lock" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - DAV lock manipulation functions</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="fn_dav_api_change.html" title="DAV manipulation functions">Prev</a> | <a class="link" href="fn_dav_api_search.html" title="DAV search functions">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div>
<a class="selected" href="functions.html">Virtuoso Functions Guide</a>
</div>
<br />
<div>
<a href="functions.html#admin">Administration</a>
</div>
<div>
<a href="functions.html#aggr">Aggregate Functions</a>
</div>
<div>
<a href="functions.html#array">Array Manipulation</a>
</div>
<div>
<a href="functions.html#bpel">BPEL APIs</a>
</div>
<div>
<a href="functions.html#backup">Backup</a>
</div>
<div>
<a href="functions.html#compression">Compression</a>
</div>
<div>
<a href="functions.html#cursors">Cursor</a>
</div>
<div>
<a href="functions.html#time">Date & Time Manipulation</a>
</div>
<div>
<a href="functions.html#debug">Debug</a>
</div>
<div>
<a href="functions.html#dict">Dictionary Manipulation</a>
</div>
<div>
<a href="functions.html#encoding">Encoding & Decoding</a>
</div>
<div>
<a href="functions.html#file">File Manipulation</a>
</div>
<div>
<a href="functions.html#ft">Free Text</a>
</div>
<div>
<a href="functions.html#hash">Hashing / Cryptographic</a>
</div>
<div>
<a href="functions.html#ldap">LDAP</a>
</div>
<div>
<a href="functions.html#localization">Locale</a>
</div>
<div>
<a href="functions.html#mail">Mail</a>
</div>
<div>
<a href="functions.html#misc">Miscellaneous</a>
</div>
<div>
<a href="functions.html#number">Number</a>
</div>
<div>
<a href="functions.html#phrz">Phrases</a>
</div>
<div>
<a href="functions.html#rdf">RDF data</a>
</div>
<div>
<a href="functions.html#rmt">Remote SQL Data Source</a>
</div>
<div>
<a href="functions.html#repl">Replication</a>
</div>
<div>
<a href="functions.html#soap">SOAP</a>
</div>
<div>
<a href="functions.html#sql">SQL</a>
</div>
<div>
<a href="functions.html#string">String</a>
</div>
<div>
<a href="functions.html#txn">Transaction</a>
</div>
<div>
<a href="functions.html#type">Type Mapping</a>
</div>
<div>
<a href="functions.html#uddi">UDDI</a>
</div>
<div>
<a href="functions.html#udt">User Defined Types & The CLR</a>
</div>
<div>
<a href="functions.html#vad">VAD</a>
</div>
<div>
<a href="functions.html#jvmpl">Virtuoso Java PL API</a>
</div>
<div>
<a href="functions.html#bif">Virtuoso Server Extension Interface (VSEI)</a>
</div>
<div>
<a class="selected" href="functions.html#ws">Web & Internet</a>
</div>
<div class="selected">
<div>
<a href="fn_dav_api_add.html">dav add & update fun...</a>
</div>
<div>
<a class="selected" href="fn_dav_api_lock.html">dav lock manipulatio...</a>
</div>
<div>
<a href="fn_dav_api_change.html">dav manipulation fun...</a>
</div>
<div>
<a href="fn_dav_api_search.html">dav search functions</a>
</div>
<div>
<a href="fn_dav_exp.html">dav_exp</a>
</div>
<div>
<a href="fn_lfs_exp.html">lfs_exp</a>
</div>
<div>
<a href="fn_serv_queue_top.html">serv_queue_top</a>
</div>
<div>
<a href="fn_urlrewrite_create_regex_rule.html">urlrewrite_create_re...</a>
</div>
<div>
<a href="fn_USER_KEY_LOAD.html">user_key_load</a>
</div>
<div>
<a href="fn_vhost_define.html">vhost_define</a>
</div>
<div>
<a href="fn_vhost_remove.html">vhost_remove</a>
</div>
<div>
<a href="fn_dav_api_user.html">webdav users & group...</a>
</div>
<div>
<a href="fn_client_attr.html">client_attr</a>
</div>
<div>
<a href="fn_connection_get.html">connection_get</a>
</div>
<div>
<a href="fn_connection_id.html">connection_id</a>
</div>
<div>
<a href="fn_connection_is_dirty.html">connection_is_dirty</a>
</div>
<div>
<a href="fn_connection_set.html">connection_set</a>
</div>
<div>
<a href="fn_connection_vars.html">connection_vars</a>
</div>
<div>
<a href="fn_connection_vars_set.html">connection_vars_set</a>
</div>
<div>
<a href="fn_dbname.html">dbname</a>
</div>
<div>
<a href="fn_ftp_get.html">ftp_get</a>
</div>
<div>
<a href="fn_ftp_ls.html">ftp_ls</a>
</div>
<div>
<a href="fn_ftp_put.html">ftp_put</a>
</div>
<div>
<a href="fn_get_certificate_info.html">get_certificate_info</a>
</div>
<div>
<a href="fn_get_keyword.html">get_keyword</a>
</div>
<div>
<a href="fn_get_keyword_ucase.html">get_keyword_ucase</a>
</div>
<div>
<a href="fn_http.html">http</a>
</div>
<div>
<a href="fn_http_acl_get.html">http_acl_get</a>
</div>
<div>
<a href="fn_http_acl_remove.html">http_acl_remove</a>
</div>
<div>
<a href="fn_http_acl_set.html">http_acl_set</a>
</div>
<div>
<a href="fn_http_body_read.html">http_body_read</a>
</div>
<div>
<a href="fn_http_client.html">http_client</a>
</div>
<div>
<a href="fn_http_client_ext.html">http_client_ext</a>
</div>
<div>
<a href="fn_http_client_ip.html">http_client_ip</a>
</div>
<div>
<a href="fn_http_debug_log.html">http_debug_log</a>
</div>
<div>
<a href="fn_http_enable_gz.html">http_enable_gz</a>
</div>
<div>
<a href="fn_http_file.html">http_file</a>
</div>
<div>
<a href="fn_http_flush.html">http_flush</a>
</div>
<div>
<a href="fn_http_get.html">http_get</a>
</div>
<div>
<a href="fn_http_header.html">http_header</a>
</div>
<div>
<a href="fn_http_header_get.html">http_header_get</a>
</div>
<div>
<a href="fn_http_kill.html">http_kill</a>
</div>
<div>
<a href="fn_http_listen_host.html">http_listen_host</a>
</div>
<div>
<a href="fn_http_lock.html">http_lock</a>
</div>
<div>
<a href="fn_http_map_get.html">http_map_get</a>
</div>
<div>
<a href="fn_http_map_table.html">http_map_table</a>
</div>
<div>
<a href="fn_http_param.html">http_param</a>
</div>
<div>
<a href="fn_http_path.html">http_path</a>
</div>
<div>
<a href="fn_http_pending_req.html">http_pending_req</a>
</div>
<div>
<a href="fn_http_physical_path.html">http_physical_path</a>
</div>
<div>
<a href="fn_http_proxy.html">http_proxy</a>
</div>
<div>
<a href="fn_http_request_get.html">http_request_get</a>
</div>
<div>
<a href="fn_http_request_header.html">http_request_header</a>
</div>
<div>
<a href="fn_http_request_status.html">http_request_status</a>
</div>
<div>
<a href="fn_http_rewrite.html">http_rewrite</a>
</div>
<div>
<a href="fn_http_root.html">http_root</a>
</div>
<div>
<a href="fn_http_unlock.html">http_unlock</a>
</div>
<div>
<a href="fn_http_url.html">http_url</a>
</div>
<div>
<a href="fn_http_value.html">http_value</a>
</div>
<div>
<a href="fn_http_xslt.html">http_xslt</a>
</div>
<div>
<a href="fn_json_parse.html">json_parse</a>
</div>
<div>
<a href="fn_ses_connect.html">ses_connect</a>
</div>
<div>
<a href="fn_ses_disconnect.html">ses_disconnect</a>
</div>
<div>
<a href="fn_ses_read_line.html">ses_read_line</a>
</div>
<div>
<a href="fn_ses_write.html">ses_write</a>
</div>
<div>
<a href="fn_tcpip_gethostbyaddr.html">tcpip_gethostbyaddr</a>
</div>
<div>
<a href="fn_tcpip_gethostbyname.html">tcpip_gethostbyname</a>
</div>
<div>
<a href="fn_vsp_calculate_digest.html">vsp_calculate_digest</a>
</div>
<div>
<a href="fn_wsdl_import_udt.html">wsdl_import_udt</a>
</div>
</div>
<div>
<a href="functions.html#xml">XML</a>
</div>
<div>
<a href="functions.html#XPATH">XPATH & XQUERY</a>
</div>
<br />
<div>
<a href="functionidx.html">Functions Index</a>
</div>
<br />
</div>
<div id="text">
<h2>DAV lock manipulation functions</h2>
<div class="refpurpose">Operations on locks of DAV collections and resources</div>
<div class="funcsynopsis">
<span class="funcdef">integer <span class="function">DAV_IS_LOCKED</span>
</span>
(<span class="paramdef">in <span class="parameter">id</span> any</span>,
<span class="paramdef">in <span class="parameter">type</span> char(1)</span>,
<span class="paramdef">in <span class="parameter">owned_tokens</span> any := 1</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">integer <span class="function">DAV_LIST_LOCKS</span>
</span>
(<span class="paramdef">in <span class="parameter">id</span> any</span>,
<span class="paramdef">in <span class="parameter">type</span> char(1)</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">integer <span class="function">DAV_LOCK</span>
</span>
(<span class="paramdef">in <span class="parameter">path</span> varchar</span>,
<span class="paramdef">in <span class="parameter">locktype</span> varchar</span>,
<span class="paramdef">in <span class="parameter">scope</span> varchar</span>,
<span class="paramdef">in <span class="parameter">token</span> varchar</span>,
<span class="paramdef">in <span class="parameter">owner_name</span> varchar</span>,
<span class="paramdef">in <span class="parameter">owned_tokens</span> varchar</span>,
<span class="paramdef">in <span class="parameter">depth</span> varchar</span>,
<span class="paramdef">in <span class="parameter">timeout_sec</span> integer</span>,
<span class="paramdef">in <span class="parameter">auth_uname</span> varchar</span>,
<span class="paramdef">in <span class="parameter">auth_pwd</span> varchar</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">any <span class="function">DAV_UNLOCK</span>
</span>
(<span class="paramdef">in <span class="parameter">path</span> varchar</span>,
<span class="paramdef">in <span class="parameter">token</span> varchar</span>,
<span class="paramdef">in <span class="parameter">auth_uname</span> varchar</span>,
<span class="paramdef">in <span class="parameter">auth_pwd</span> varchar</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>
<span class="computeroutput">DAV_LOCK</span> sets a new lock or refresh an existing lock or creates a lock object.</p>
<p>
<span class="computeroutput">DAV_UNLOCK</span> releases a lock.</p>
<p>
<span class="computeroutput">DAV_IS_LOCKED</span> reports whether the resource or collection is locked.</p>
<p>
<span class="computeroutput">DAV_LIST_LOCKS</span> returns a full list of all locks on a resource or collection.</p>
<p>It is strongly recommended to carefully study DAV standards before using these functions in applications.
Improper use of DAV locks may result in subtle application errors that are hard to debug.</p>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">path – </span>
Resource or collection path.
As usual, collection names must end with '/' and both sorts of path strings should begin with '/'.
If the path specifies a non-existing resource in an existing collection then a lock object is created and only lock owner can create a resource with this name in future.
</div>
<div class="refsect2">
<span class="refsect2title">locktype – </span>
The type of lock. Current set of DAV standards specifies only one type of locks, called 'D:write'; the parameter value is stored 'as is' and never used, so the recommended value is an empty string.
</div>
<div class="refsect2">
<span class="refsect2title">scope – </span>
The scope of lock as a single-char string: 'S' for shared lock, 'X' for exclusive.
</div>
<div class="refsect2">
<span class="refsect2title">token – </span>
The token to update. Empty string or NULL means creation of a new lock, not an update of the existing one.
</div>
<div class="refsect2">
<span class="refsect2title">owner_name – </span>
Lock owner name as it will be displayed to other users that will query for existing locks. It is strongly recommended to provide commonly used names such as e-mails to let users ask each other to remove forgotten locks.
</div>
<div class="refsect2">
<span class="refsect2title">owned_tokens – </span>
String of tokens owned by a user, to let user ignore his own tokens. The string should match syntax of DAV HTTP 'If' parameter.
This can be also an integer, this will work as empty list of tokens.
</div>
<div class="refsect2">
<span class="refsect2title">depth – </span>
This specifies the recursive depth of the lock.
The string can be '0' to lock the specified collection only, '1' to lock the collection and its subcollections, 'infinity' to lock the whole subtree.
When the lock is added to a resource, the value '0' is used, for obvious reason.
If NULL is passed to the function then the effective value is 'infinity' for collection lock or '0' for resource lock.
</div>
<div class="refsect2">
<span class="refsect2title">timeout_sec – </span>
Expiration interval for the lock, in seconds. If 0 or NULL is passed then HTTP DAV default is used that is equal to 604800 seconds (one week).
</div>
<div class="refsect2">
<span class="refsect2title">auth_uname – </span>
DAV user name to authenticate access. Lock, Lock refresh and unlock operations on existing resource or collection require write permission.
To create a lock object in a collection, user should have write permission on that collection.
This may cause problem when user first locks a resource and then loose write permission for some reason: the user is unable to remove his own lock.
Default is NULL that means public access.
</div>
<div class="refsect2">
<span class="refsect2title">auth_pwd – </span>
User password. Default is NULL.
</div>
<div class="refsect2">
<span class="refsect2title">id – </span>
Internal identifier of a resource or collection as returned by DAV_SEARCH_ID().
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Examples</div>
<a name="ex_dav_api_lock_1" />
<div class="example">
<div class="exampletitle">Two concurrent users</div>
<p>The following example shows how two users can prevent each other from undesired operations.</p>
<p>The sample function DAV_LOCK_DEMO() uses a function DUMP_VEC() that print the content of vector in Virtuoso/PL syntax.
Yon can find the implementation of this function as one of examples for <a href="fn_vector.html">vector()</a> Virtuoso/PL function.</p>
<div>
<pre class="screen">
create procedure DAV_LOCK_DEMO (in dav_passwd varchar := 'dav')
{
declare ACTION, RETVAL, token_s1, token_s2, token_x varchar;
result_names (ACTION, RETVAL);
result ('Adding group lock_demo_grp:',
DAV_ADD_GROUP ('lock_demo_grp', 'dav', dav_passwd) );
result ('Adding user lock_u1:',
DAV_ADD_USER ('lock_u1', 'lock_u1_pwd', 'lock_demo_grp', '110110000T', 0, '/DAV/lock_demo_u1_home/', 'First User of lock demo', 'lock_u1@localhost', 'dav', dav_passwd) );
result ('Adding user lock_u2:',
DAV_ADD_USER ('lock_u2', 'lock_u2_pwd', 'lock_demo_grp', '110110000T', 0, '/DAV/lock_demo_u2_home/', 'Second User of lock demo', 'lock_u2@localhost', 'dav', dav_passwd) );
result ('Adding a collection:',
DAV_COL_CREATE ('/DAV/lock_demo/', '110110000R', 'lock_u1', 'lock_demo_grp', 'dav', dav_passwd) );
result ('Uploading /DAV/lock_demo/sample.htm:',
DAV_RES_UPLOAD ('/DAV/lock_demo/sample.htm', '<html><body>This is /DAV/lock_demo/sample.htm</body></html>', 'text/plain', '110110000R', 'lock_u1', 'lock_demo_grp', 'lock_u1', 'lock_u1_pwd') );
token_s1 := DAV_LOCK ('/DAV/lock_demo/sample.htm', '', 'S', NULL, 'user1@example.com', '', '0', NULL, 'lock_u1', 'lock_u1_pwd');
result ('First user set a shared lock:', token_s1);
token_s2 := DAV_LOCK ('/DAV/lock_demo/sample.htm', '', 'S', NULL, 'user2@example.com', '', '0', NULL, 'lock_u2', 'lock_u2_pwd');
result ('Second user set a shared lock:', token_s2);
token_x := DAV_LOCK ('/DAV/lock_demo/sample.htm', '', 'X', NULL, 'user1@example.com', token_s1, '0', NULL, 'lock_u1', 'lock_u1_pwd');
result ('Lock dump',
DUMP_VEC (DAV_LIST_LOCKS (DAV_SEARCH_ID ('/DAV/lock_demo/sample.htm', 'R'), 'R')) );
result ('First user tries to set an exclusive lock:', token_x);
result ('Second user releases his lock:',
DAV_UNLOCK ('/DAV/lock_demo/sample.htm', token_s2, 'lock_u2', 'lock_u2_pwd') );
token_x := DAV_LOCK ('/DAV/lock_demo/sample.htm', '', 'X', NULL, 'user1@example.com', token_s1, '0', NULL, 'lock_u1', 'lock_u1_pwd');
result ('First user sets an exclusive lock:', token_x);
result ('First user releases his lock:',
DAV_UNLOCK ('/DAV/lock_demo/sample.htm', token_s1, 'lock_u1', 'lock_u1_pwd') );
token_x := DAV_LOCK ('/DAV/lock_demo/sample.htm', '', 'X', NULL, 'user1@example.com', token_s1, '0', NULL, 'lock_u1', 'lock_u1_pwd');
result ('First user sets an exclusive lock:', token_x);
result ('Second user tries to add a property to the resource:',
DAV_PROP_SET ('/DAV/lock_demo/sample.htm', 'sample_prop', 'sample value', 'lock_u2', 'lock_u2_pwd') );
result ('First user releases his shared:',
DAV_UNLOCK ('/DAV/lock_demo/sample.htm', token_x, 'lock_u1', 'lock_u1_pwd') );
result ('Second user adds a property to the resource:',
DAV_PROP_SET ('/DAV/lock_demo/sample.htm', 'sample_prop', 'sample value', 'lock_u2', 'lock_u2_pwd') );
}
DAV_LOCK_DEMO ();
ACTION RETVAL
VARCHAR VARCHAR
_______________________________________________________________________________
Adding group lock_demo_grp: 107
Adding user lock_u1: 108
Adding user lock_u2: 109
Adding a collection: 171
Uploading /DAV/lock_demo/sample.htm: 1103
First user set a shared lock: 1545ce54-3599-11da-8697-8f3efbd86ef2
Second user set a shared lock: 15460590-3599-11da-8697-8f3efbd86ef2
Lock dump
vector (
vector ('', 'S', '1545ce54-3599-11da-8697-8f3efbd86ef2', 604800, 108, 'user1@example.com'),
vector ('', 'S', '15460590-3599-11da-8697-8f3efbd86ef2', 604800, 109, 'user2@example.com'))
First user tries to set an exclusive lock: -8
Second user releases his lock: 15460590-3599-11da-8697-8f3efbd86ef2
First user sets an exclusive lock: -8
First user releases his lock: 1545ce54-3599-11da-8697-8f3efbd86ef2
First user sets an exclusive lock: 1547251a-3599-11da-8697-8f3efbd86ef2
Second user tries to add a property to the resource: -8
First user releases his shared: 1547251a-3599-11da-8697-8f3efbd86ef2
Second user adds a property to the resource: 1321
</pre>
</div>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="fn_dav_api_add.html">DAV content add/update/delete functions</a>
</p>
<p>
<a href="fn_dav_api_change.html">DAV content manipulation functions</a>
</p>
<p>
<a href="fn_dav_api_search.html">DAV search functions</a>
</p>
<p>
<a href="fn_dav_api_user.html">DAV user management functions</a>
</p>
</div>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
227
