DosReplaceModule

Syntax

rc = DosReplaceModule( pszModName, pszReplaceWith, pszBackupName );

Parameters

PSZ pszModName (input)

Name of module to replace

PSZ pszReplaceWith (input)

Name of module to replace the above with

PSZ pszBackupName (input)

Name to back up the old module with (if specified)

Returns

APIRET rc

Usage Explanation

This API is undocumented, but the entry point is located in the OS2386.LIB file.

This API allows you to replace a DLL that is in use. Apparently, this API checks to see whether the DLL named in pszModName is currently being used. If it is not, the API returns with an error. If it is, the O/S loads the entire module into memory, and releases the filesystem's hold on the file. It will then copy the pszReplaceWith file over the pszModName file, and optionally back up pszModName to pszBackupName.

No guarantees...

The prototype is APIRET APIENTRY DosReplaceModule(PSZ pszModName, PSZ pszReplaceWith, PSZ pszBackupName);

Information from Rick Papo Undocumented

Prototype:

APIRET APIENTRY DosReplaceModule ( PSZ pszOldModule, PSZ pszNewModule, PSZ pszBackupModule ) ; 

Linkage Definition:

IMPORTS DosReplaceModule = DOSCALLS.417 

Parameters:

PSZ pszOldModule     The name of the module being replaced. 
PSZ pszNewModule     The name of the replacement module. 
PSZ pszBackupModule The new name of the old module. 

Comments:

When a DLL or EXE file is in use by the system, the file is locked. It can not therefore be replaced on the hard disk by a newer copy. This API is to allow the replacement on the disk of the new module whilst the system continues to run the old module. The contents of the file 'pszOldModule' are cached by the system and the file is closed. A backup copy of the file is created as 'pszBackupModule' for recovery purposes should the install program fail. The new module 'pszNewModule' takes the place of the original module on the disk.

Note: The system will continue to use the cached old module until all references to it are released. The next reference to the module will cause a reload from the new module on disk.

Note: Only protect mode executable files can be replaced by this API. This cannot be used for DOS/Windows programs, or for data files.

Note: pszNewModule and pszBackupModule may be NULL pointers.

Note: This API uses the swap file to cache the old module. This API is expensive in terms of disk space usage.

Note: Unlike some of the other undocumented APIs, this function IS defined in os2386.lib, so you probably will not have to import it in your DEF file.

Example:

int main ( int argc, char *argv[] ) {
   APIRET rc ;
   if ( argc != 4 ) {
      printf ( "Usage: <OldDll> <NewDll> <BackupDll>\n" ) ;
      return ( 1 ) ;
   }
   rc = DosReplaceModule ( argv[1], argv[2], argv[3] ) ;
   if ( rc ) {
      printf ( "Error %d.\n", rc ) ;
   }
   return ( rc ) ;
}