This chapter describes in detail the usage of the Postman's Sort Applications Interface. This interface consists of function calls implemented via the DLL mechanism in Windows and via a table of function pointers whose address is stored a software interrupt in DOS. Function prototypes for these function calls are found in PSORTW.H and PSORT.H respectively. Just #include these header files in your program and you can invoke the function calls described below.
There are two command line switches that are relevant only to the PSORT.DLL and PSORTTSR versions of the Postman's Sort. The are used to communicate the file size of the file to be sorted when the input file is not specified on the command line. This can only happen when PSORT.DLL is used and records are transferred to the sort via the PsortSend function call discussed below.
-fs <estimated size of file>
-rs <estimated average record size in bytes>
If these switches are not used and there is no input file specified on the command line, it is probable that much more memory than necessary will be allocated. This will result in a severe performance degradation in Windows. An alternative in such cases would be to use the -m switch to specify a maximum amount of memory that PSORT.DLL should be allowed to allocate. This will achieve the same result although the use of the -fs and -rs switches will ensure that no more that the minimum required memory is reserved. This will be more efficient. The filesize should be specified in K (the default) or with the k, m or g suffix to indicate k bytes, megabytes or gigabytes respectively.
The principal method to use PSORT.DLL is to call the functions listed below. Source Modules that make these calls should INCLUDE the file PSORTW.H. The DLL import library PSORT.LIB should be included on the link editor command line.
Note that records sent to / retrieved from PSORT.DLL are
not transformed in any way. That is text record retrieved will
be terminated with a carriage return/line feed (i.e. 0x0d 0x0a).
Text records send to PSORT.DLL should also include these
characters. The record size parameter will always include
these characters. In other words, the interface with PSORT.DLL
is one of binary i/o.
A pointer to a function which will be called when ever the psort dll has a message which should be displayed.
A pointer to a function which will be called occasionally so that control may be passed to another part of windows. This can be used to permit a long sort to be run in the background. Psort maintains an internal counter. Each time a record is read or written this counter is decremented. When it reaches zero this function is called. The application can then yield to windows or perform other processing. The value returned to psort is used to reload the the counter. A typical value returned might be 1000 indicating that psort should yield to the calling application every 1000 read/write operations
A pointer to a record read callback function specified by application. Returns a non zero value if an error record could not be read because of error. In all other circumstances a zero should be returned.
A pointer to a record write callback function specified by application. Returns a non zero value if an error record could not be written because of an error. In all other circumstances a zero should be returned.
This function is called to allocate a sorting context identified by a PSORTHANDLE. I requires several parameters as indicated. The returned sorting instance handle should be stored by the application for subsequent use when calling other functions in api.
Start sorting. Pass call backs and command line parameters to psort. This function returns a zero if no errors occurred. Otherwise it returns a non-zero value. Errors detected by psort return a value of 1. Errors detected the application call back functions will have values specified when an error is returned.
The inverse of PsortCreate, indicates that the sorting context is no longer needed and that resources may be released and returned to operating system
This function is called by any of the call back functions to indicate that the sorting process should be aborted.
This function is used by an application to send data to psort when the read function argument of PsortStart was loaded with the manifest constant PSORTRETRIEVE. That is, PsortSend is the mirror image of PSORTRETRIEVE.
This function is used to write records to directly to the sorted output when the command line specifies the output file. This can be called before the first sorted record is written to output or after the last one is. It can be used for writing special header or trailer records.
This function is used by an application to retrieve sorted records from psort when the write function argument of PsortStart was loaded with the manifest constant PSORTSEND. That is, PsortRetrieve is the mirror image of PSORTSEND.
This function is used to read records from the input files(s) specified on the Postmans sort command line. This can be used when filtering input records or just to skip certain input records.
This function is returns the captured psort output when no display callback is used. It must be called after PsortStart has returned and before PsortDestroy has been called.