Skip to main content
************* PRERELEASE CONTENT *************
Previous sectionNext section

$SORTBEGIN

Initiates a sorting mode to improve performance of multiple sets to a global.

Synopsis

$SORTBEGIN(set_global)

Parameter

Argument Description
set_global A global variable name.

Description

$SORTBEGIN initiates a special sorting mode during which SET operations to the specified target global are redirected to a process-private temporary area and sorted into subsets. This mode is ended with a call to $SORTEND which copies the data into the target global reference. When the special sorting mode is in effect, all sets to the target global reference and any of its descendants are affected.

$SORTBEGIN is designed to help the performance of operations, such as index building, where a large amount of unordered data needs to be written to a global. When the amount of data written approaches or exceeds the amount of available buffer pool memory, performance can suffer drastically. $SORTBEGIN solves this problem by guaranteeing that data is written to the target global in sequential order, thus minimizing the number of physical disk accesses needed. It does this by writing and sorting data into one or more temporary buffers (using space in the IRISTEMP database if needed) and then, when $SORTEND is called, copying the data sequentially into the target global.

While $SORTBEGIN is in effect, data read from the target global will not reflect any SET operations. You cannot use $SORTBEGIN in cases where you need to read global values from the same global in which you are inserting values.

InterSystems IRIS object and InterSystems SQL applications automatically make use of $SORTBEGIN for index and temporary index creation.

The $SORTBEGIN sorting mode can be terminated without writing data to the target global by calling $SORTEND with it optional second parameter set to 0.

If successful, $SORTBEGIN returns a nonzero integer value. If unsuccessful, $SORTBEGIN returns zero.

Sorting Mode Errors

Invoking some operations between the $SORTBEGIN and $SORTEND result in InterSystems IRIS issuing an error code:

  • If the mapping of the namespace of set_global is changed between $SORTBEGIN and $SORTEND, a <NAMESPACE> error occurs when you invoke $SORTEND. However, if $SORTBEGIN specifies set_global with an implied namespaces, subsequent namespace mapping changes have no effect on $SORTEND. Global references with implied namespace and global references with explicit namespaces should not be mixed in the same sort operation. For information on modifying namespaces, see Configuring Namespaces in the System Administration Guide.

  • If you establish a $SORTBEGIN global, and then issue a $SORTBEGIN for an ancestor or descendent of that global, InterSystems IRIS issues a <DUPLICATEARG> error. For example, if you invoke $SORTBEGIN(^test(1,2,3)), the following function calls result in a <DUPLICATEARG> error: $SORTBEGIN(^test(1,2)) or $SORTBEGIN(^test(1,2,3,4)).

See Also