Beginning in Version 20, PC*MILER|Rail-Connect provides three new APIs that enable users to identify which datasets are available and to switch between them. The new APIs are described below.


PCRSSwitchDataSet (int DataSetID)


The PCRSSwitchDataSet() allows you to dynamically switch to a different dataset any time after your PCRSInitSrv() call and before you call the PCRSCleanupSrv().  Before making this API call, you should call PCRSIsUpdateAvailable(DataSetID) to verify that the dataset has previously been downloaded and is available (see below).


The names of the four datasets that are expected to be available throughout the year for the Version 25 release are listed in Table 1 below, along with the DataSetID integer to use. The names below are also the names of the subfolders containing rail data updates under your RAILNET install folder.


Table 1

Dataset ID
Dataset Name
Description
0
"25.0_BASE"
Base Data included in the Version 25 release
1
"25.1_UPDATE"
First update of Rail data
2
"25.2_UPDATE"
Second update of Rail data


The user must pass in a valid dataset ID (see Table 1). For example, to switch to the 25.2 update, the dataset ID is the integer value of 2.


Please remember, the dynamic switch of rail data is only good for the Connect session. Once the session closes, the use of the new dataset is lost. Once you restart your Connect session, the default dataset (defined in the user interface) is again loaded. Also, once you dynamically switch datasets, any existing trips you established earlier are deleted within this API call. For example, if you try to add a stop to a previous open trip, you will receive an error. 



Table 2 below lists return values.



Table 2

Return Value
Description
0
Switching datasets was SUCCESSFUL.
PCRS_BADARG
User did not pass in valid dataset value (0 thru 3).
PCRS_DATANOTAVAIL
User passed in valid dataset, but the set is not available for data switching because it has not been downloaded.  The user should "Check for Updates" from within the GUI to download the update.
PCRS_ERRORSWITCHINGDATA
Fatal Error - Cannot switch datasets due to an error in processing, please contact Technical Support.



PCRSIsUpdateAvailable (int DataSetID)


The above API enables the user to check if a dataset is available. The user must pass in a valid dataset ID. Before you switch datasets within a Connect Session, you should make this API call to ensure that the set is available.


Table 1 below lists valid dataset IDs.


Table 1

Dataset ID
Dataset Name
Description
0
"25.0_BASE"
Base Data included in the Version 25 release
1
"25.1_UPDATE"
First update of Rail data
2
"25.2_UPDATE"
Second update of Rail data
3
"25.3_UPDATE"
Third update of Rail data


Table 2 below lists return values.


Table 2

Return Value
Description
1
Dataset is available
0
Dataset is not available
PCRS_BADARG
User did not pass in valid dataset value (0 thru 3)



PCRSGetAvailableUpdates (int *dataSet_1, int *dataset_2, int *dataset_3)


The API above enables the user to find out which updates are available. It is similar to the PCRSIsUpdateAvailable() API call that queries whether a specific dataset is available.


Since there are three potential updates over the duration of a PC*MILER|Rail yearly release, there are three values coming back from this API. If the value coming back within the pointer to the arg is 1, the dataset is available;  otherwise 0 (zero). Using one call, this API lets you know which data updates have been downloaded.


Table 1 below lists valid dataset IDs.


Table 1

Dataset 
Arg Type
Value coming back from API call
dataSet_1
Int*
1 = dataset one is available;  0 = otherwise
dataSet_2
Int*
1 = dataset two is available;  0 = otherwise
dataSet_3
Int*
1 = dataset three is available;  0 = otherwise


Table 2 below lists return values.


Table 2

Return Value
Description
0
Success
-1
Failure