extract_sort()

Purpose	Sorts an extract file
Old name	#define sort_extract extract_sort
Syntax	int extract_sort(void);
Description	The extract_sort() function sorts an extract file, using the DP4 program SORTEXTR. The sorted field of the header record EXT_HEADER is set to TRUE by the SORTEXTR program and used to check that the sort was successfully run. The extract file must have been previously created by a call to the function extract_open(). See this function for details of how to write your own sort program. The progress of the sort program is normally displayed on the screen. To suppress this, set the suppress_output field of the header record EXT_HEADER to TRUE. If this is done, a 'please wait' message is displayed before calling the function extract_sort(). The function extract_sort() calls the function trm_run_program() with the following parameters:
	Parameter	Description
	name	"sortextr <extfile>", where <extfile> is the filename passed to the function extract_open()
	batch	FALSE. Do not run as a batch program
	copy_screen	TRUE. The screen as it is when sortextr completes is copied to this applications screen buffer. (This is only effective on MS-DOS,FlexOS, and OS/2), and may be undesirable.
	If you want the third parameter to the function trm_run_program() to be FALSE, you must write your own version. This is shown in the example under extract_open().
Return values	Returns the sorted field of the EXT_HEADER header record
See also	extract_open(), extract_write(), extract_read(), extract_close()
Example	See the example in extract_open()
Remarks	The sort algorithm used is a variation on natural merge-sort: Records are added to an AVL balanced binary tree until the area allowed for in-memory sorting is full. Then the smallest record is removed from the in memory area and written to a file and a new record is added, and the process is repeated for each remaining record. Until and unless the new record is added becomes the smallest record it is known that the file and the in memory area are perfectly sorted. If a new record does become the smallest record all the remaining memory records are written to the file, so that a new in memory sort can be started. The size of each section in the file created is remembered for a later merge phase. At the original extract file is no longer needed as all the information is now in the partially sorted file. When the sort phase is complete, as many merge pahses as are required to reduce the number of sorted sub-sections of the file to 1 are performed. The merging uses a straight forward write to the file that is no longer required to ceate the merged file. The merge algortihm adds one record from each merge section to an AVL binary tree, and repeatedly removes the smallest node to the new sort file and adds a new node from the same merge section that the removed node came from.