Using DELETETABLE_SUB (Functions/Subroutines/Programs)

DELETETABLE_SUB

DELETETABLE_SUB( tableName, options )

Using DELETETABLE_SUB

Removes a table permanently from Advanced Revelation, including the related index file (!file). You have the option to remove the dictionary and data portion of a table together, or to delete only the one or the other.

tableName

The name of the table to delete. The table must be attached. By default, DELETETABLE_SUB deletes the dictionary, the data portion, and the index (!file) for the table. To delete only the dictionary, use the prefix "DICT." on the tableName. To delete only the data portion (and the index), use the prefix "DATA."

You cannot use DELETETABLE_SUB to delete any of these tables:

DICT.VOC	SYSPOPUPS	SYSWINDOWS
SYSMENUS	SYSTABLES	VOC
SYSMESSAGES	SYSTEXT
SYSOBJ	SYSVOLUMES

options

Option	Meaning
L	(Lock) Locks the table before deleting it.

Values returned

The return status of DELETETABLE_SUB is indicated by the system variables @file.error. The error number appears in field 1 of each @file.error "record", and additional information about the error appears in field 2. Multiple errors are delimited with record marks (@RM). Possible errors are:

Error	Meaning	Add'l Info.
S140	Process not allowed on a Runtime version of Advanced Revelation.
S141	No table name provided.	<2,1> DELETETABLE_SUB <2,2> 1 (for argument 1 )
W523	Unable to delete the table.	<2,1> table name <2,2> volume
W113	Unable to delete the table.	<2> table*application
W351	The table is not attached.	<2> table
R123	Cannot delete a system table.	<2,1> table name <2,2> volume
B205	The table is locked.	<2> table name

Additional information is available in the system variable status( ). Possible values are:

status( )	Meaning
null	Successful deletion.
-2	Informational error (for example, dictionary could not be found).
0 or 1	An error occurred.

If you have passed the name of the data table only in tableName (that is, you did not use the prefix "DICT."), and if the dictionary cannot be deleted, DELETETABLE_SUB does not consider this to be an error and returns -2 in status( ).

Notes

Locking

If you are on a network when you delete a table, other users who might be using the table at the same time will experience an error. To avoid this problem, you should attempt to lock the table before deleting it by using the L option.

However, the L option is only effective of all users are using coordinated locking (table lock first, followed by row lock). If other users are not using a coordinated lock and are therefore locking only rows and not the table itself, DELETETABLE_SUB will delete the table without warning. For more information about coordinated locking, see "Types of Locking " in Chapter 30 of the Advanced Revelation User's Guide.

Correct use of DELETETABLE_SUB

equ null$ to ""

equ informational$ to -2

table = "TESTMIKE"

option = "L"

call deletetable_sub( table, option )

if status() ne null$ then

if status() eq informational$ then

/* no problem – just couldn't find the dictionary */

end else

call fsmsg()

end