ServerSandboxesDelete

Description

This function uses a "predicate" to describe the sandbox being deleted. A predicate can be read as: "Delete sandboxes whose attribute is condition value."

For example: Delete sandboxes whose size is greater than 10 MB. In this example, the attribute is the "size" of the sandbox, the condition is "greater than", and the value is "10 MB".

There are two optional delimiter character parameters to the TurboIntegrator function. Because a sandbox has no restrictions on which characters can be used in their name, administrators can supply their own "safe" delimiter when needed.

For example, ServerSandboxesDelete( 'client:=:Admin, name:=:best case scenario' );"

In the following example, the colon character is used in the sandbox name ("best::case::scenario") so another delimiter is needed:

ServerSandboxesDelete( 'client|=|Admin# name|=|best::case::scenario', '|', '#' );"

Filter Attributes

Filter attributes are properties of a sandbox on which it can be conditionally matched. Attribute names and their corresponding valid conditions are case insensitive and ignore embedded whitespace. For example, the following two calls are both valid:

ServerSandboxesDelete( 'client:=:Admin' );

ServerSandboxesDelete( 'C L I E N T : = :Admin' );

Logging and Returns

Sandbox deletion is logged using the preexisting audit logging functionality. Additionally, a more detailed report of the effects of sandbox administration is included in the debug log (tm1server.log) at INFO level. This report will include the list of affected sandboxes, as well as some of their attributes, and any errors encountered.

ServerSandboxesDelete returns only a success or failure status.

Semantics

Predicate List

Multiple predicates passed in a single call to ServerSandboxesDelete are conjunctive. In other words, for a sandbox to match the passed criteria, all predicates must be true. Multiple calls to ServerSandboxesDelete can be used to achieve disjunctive behavior. Only one occurrence of each attribute is allowed per call to ServerSandboxesDelete. For example, passing client twice is invalid as a sandbox has only one owning client. When multiple occurrences of an attribute are detected, a warning displays in the detailed report, however, the operation will not abort in failure. In such a case, the predicates are tested as with any other query, but the results set is always empty.

Locking

To avoid massive locking issues, ServerSandboxesDelete looks at the sandboxes of a client as a point-in-time snapshot and then, when possible, release any locks that would ensure a serializable transaction. Because of this behavior, once a client is "passed" in the iteration of all clients, a sandbox matching the filter criteria may be added to that client before the maintenance transaction completes. This behavior is similar to the behavior that occurs when a sandbox is added to the client immediately after the transaction completes.

Scope

Members of the ADMIN (super-user) and the DataAdmin groups will have access to all sandboxes of all clients. They must explicitly specify the client attribute to limit the scope of their call to ServerSandboxesDelete to only their own sandboxes. All other users have access to only their own sandboxes; if they specify a different client, or a group to which they do not belong, the function will abort in failure and return a privilege error.

In-Use Sandboxes

When a sandbox meets the criteria for deletion, but is currently in use, that sandbox will not be deleted. An entry will appear in the debug log info-level report indicating the occurrence.

Access and Update Dates

Date attributes can be matches with, at most, day granularity. Because of this restriction, recording of these attributes is correspondingly granular. Last Update Date is not updated on individual cell writes. Instead, the system records the unload date of a sandbox that has had something written to it while it was loaded in memory. For such sandboxes, Last Access Date and Last Update Date will be the same. Only Last Access Date is updated on the unloading of a sandbox from memory. Also, because in-memory sandboxes are not subject to ServerSandboxesDelete, Last Access Date is not updated when a sandbox is loaded into memory.

For example, consider the follow usage scenario:

Table 2. Last Access Day Example

Day	Time	Action
1	1	Load Sandbox S
1	2	Write 1
2	3	Read 1
2	4	Unload Sandbox

A user is working with sandbox over the course of two days (perhaps for a much shorter period encompassing the day change.) At time 4, when the sandbox is unloaded, Last Update Date is set to 2, rather than 1 where the last update actually occurred. Last Access Date is also set to 2 at time 4 in this case. If Write1 were instead a read, only Last Access Date would be set to 2, while Last Update Date wouldn't be changed.