|
Process Help |
|
Process Name |
Menu Path |
Link to Command Table |
|
MGSORT |
Data ribbon | Data Tools | Sort |
Introduction
Sorts any file into ascending (or optionally descending) order of keyfields.
Ascending order is the default; descending order is specified by setting the optional parameter @ORDER=2.
At least one keyfield must be specified and must appear as an explicit field. For alphanumeric fields, the collating sequence is the standard Datamine-specific sort sequence for text. The fields are sorted in the order in which they are specified. If a specified keyfield is not in the file, it is ignored. A warning message is given if @PRINT>=1.
From Studio MR22 Update 1 onwards, SORTX and MGSORT become identical, although separate process names were retained for legacy purposes. The new implementation provides significant performance benefits over earlier versions.
Where sufficient memory exists, the table is sorted entirely within memory. However, if the memory required exceeds that available, the table is sorted in separate 'chunks', each temporarily stored to disk and then merged together for the final write. The maximum number of records that can be sorted is therefore limited only by available disk space.
This process includes the KEYSFRST option which, by default, maintains legacy behavior by reordering key fields in the output file so that KEY1 becomes the first field, KEY2 the second field, and so on. If you specify that key fields are not reordered, then the order of fields in the OUT and IN file will be identical.
This process allows you to determine how the sort is performed with regards to duplicate key field values, using the ROWORDER parameter.
|
Although the order of fields in a file does not affect subsequent processing, it makes it more difficult to review the file using Datamine's Table Editor: for example, a borehole file which is sorted by BHID, FROM and TO is more difficult to manually validate if these fields are not adjacent. |
Files, Fields and Parameters
Input Files
|
Name |
Description |
I/O Status |
Required |
Type |
|
IN |
File to be sorted. |
Input |
Yes |
Table |
Output Files
|
Name |
I/O Status |
Required |
Type |
Description |
|
OUT |
Output |
Yes |
Table |
Sorted file. |
Fields
|
Name |
Description |
Source |
Required |
Type |
Default |
|
KEY1 |
Keyfield 1 for sorting on. |
IN |
Yes |
Any |
Undefined |
|
KEY2 |
Keyfield 2. |
IN |
No |
Any |
Undefined |
|
KEY3 |
Keyfield 3. |
IN |
No |
Any |
Undefined |
|
KEY4 |
Keyfield 4. |
IN |
No |
Any |
Undefined |
|
KEY5 |
Keyfield 5. |
IN |
No |
Any |
Undefined |
|
KEY6 |
Keyfield 6. |
IN |
No |
Any |
Undefined |
|
KEY7 |
Keyfield 7. |
IN |
No |
Any |
Undefined |
|
KEY8 |
Keyfield 8. |
IN |
No |
Any |
Undefined |
|
KEY9 |
Keyfield 9. |
IN |
No |
Any |
Undefined |
|
KEY10 |
Keyfield 10. |
IN |
No |
Any |
Undefined |
Parameters
|
Name |
Description |
Required |
Default |
Range |
Values |
||||||
|
ORDER |
|
No |
1 |
1,2 |
1,2 | ||||||
|
KEYSFRST |
|
No |
1 |
0,1 |
0,1 |
||||||
|
ROWORDER |
|
No |
1 |
0,1 |
0,1 |
||||||
|
KEYTOL |
KEYTOL is the tolerance value used to test whether numeric key values are equal. It must be greater than or equal to zero. It replaces the previous heuristic comparison method. If KEYTOL is set to a negative value then zero is used. In a macro KEYTOL can be set to absent using -. "@KEYTOL=-" This will revert to legacy behaviour and use a heuristic comparison in relational commands and zero in sort. |
No |
0.00001 |
0,+ |
Undefined |
Notes
The SORTX and MGSORT processes honor the standard Datamine-specific sort sequence for text, shown below.
|
|
Note that "space" sorting is done before "A". |
AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz0123456789+-*/.,;:=?!@$%&()_' "<>[]
The above sequence has been extended by adding the following characters that were previously illegal for sorting purposes: #^`{|}~
For macros and script operation, any number of KEYn fields can be defined (the previous limit of ten has been removed). Key fields must be specified in consecutive order, and without gaps: for example, adding KEY1, KEY2 and KEY4 would not be allowed, and the reading of keyfields would stop after KEY2.
The previous limitation on keyfields being up to 10 words long has also been removed.
Example
|
!MGSORT |
&IN(MODEL), &OUT(SMODEL), *KEY1(IJK), *KEY2(XC), *KEY3(YC), *KEY4(ZC) |
Error and Warning Messages
|
Message |
Description |
Solution |
| Warning: Keyfield:field_nameis implicit and will be ignored. |
An implicit keyfield was provided. Since all values within it are identical, the keyfield is ignored. |
|
| Warning: Missing keyfield. |
A requested keyfield could not be found in the file. The keyfield will be ignored. |
|
| Error: No valid keyfields have been found. Process aborted. |
There were no valid keyfields to sort on. Keyfields may not have been specified, were not found in the file, or were implicit. |
|
| Error: Failed to open input file. |
The required input file could not be found, or could not be opened for reading. |
The file may not exist, be open in another application, or you may not have access rights to the file. |
| Error: Unable to create DmFile read buffer! |
An unspecified error (possibly memory related) when reading the input file. |
|
| Error: Unable to open temporary chunk filefile_name. |
An unspecified error when creating a temporary file - possibly due to a shortage of disk space. |
|
| Error: Error writing to temporary chunk filefile_name. |
An unspecified error when writing to a temporary file - may be followed by a description of the problem, if available. |
|
| Error: Error whilst writing data tofile_name. |
An unspecified error when writing to the output file - may be followed by a description of the problem, if available. |
|
| Error: Could not createfile_name. |
An unspecified error when creating the output file - may be followed by a description of the problem, if available. |
The output file may be open in another application, or you may not have access rights to overwrite or create it. |
| Error: Could not create an instance of DmTable. |
An internal error when accessing the Datamine file. |
|
| Error: Could not create an instance of DmSchema. |
An internal error when accessing the Datamine file. |
