'revdb, restricted under current license' - causes and solutions

[Eric Peden]

Fellow Revvers,

How many times have you seen the dreaded "revdb, restricted under 
current license" message? Too many, if your projects are anything like 
mine. I've compiled a bit of information on this error message as well 
as some workarounds; hopefully this information will prove useful to 
some of you.

First, the cause: this error seems to be triggered when more than one 
database connection or cursor is opened. The documentation states that 
only one connection is allowed for non-Professional licenses and that 
Pro licenses can have unlimited connections; however, my preliminary 
testing suggests that this error occurs under Pro licenses, as well.

So, how can it be avoided? Make sure that you always store the results 
of a revdb_open(), revdb_query(), or revdb_queryblob() request; these 
results are connection/cursor IDs that, even if the results they point 
to are empty, must be closed before another connection/cursor is 
opened. As soon as you're finished with the connection/cursor, call the 
corresponding close function: revdb_close() and revdb_closecursor(), 
respectively.

Unfortunately, during testing, the restricted error is all too likely 
to crop up, even if you follow the recommendations above. Any errors 
that occur before the connection/cursor can be closed will leave them 
"dangling," causing the restricted error when the script is run again. 
A common method for dealing with this is to quit Revolution and re-open 
it; this works, but is time-consuming. In place of this, the dangling 
items can be closed by hand with the following procedure:

1. Open the Message box.
2. Execute 'revdb_connections()'
3. For each integer returned (there should be only 1; if there's more 
than that, you shouldn't be seeing a restricted error), execute 
'revdb_close(connectionID)'. This closes the dangling connection and 
any cursors open under it.

One could also close just the dangling cursor(s) without touching the 
connection(s) by using the corresponding cursor commands in the above 
procedure.

With careful programming, errors of this kind can be eliminated in 
distribution stacks by making certain that connection/cursor calls are 
balanced. I've found that this is made easier by creating a robust 
'open' function that only opens a connection if there isn't one open 
already, and then calling this function before each database access. 
Cursors, on the other hand, should be as limited in scope as possible. 
In virtually all cases, a cursor can (and should!) be closed in the 
same function that opened it; just make sure to never ignore the return 
value of a revdb_query*().

Hopefully some of you will find this information helpful; if you've 
anything to add or any corrections to make, I look forward to hearing 
from you.

-- eric