Multi-Version Switch uses the same APIs as PC*MILER|Connect with only minor changes to accommodate accessing multiple versions of PC*MILER. Your application should be linked to pcmmv.dll, instead of pcmsrv32.dll. This will provide the modified APIs as described below.
The key difference when using Multi-Version Switch is that a new function, PCMSOpenServer2, is provided to be used in place of PCMSOpenServer. This new function takes an additional parameter which is a string that matches the appropriate key in the pcmmv.ini file. This key identifies which version of PC*MILER will be connected to.
For example, if the key [PCMiler 290] is defined in the pcmmv.ini file to identify version 29 of PC*MILER, then the extra parameter passed to PCMSOpenServer2 would be PCMiler 290. serverID = PCMSOpenServer2(“PCMiler”, “290”)
Note that the first ServerID will be 10000 on success. Subsequent calls to PCMSOpenServer2() will return ServerID’s incremented by 1. (IE: 10000, 10001, 10002…)
- If PCMSOpenServer is called instead of PCMSOpenServer2, the ServerID returned will refer to the product version specified under the [Default] section of pcmmv.ini. Use of PCMSOpenServer is not recommended.
- Pcmmv.dll does a case sensitive match between the values passed in the PCMSOpenServer2 function and the bracketed values in pcmmv.ini.
All PC*MILER|Connect functions that take a Server ID parameter will use the version of PC*MILER that was identified during the call to PCMSOpenServer2. Similarly, functions that accept a "trip trip" parameter will use the particular version of PC*MILER associated with the Server ID used to create the trip. No further programming changes are required.
Summary of Alternative Functions
The following are the alternative functions included in the Multi-Version Switch API.
- PCMSOpenServer2(Const Char Name_With_Version,NULL)
- PCMSAbout2(PCMServerID serv, const char FAR *which, char FAR *buffer, int bufSize)
- PCMSGetErrorString2(PCMServerID serv, int errorCode, char *buffer, int bufSize)
- PCMSSetDefaultRegion2(PCMServerID serv, char FAR *regionId)
- PCMSGetDefaultRegion2(PCMServerID serv, short bufSize, char FAR *regionId)
NOTE: PCMSSetDefaultRegion has been deprecated at the pcmsock29.exe level. All calling applications should use PCMSNewTripWithRegion instead.
Connections and Threads
The threading model supported by the Multi-Version Switch API is identical to that supported by the C API. A given ServerID can be reused across threads since calls that take a Server ID are automatic. However, a given trip handle should only be used on a single thread at a time.
The network connection model is similar to the threading model. Calls taking a Server ID operate automatically and will generally create and destroy a new network connection on each call. For calls taking a trip handle, the network connection is created by PCMSNewTrip and reused by subsequent calls taking that trip handle until being destroyed by PCMSDeleteTrip.
Be careful not to "leak" Trip handles. There is a memory assignment associated with each Trip handle generated, and this memory is not freed up until PCMSDeleteTrip is called.