DosReplaceModule

DosReplaceModule replaces or caches a module that is in use.

Syntax

DosReplaceModule( pszModName, pszReplaceWith, pszBackupName )

Parameters

pszModName (PSZ) - input

Name of module to replace. Points to the name of the existing module. Required.

pszReplaceWith (PSZ) - input

Name of module to replace the above with. Points to the name of the new module. Optional.

pszBackupName (PSZ) - input

Name to back up the old module with (if specified). Points to the name to be used for saving a copy of the old module. Optional.

Returns

APIRET rc

DosReplaceModule returns one of the following values:

• 0 NO_ERROR
• 2 ERROR_FILE_NOT_FOUND
• 3 ERROR_PATH_NOT_FOUND
• 5 ERROR_ACCESS_DENIED
• 17 ERROR_NOT_THE_SAME_DEVICE
• 26 ERROR_NOT_DOS_DISK
• 32 ERROR_SHARING VIOLATION
• 87 ERROR_INVALID_PARAMETER
• 108 ERROR_DRIVE_LOCKED
• 112 ERROR_DISK_FULL
• 267 ERROR_DIRECTORY
• 296 ERROR_MODULE_IN_USE
• 731 ERROR_MODULE_CORRUPTED

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

Linkage Definition

IMPORTS DosReplaceModule = DOSCALLS.417 

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 ) ;
}

Related Functions

• DosLoadModule
• DosCopy