DLL/TSR Applications Interface

Go to Robert Ramey Software Development Home Page

6. DLL/TSR Applications Interface

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. Command Line Switches

6.1. Command Line Switches

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. Function Calls

6.2. Function Calls

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.

PSORTHANDLE Handle to a psort context which is used to identify the particular psort instance.

PSORTDISPLAY/PSORTDISPLAYPTR Callback Function Prototype.

A pointer to a function which will be called when ever the psort dll has a message which should be displayed.

#define PSORTDISPLAY void CALLBACK void (CALLBACK *PSORTDISPLAYPTR)( LPCSTR /* NULL terminated string which * contains the message. It will * usually be terminated with a * newline */ );

PSORTYIELD/PSORTYIELDPTR Callback Function Prototype.

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

#define PSORTYIELD unsigned int CALLBACK unsigned int (CALLBACK *PSORTYIELDPTR)( void );

PSORTREAD/PSORTREADPTR Callback Function Prototype.

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.

#define PSORTREAD int CALLBACK int (CALLBACK * PSORTREADPTR)( size_t FAR *, /* address where size of record read is to be * returned. Must be filled with a non-zero * value except if there are no more records * to be read. In that case this address * should be loaded with a zero. */ LPSTR FAR * /* address where address of record is to be * returned. If there are no more records * this address should be loaded with NULL * pointer */ );

PSORTWRITE/PSORTWRITEPTR Callback Function Prototype.

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.

#define PSORTWRITE int CALLBACK int (CALLBACK * PSORTWRITE)( size_t, /* size of record to be written. Will be a * non-zero value unless there are no more * records to be written. In that case it will * be equal to 0. */ LPSTR /* address of record to be written. Will * equal NULL if there are no more records to * be written. */ );

PsortCreate API Function.

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.

PSORTHANDLE WINAPI PsortCreate( PSORTDISPLAY, /* Pointer to applications error message * display handler. This must be valid * function pointer. It cannot be NULL. */ PSORTYIELD /* Pointer to yield callback function. * This argument is optional and can be * specified with NULL. This would indicate * that psort should not yield. This * would be especially appropriate for * small sorts or when that co-routine * mechanism is used. In this latter case * control is returned to the application * each time a record is read and/or written * so there is normally no need for psort to * yield. */ );

PsortStart API Function.

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.

int WINAPI EXPORT PsortStart( PSORTHANDLE, /* handle of sorting context returned by * PsortCreate */ PSORTREADPTR, /* Pointer to function which reads records * to be sorted. In addition to a valid * pointer to a function in the applications * program, this argument may contain NULL * to indicate that the command line * contains an input file(s) specification * so there is no need to call a function * in the application to read records to be * sorted. This argument may also * contain the manifest constant PSORTRETRIEVE * to indicate that records will be sent to * psort via the PsortSend call. This is * referred to a co-routine mechanism. */ PSORTWRITEPTR, /* Pointer to function which psort will use * write sorted output records. In addition * to a valid pointer to a function in the * applications program, this argument may * contain a NULL to indicate the the command * line contains an output file specification * so there is no need to call any function * in the application for this purpose. This * argument may also contain the manifest * constant PSORTSEND to indicate that the * records can be retrieved from psort via * the PsortRetrieve call. */ LPCSTR /* psort command line string */ );

PsortDestroy API Function.

The inverse of PsortCreate, indicates that the sorting context is no longer needed and that resources may be released and returned to operating system

void WINAPI PsortDestroy( PSORTHANDLE /* Handle of context to terminate */ );

PsortExit API Function.

This function is called by any of the call back functions to indicate that the sorting process should be aborted.

void WINAPI PsortExit( PSORTHANDLE, /* Handle of context to terminate */ int /* exit code. This must be a non-zero * integer. This will be the value * that is returned by PsortStart. */ );

PsortSend API Function.

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.

void WINAPI PsortSend( PSORTHANDLE, /* handle of sorting instance waiting * to read a record */ size_t, /* number of bytes in record */ LPSTR /* address of record record */ );

PsortWrite API Function

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.

int WINAPI PsortWrite( PSORTHANDLE, /* handle of sorting instance */ size_t, /* number of bytes in record */ LPSTR /* address of record */ );

PsortRetrieve API Function.

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.

void WINAPI PsortRetrieve( PSORTHANDLE, /* handle of sorting instance */ size_t _far *, /* pointer to variable that will be * loaded with size of record */ LPSTR _far * /* address of variable that will * contain address of retrieved record */ );

PsortRead API Function

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.

int WINAPI PsortRead( PSORTHANDLE, /* handle of sorting instance */ size_t FAR *, /* pointer to variable that will be *loaded with size of record */ LPSTR FAR * /* pointer of variable that will contain * address of retrieved record */ );

PsortMessage API Function

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.

LPCSTR WINAPI PsortMessage( PSORTHANDLE Handle, /* handle of sorting instance */ );