CA2330931C - Model train control system - Google Patents

Abstract

A system (10) which operates a digitally controlled model railroad transmitting a first command from a first interface through a first communications transport (12). A second command is transmitted from a second client program (14) to the resident external controlling interface (16) which queues the controlling interface sends third and fourth commands respectively, to a digital command station (18) for execution on the digitally controlled model railroad.

Description

z MODEL TRAIN CONTROL SYSTEM
BACXGROUND OF THE INVENTION
The present invention relates to a system for controlling a model railroad.
Model railroads have traditionally been constructed with of a set of interconnected sections of train track, electric switches between different sections of the train track, and other electrically operated devices, such as train engines and draw bridges. Train engines receive their power to travel. on the train track by electricity provided by a controller through the track itself. The speed and direction of~t;he train engine is controlled by the level and polarity, respectively, of the electrical power supplied to the train track. The operator manually pushes buttons or pulls levers to cause the switches or other electrically opexated devices to function, as desired. Such model railroad sets are suitable for a single operator, but unfortunately they lack the capability of adequately controlling multiple trains independently. In addition, ~~uch model railroad sets are not suitable for being controlled by multiple operators, especially if the operator°s are located at different locations distant from. the model railroad, such as different cities.
A digital command control (DDC) system has been developed to provide additional cont~__~ollability of individual train engines and other a:Lectrical devices.
Each device the operator desires to control, such as a train engine, includes an individually addressable digital decoder. A digital command :station (DCS) is electrically connected to the train l4rack to provide a command in the form of a set of encoded digital bits to a particular device that includes a di<~ital decoder. The digital command station is typically controlled by a personal computer. A suitable standard.for the digital command control system is the NMRA DCC Standards, issued March 1997. While providing the ability to individually control different devices of the railroad set, the DCC system still fails to provide the capability for multiple operators to control the railroad devices, especially if the operators are remotely located from the railroad set and each other.
DigiToys SystemsTM of Lawrenceville, Georgia has developed a software program for controlling a model railroad set from a remote location. The software includes an interface which allows the operator to select desired changes to devices of the railroad set that include a digital decoder, such as increasing the speed of a train or switching a switch. The software issues a command locally or through a network, such as the Internet, to a digital command station at the railroad set which executes the command.
The protocol used by the software is based on COBRATM from OPEN MANAGEMENT
GROUPTM where the software issues a command to a communication interface and awaits confirmation that the command was executed by the digital command station.
When the software receives confirmation that the command executed, the software program sends the next command through the communication interface to the digital command station. In other words, the technique used by the software to control the model railroad is analogous to an inexpensive printer where commands are sequentially issued to the printer after the previous command has been executed. Unfortunately, it has been observed that the response of the model raikoad to the operator appears slow, especially over a distributed network such as the Internet. One technique to decrease the response time is to use high-speed network connections but unfortunately such connections are expensive.
What is desired, therefore, is a system for controlling a model railroad that effectively provides a high-speed connection without the additional expense associated therewith.
The foregoing and other objectives, features, and advantages of the invention will be more readily understood upon consideration of the following detailed description of the invention, taken in conjunction with the accompanying drawings.
SUMMARY OF THE PRESENT INVENTION
The present invention overcomes the aforementioned drawbacks of the prior art, in a first aspect, by providing a system for operating a digitally controlled model railroad that includes transmitting a first command from a first client program to a resident external controlling interlace through a first communications transport. A second command in transmitted from a second client program to the resident external controlling interface through a second communications transport. The first command and the second command are received by the resident external controlling interface which queues the first and second commands. The resident external controlling interface sends third and fourth commands representative of the first and second commands, respectively, to a digital command station for execution on the digitally controlling model railroad.
Incorporating a communications transport between the multiple client programs and the resident external controlling interlace permits multiple operators of the model railroad at locations distant from the physical model railroad and each other. In the environment of a model railroad club where the members want to simultaneously control devices of the name model railroad layout, which preferably includes multiple trains operating thereon, the operators each provide commands to the resistant external controlling interface, and hence the model railroad. In addition by queuing by commands at a single resident external controlling interface permits controlled execution of the commands by the digitally controlled model railroad, would may w otherwise conflict with one another.
In another aspect of the present invention the first command is selectively processed and sent to one of a plurality of digital command stations for execution on the digitally controlled model railroad based upon information contained therein. Preferably, the second command is also selectively processed and sent to one of the plurality of digital command stations for execution on the digitally controlled model railroad based upon information contained therein. The resident external controlling interface also preferably includes a command Z5 queue to maintain the order of the commands.
The~command queue also allows the sharing of multiple devices, multiple clients t.o communicate with the same device (locally or remote) in a controlled manner, and multiple clients to comm~.unicate with 2~0 different devices. In other words, the command queue permits the proper execution in the cases of: (1) one client to many~devices, (2) many clients to one device, and (3) many clients to many devices..
In yet another aspect of the present invention 25 the first command is transmitted from a first client program to a first processor through, a first communications transport. The first. command is received at the first processor. The first processor provides an acknowledgement to the first client program through the 30 first communications transport indicating that the first command has properly executed prior to execution of commands related to the first command by the digitally controlled model railroad. The communications transport is preferably a COM or DCOM interface.
35 The model railroad application involves the use of extremely slow real-time interfaces between the digital cammand stations and the devices of the model WO 99/66999 PCTlUS99/14229 railroad. In order to increase the .apparent speed of execution to the client, other than 'using high-speed communication interfaces, the resident external controller interface receives.the command and provides an 5 acknowledgement to the client program in a timely manner before the execution of the command ;by the digital command stations. Accordingly, the execution of commands provided by the resident external controlling interface to the digital command stations occur in a synchronous manner, such as a first-in-first-out manner. The COM and DCOM communications transport between the client program and the resident external controlling interface is operated in an asynchronous manner, :namely providing an acknowledgement thereby releasing th~a communications transport to accept further communications prior to the actual execution of the command. The combination of the synchronous and the~asynchronous data communication for the commands provides the benefit that the operator considers the commands to occur near:Iy instantaneously while permitting the resident external controlling interface to verify that the command is proper and cause the commands to execute in a controlled manner by the digital command stations, all withowt additional high-speed communication networks. Moreover, for traditional distributed software execution there is no motivation to provide an acknowledgment prior to t:he execution of the command because the command executes quickly and most commands are sequential in nature. In other words, the execution of the next command is dependent upon proper execution of the prior command so there would be no motivation to provide an acknowledgment prior to its actual execution.
BRIEF DESCRIPTION OF THE SEVERAL VIEWS OF THE DRAWINGS
FIG. 1 is a block diagram of an exemplary embodiment of a model train control system.

FIG. 2 is a more detailed block diagram of the model train control system of FIG. 1 including external device control logic.
FIG. 3 is a block diagram of the external device control logic of FIG. 2.
DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENT
Referring to FIG. 1, a model train control system 10 includes a communications transport 12 interconnecting a client program 14 and a resident external controlling interface 16.
The client program 14 executes on the model raikoad operator's computer and may include any suitable system to permit the operator to provide desired commands to the resident external controlling interface 16. For example, the client program 14 may include a graphical interface representative of the model railroad layout where the operator issues commands to the model railroad by making changes to the graphical interface. The client program 14 also defines a set of Application Programming Interfaces (API's), described in detail later, which the operator accesses using the graphical interface or other programs such as Visual BasicTM, C++TM, JavaTM, or browser based applications.
There may be multiple client programs interconnected with the resident external controlling interface 16 so that multiple remote operators may simultaneously provide control commands to the model railroad.
The communications transport 12 provides an interface between the client program 14 and the resident external controlling interface 16. The communications transport 12 may be any suitable communications medium for the transmission of data, such as the Internet, local area network, satellite links, or multiple processes operating on a single computer. The preferred interface to the communications transport 12 is a COM
or DCOM interface, as developed for the WINDOWSTM operating system available from MICROSOFT CORPORATION. The communications transport 12 also determines if the resident external controlling interface 16 is system resident or remotely located on an external system. The communications transport 12 may also use private or public communications protocol as a medium for communications. The client program 14 provides commands and the resident external controlling interface 16 responds to the communications transport 12 to exchange information. A description of COM
(common object model) and DCOM (distributed common object model) is provided by ChappelTM
in a book entitled Understanding ActiveXTM and OLETM, Microsoft PressTM.
Incorporating a communications transport 12 between the client programs) 14 and the resident external controlling interface 16 permits multiple operators of the model railroad at locations distant from the physical model railroad and each other. In the environment of a model railroad club where the members want to simultaneously control devices of the same model railroad layout, which preferably includes multiple trains operating thereon, the operators each provide commands to the resident external controlling interface, and hence the model railroad.
The manner in which commands are executed for the model railroad under COM and DCOM may be as follows. The client program 14 makes requests in a synchronous manner using COM/DCOM to the resident external interface controller 16. The synchronous manner of the request is the technique used by COM and DCOM to execute commands. The communications transport 12 packages the command for the transport mechanism to the resident external controlling interface 16. The resident external controlling interface 16 then passes the command to the digital command stations 18 which in turn executes the command. After the digital command station 18 executes the command an acknowledgement is passed back to the resident external controlling interface 16 which in turn passes an acknowledgement to the client program 14. Upon receipt of the acknowledgement by the client program 14, the communications transport 12 is again available to accept another command. The train control system 10, without more, permits execution of commands by the digital command stations 18 from multiple operators, but like the DigiToys Systems' software the execution of commands is slow.
The present inventor came to the realization that unlike traditional distributed systems where the commands passed through a communications transport are executed nearly instantaneously by the server and then an acknowledgement is returned to the client, the model railroad application involves the use of extremely slow real-time interfaces between the digital command stations and the devices of the model railroad.
The present inventor came to the further realization that in order to increase the apparent speed of execution to the client, other than using high-speed communication interfaces, the resident external controller interface 16 should receive the command and provide an acknowledgement to the client program 14 in a timely manner before the execution of the command by the digital command stations 18. Accordingly, the execution of commands provided by the resident external controlling interface 16 to the digital command stations 18 occur in a synchronous manner, such as a first-in-first-out manner. The COM
and DCOM communications transport 12 between the client program 14 and the resident external controlling interface 16 is operated in an asynchronous manner, namely providing an acknowledgement thereby releasing the communications transport 12 to accept further communications prior to the actual execution of the command.
The combination of the synchronous and the asynchronous data communication for the commands provides the benefit that the operator considers the commands to occur nearly instantaneously while permitting the resident external controlling interface 16 to verify that.the command is proper and cause the commands to execute in a controlled manner by the digital command stations 18, all without additional high-speed communication networks. PZoreover, for traditional distributed software execution there is no motivation to provide an acknowledgment prior to the execution of the command because the command executes quickly and most commands are sequential in nature. In other words, the execution of the nee;t command is dependent upon proper execution of tree prior command so there would be no motivation to provide an acknowledgment prior to its actual execution. It is to be understood that other devices, such as digital devices, may be controlled in a manner as described for model railroads.
Referring to FIG. 2, the client program 14 sends a command over the.communications transport 12 that is received by an asynchronous evmmand processor 100.
The asynchronous command processor 1r~0 queries a local database storage 102 to determine if it is necessary to package a command to be transmitted t.o a command queue 104. The local database storage 102 primarily contains the state of the devices of the model railroad, such as for example, the speed of a train, th.e direction of a train, whether a draw bridge is up or' down, whether a light is turned on or off, and the configuration of the model railroad layout. If the command received by the asynchronous command processor 100 is a query of the .state of a device, then the asynchronous command processor 100 retrieves such information from the local database storage 102 and provides the information to an asynchronous response processor 106. The asynchronous response processor 10& then provides a response to the client program 14 indicating the state of the device and releases the communications transport 12 for the next command.

. The asynchronous command pi..°ocessor 100 also verifies, using the configuration inf=ormation in the local database storage 102, that the command received is a potentially valid operation. If the command is 5 invalid, the asynchronous command processor 100 provides such information to the asynchronous response processor 106, which in turn returns an error indication to the client program 14.
The asynchronous command processor 100 may 10 determine that the necessary information is not contained in the local database storage 102 to provide a response to the client program 14 of the device state or that the command is a valid action. Actions may include, for example, an increase in the train's ~~peed, or turning on/off of a device. In either case, the valid unknown state or action command is packaged and forwarded to the command queue 104. The packaging of the command may also include additional information from t:he local database storage 102 to complete the client program 14 request, if necessary. Together with packaging t:he command for the command queue 104, the asynchronous command processor 100 provides a command to the asynchronous request processor 106 to provide a response to the client program 14 indicating that the event has occurred, even though such an event has yet to occur on the phy~;ical railroad layout.
As such, it can be observed that whether or not the command is valid, whether or not the information requested by the command is available: to the asynchronous command processor 100, and whether or not the command has executed, the combination of the asynchronous command processor 100 and the asynchronous reaponse processor 106 both verifies the validity of the command and provides a response to the client program 14 thereby freeing up the communications transport 12 for addit.ionai commands.
Without the asynchronous nature of th.e resident external controlling interface 16, the response to the client program 14 would be, in many circumstances, delayed thereby resulting in frustration to the operator that the model railroad is performing in a slow and painstaking manner. In this manner, the railroad operation using the asynchronous interface appears to the operator as nearly instantaneously responsive.
Each command in the command queue 104 is fetched by a synchronous command processor 110 and processed. The synchronous command processor 110 queries a controller database storage 112 for additional information, as necessary, and determines if the command has already been executed based on the state of the devices in the controller database storage 112. In the event that the command has already been executed, as indicated by the controller database storage 112, then the synchronous command processor 110 passes information to the command queue 104 that the command has been executed or the state of the device. The asynchronous response processor 106 fetches the information from the command queue 104 and provides a suitable response to the client program 14, if necessary, and updates the local database storage 102 to reflect the updated status of the railroad layout devices.
If the command fetched by the synchronous command processor 110 from the command queue 104 requires execution by external devices, such as the train engine, then the command is posted to one of several external device control logic 114 blocks.
The external device control logic 114 processes the command from the synchronous command processor 110 and issues appropriate control commands to the interface of the particular external device 116 to execute the command on the device and ensure that an appropriate response was received in response. The external device is preferably a digital command control device that transmits digital commands to decoders using the train track. There are several different manufacturers of digital command stations, each WO 99/66999 PCT/US99/ht229 of which~has a different set of input. commands, so each external device is designed for a particular.digital command station. In this manner, the:~system is compatible with different digital command stations. The digital command stations 18 of the e~aernal devices 116 provide a response to the external device control logic 114 which is checked for validity andl identified as to which prior command it corresponds to so that the controller database storage 112 may be updated properly.
The process of transmitting commands to and receiving responses from the external devices 1.16 is slow.
The synchronous command processor 110 is notified of the results from the external control logic 114 and, if appropriate, forwards thE: results to the command queue 104. The asynchronous response processor 100 clears the results from the command queue 104 and updates the local database storage 102 and sends an asynchronous response to the client program 14, if needed. The response updates the client program 14 of the actual state of the railroad track devices, if changed, and provides an error message to the client program 14 if the devices actual stage was previously improperly reported or a command did not execute properly.
The use of two separate database storages, each of which is substantially a mirror image of the other, provides a performance enhancement by a fast acknowledgement to the client program 14 using the local database storage 102 and thereby freE:ing up the communications transport 12 for additional commands. In addition, the number of commands forwarded to the external device control logic 114 and the external devices 116, which are relatively slow to respond, is minimized by maintaining information concerning the state and configuration of_the model railroad. Also, the use of two separate database tables 102 and 112 allows more efficient multi-threading on multi-px-ocessor computers.

In order to achieve the separation of the asynchronous and synchronous portions of the system the command queue 104 is implemented as a named pipe, as developed by MICROSOFTTT'' for WINDOWS'. The queue 104 allows both portions to be separate from each other, where each considers the other to be the destination device.
In addition, the command queue maintains the order of operation which is important to proper operation of the system.
The use of a single command queue 104 allows multiple instantiations of the asynchronous functionality, with one for each different client. The single command queue 104 also allows the sharing of multiple devices, multiple clients to communicate with the same device (locally or remote) in a controlled manner, and multiple clients to communicate with different devices. In other words, the command queue 104 permits the proper execution in the cases of: ( 1 ) one client to many devices, (2) many clients to one device, and (3) many clients to many devices.
The present inventor came to the realization that the digital command stations provided by the different vendors have at least three different techniques for communicating with the digital decoders of the model railroad set. The first technique, generally referred to as a transaction (one or more operations), is a synchronous communication where a command is transmitted, executed, and a response is received therefrom prior to the transmission of the next sequentially received command. The DCS may execute multiple commands in this transaction. The second technique is a cache with out of order execution where a command is executed and a response received therefrom prior to the execution of the next command, but the order of execution is not necessarily the same as the order that the commands were provided to the command station. The third technique is a local-area-network model where the commands are transmitted and received simultaneously.
In the LAN model there is no requirement to wait until a response is received for a particular command prior to sending the next command. Accordingly, the LAN model may result in many commands being transmitted by the command station that have yet to be executed: In addition, some digital command stations use two or more of these techniques. ;
With all these different techniques used to communicate with the model railroad sset and the system 10 providing an interface for each different type of command station, there exists a need for the capability of matching up the responses from each of the different types of command stations with the particular command issued for record keeping purposes. Without matching up .the responses from the command stations, the databases can not be updated properly.
Validation functionality i:> included within the external device control logic 114 to accommodate all of the different types of command stations. Referring to FIG. 3, an external command processor 200 receives the validated command from the synchronous command processor 110. The external command processor 200 determines which device the command should be directed to, the particular type of command it is, and builds state information for .
the command. The state information includes, for example, the address, type, port, variables, and type of commands to be sent out. In other words, the state information includes a command set for a particular device on a particular port device. In addition, a copy of the original command is maintained for verification purposes. The constructed command is forwarded to the command sender 202 which is another queue, and preferably a circular queue. The command sender 202 receives the command and transmits commands within its queue in a repetitive nature until the command as removed from its queue. A command response processor 204 receives all the WO 99/bb999 PCT/US99/14229 commands'from the command stations and passes the commands to the validation function 206. The validation function 206 compares the received command against potential commands that are in the queue of the command 5 sender 202 that could potentially provide such a result.
The validation function 206 determines one of four potential results from the comparison. First, the results could be simply bad data that. is discarded.
Second, the results could be partially executed commands 10 which are likewise normally discarded. Third, the results could be valid responses but not relevant to any command sent. Such a case could result from the operator manually changing the state of devicEas on the model railroad or from another external device, assuming a 15 shared interface to the DCS. Accordingly, the results are validated and passed to the resu.'Lt processor 210.
Fourth, the results could be valid responses relevant to a command sent. The corresponding command is removed from the command sender 202 and the~results passed to the result processor 210. The commands in the queue of the command sender 202, as a result of the validation process 206, are retransmitted a predetermined number of times, then if error still occurs the digital command station is reset, which if the error still persists then the command is removed and the operator is notified of the error.
APPLICATION PROGRAMMING INTERFACE
Train TooisTM Interface Descripition Building your own visual interface to a model railroad Copyright 1992-1998 KAM Industries.
Computer Dispatcher, Engine Commander; The Conductor, Train Server, and Train Tools are Trademarks of KAM
Industries, all Rights~Reserved.
Questions concerning the product can be EMAILED to:
traintools@kam.rain.com You can also mail questions to:
KAM Tndustries 2373 NW 185th Avenue Suite 416 Hillsboro, Oregon.97124 FAX - (503) 291-1222 Table of~ contents 1. OVERVIEW
1.1System Architecture 2. TUTORIAL
2.1 Visual BASIC Throttle Example Application 2.2 Visual BASIC Throttle Example Source Code 3. IDL COMMAND REFERENCE
3.1 Introduction 3.2 Data Types 3.3 Commands to access the server configuration variable database KamCVGetValue KamCVPutValue KamCVGetEnable KamCVPutEnable KamCVGetName KamCVGetMinRegister KamCVGetMaxRegister 3.4 Commands to program configuration variables KamProgram KamProgramGetMode.
KamProgramGetStatus KamProgramReadCV
KamProgramCV
KamProgramReadDecoderToDat,aBase KamProgramDecoderFromDataB;ase 3.5 Commands to control ail decoder types KamDecoderGetMaxModel.s KamDecoderGetModelName KamDecoderSetModelToObj KamDecoderGetMaxAddress KamDecoderChangeOldNewAddr KamDecoderMovePort KamDecoderGetPort KamDecoderCheckAddrInUse KamDecoderGetModelFromObj KamDecoderGetModelFacility KamDecoderGetObjCount KamDecoderGetObjAtIndex KamDecoderPutAdd KamDecoderPutDe1 KamDecoderGetMfgName KamDecoderGetPowerMode KamDecoderGetMaxSpeed 3.6 Commands to control locomotive dE=coders KamEngGetSpeed KamEngPutSpeed KamEngGetSpeedSteps KamEngPutSpeedSteps KamEngGetFunction KamEngPutFunction KamEngGetFunctionMax KamEngGetName KamEngPutName KamEngGetFunctionName KamEngPutFunctionName KamEngGetConsistMax KamEngPutConsistParent KamEngPutConsistChild KamEngPutConsistRemoveObj 3.7 Commands to control accessory decoders KamAccGetFunction KamAccGetFunctionAll KamAccPutFunction KamAccPutFunctionAll KamAccGetFunctionMax KamAccGetName KamAccPutName KamAccGetFunctionName KamAccPutFunctionName KamAccRegFeedback KamAccRegFeedbackAll KamAccDelFeedback KamAccDelFeedbackAll 3.8 Commands to control the command station KamOprPutTurnOnStation KamOprPutStartStation KamOprPutClearStatian KamOprPutStopStation KamOprPutPowerOn KamOprPutPowerOff KamOprPutHardReset KamOprPutEmergencyStop KamOprGetStationStatus 3.9 Commands to configure the command station communication port KamPortPutConfig KamPortGetConfig KamPortGetName KamPortPutMapController KamPortGetMaxLogPorts KamPortGetMaxPhysical 3.10 Commands that control command flow to the command station KamCmdConnect KamCmdDisConnect KamCmdCommand 3.11 Cab Control Commands KamCabGetMessage KamCabPutMessage KamCabGetCabAddr KamCabPutAddrToCab 3.12 Miscellaneous Commands KamMiscGetErrorMsg KamMiscGetClockTime KamMiscPutClockTime KamMiscGetInterfaceVersion KamMiscSaveData KamMiscGetControllerName WO 99!66999 PCTIUS99/14229 KamMiscGetControllerNameAtPort KamMiscGetCommandStationValue KamMiscSetCommandStationValue KamMiscGetCommandStationlndex KamMiscMaxControllerID
KamMiscGetControllerFacility I. OVERVIEW
is This document is divided into two sections, the Tutorial, and the~IDL Command Reference. The tutorial shows the complete code for a simple Visual BASIC program that controls all the major functions of a locomotive.
This program makes use of many of the commands described in the reference section. The IDL Command Reference describes each command in detail.
I. TUTORIAL
A. Visual BASIC Throttle Example Application The following application is created using the Visual BASIC source code in the next section. It controls all major locomotive functions such as speed, direction, and auxiliary functions.
A. Visual BASIC Throttle Example Source Code ' Copyright 1.998, KAM Industries. A:11 rights reserved.
This is a demonstration program showing the ' integration of VisualBasic and 'train Server(tm) ' interface. You may use this application for non ' commercial usage.
'$Date: $
'$Author: $
'$Revision: $
'$Log: $
' Engine Commander, Computer Dispatcher, Train Server, ' Train Tools, The Conductor and lcamind are registered ' Trademarks of KAM Tndustries. All rights reserved.
' This first command adds the reference to the Train ' ServerT Interface object Dim EngCmd As New EngComIfc ' Engine Commander uses the term 3?orts, Devices and ' Controllers ' Ports -> These are logical id:~ where Decoders are assigned to. Train ServerT Interface supports a ' limited number of logical ports.. You can also think ' of ports as mapping to a command station type. This ' allows you to move decoders between command station ' without losing any information a~,bout the decoder Devices -> These are communications channels ' configured in your computer.
' You may have a single device (c:oml) or multiple ' devices ' (COM 1 - COM8, LPT1, Other). You are required to ' map a port to a device to access, a command station.
' Devices start from ID 0 -> max i.d (FYI; devices do ' not necessarily have to be serial channel. Always ' check the name of the device before you use it as ' well as the maximum number of devices supported.
' The Command ' EngCmd.KamPortGetMaxPhysical(lMa.xPhysical, lSerial, ' lParallel) provides means that... lMaxPhysical =
' lSerial + lParaliel + lOther Controller - These are command the command station ' like LENZ, Digitrax ' Northcoast, EasyDCC, Marklin.>. It is recommend ' that you check the command station ID before you ' use it.
Errors - All commands return an error status. If ' the error value is non zero, then the ' other return arguments are invalid. In ' general, non zero errors means command was ' not executed. To get the error message;
' you need to call KamMiscErrorMessage and ' supply the error number To Operate your layout you will need to perform a ' mapping between a Part (logical reference), Device ' (physical communications channel) and a Controller ' (command station) for the program to work. All ' references uses the logical device as the reference ' device for access.
Addresses used are an object reference. To use an ' address you must add the address to the command ' station using KamDecoderPutAdd ... One of the return ' values from this operation is an object reference ' that is used for control.
' We need certain variables as global objects; since ' the information is being used multiple times Dim iLogicalPort, iController, iComPort Dim iPortRate,~iPortParity, iPortStop, iPortRetrans, iPortWatchdog, iPortFlow, iPortData Dim lEngine0bject As Long, iDecoderClass As Integer, iDecoderType As Integer Dim lMaxController As Long Dim lMaxLogical As Long, lMaxPhysical As Long, lMaxSerial As Long, lMaxParallel As Long ~********************************

'Form load function '- Turn of the initial buttons '- Set he interface information ~********************************
Private Sub Form_load{) Dim strVer As String, strCom As String, strCntrl As String Dim iError As Integer 'Get the interface version infoimation SetButtonState {False) iError = EngCmd.KamMiscGetlnteri:aceVersion(strVer) If ( iError) Then 15 MsgBox (("Train Server not loaded. Check DCOM-95")) -iLogicalPort = 0 LogPort.Caption = iLogicalPort ComPort.Caption = "???"

20 Controller. Caption = "Unknown"

Else MsgBox (("Simulation(COM1) Train Server -- " &

strVer) ) **************************************

'Configuration information; Only need to change these values to use a different controller...

************************~:*************

' UNKNOWN 0 // Unknown control type ' SIMULAT 1 // Interface simulator ' LENZ ix 2 // Lenz.sE:rial support module ~

' LENZ
2x 3 // Lenz serial support module ' DIGIT'DT200 4 // Digitrax direct drive support using DT200 ' DIGIT-DCS100~. 5 // Digit:rax direct drive support using DCS100 ' MASTERSERIES 6 // North Coast engineering master Series ' SYSTEMONE 7 // System One ' RAMFIX 8 // RAMFI:xx system ' DYNATROL 9 // Dynat:rol system ' Northcoast binary 10 //' North Coast binary ' SERIAL 11 // NMRA Serial interface ' EASYDCC 12 // NMRA Serial interface ' MRK6050 13 // 6050 Marklin interface (AC and DC) ' MRK6023 14 // 6023 Marklin hybrid interface (AC) ' ZTC 15 // ZTC ~~ystems ltd ' DIGIT-PR1 16 // Digit:rax direct drive support using PR1 ' DIRECT 17 // Directs drive interface rc>ut ine ~************************************~**************~*****

iLogicalPort = 1 'Select Logical port 1 for communications iController = 1 'Select controller from the list above.
iComPort = 0 ' use COM1; O means coml (Digitrax must use Com1 or Com2) 'Digitrax Baud rate requires 16.4K!
'Most COM ports above Com2 do not 'support 16.4K. Check with the °manufacture of your smart com card 'for the baud rate. Keep in mind that 'Dumb com cards with seria:L port 'support Com1 - Com4 can only support '2 com ports (like coml/com2 'or com3/com4) 'If you change the control:Ler, do not 'forget to change the baud rate to 'match the command station. See your 'user manual for details '***********************************~e****. ****************
' 0: // Baud rate is 300 ' 1: // Baud rate is 1200 ' 2: // Baud rate is 2400 ' 3: // Baud rate is 4800 ' 4: // Baud rate is 9600 ' S: // Baud rate is 14.4 ' 6: // Baud rate is 16.4 ' 7: // Baud rate is 19.2 iPortRate = 4 ' Parity values 0-4 -> no, odd, even, mark, space iPortParity = 0 ' Stop bits 0,1,2 -> 1, 1.5, 2 iPortStop = 0 iPortRetrans = 10 iPortWatchdog = 2048 iPortFlow = 0 ' Data bits 0 - > 7 Bits:, 1-> 8 bits iPortData = 1 'Display the port and controllE:r information iError = EngCmd.KamPortGetMaxLoc~Ports(lMaxLogical) iError = EngCmd.KamPortGetMaxPhysical(lMaxPhysical, lMaxSerial, IMaxParalle:l) ' Get the port name and do some checking...
iError = EngCmd.KamPortGetName(i.ComPort, strCom) SetError (iError) If (iComPort > lMaxSerial) Then MsgBox ('!Com port our of range") iError =
EngCmd.KamMiscGetControllerName(iController, strCntrl) WO 99!66999 PCT/US99114229 If (.iLogicalPort > lMaxLogical) Then MsgBox ("Logical port out of range') SetError {iError) End If 'Display values in Throttle..
LogPort.Caption = iLogicalPort CornPort.Caption = strCom Controller. Caption = strCntrl End Sub ******************************
'Send Command 'Note:
' Please follow the command order. Order is important ' for the application to work!
~******************************
Private Sub Command Click(}
'Send the command from the interface to the command station, use the engine0bject Dim iError, iSpeed As Integer If Nat Connect. Enabled Then 'TrainTools interface is a caching interface.
'This means that you need to set up the CV's or 'other operations first; then execute the 'command.
iSpeed = Speed. Text iError =
EngCmd.KamEngPutFunction(lEngineObject, 0, FO. Value) iError =
EngCmd.KamEngPutFunction(lEngineObject, 1, Fl. Value) iError =
EngCmd.KamEngPutFunction(lEngineObject, 2, F2.Value) iError =
EngCmd.KamEngPutFunction(IEngineObject, 3, F3.Value) iError = EngCmd.KamEngPutspeed(lEngineObject, iSpeed, Direction. Value) If iError = 0 Then iError =
EngCmd.KamCmdCommand(lEngineObject) SetError (iErrar) End If End Sub ~******************************
'Connect Controller ~******************************
Private Sub Connect_Click(}
Dim iError As Integer 'These are the index values for setting up the port for use PORT_RETRANS 0 // Retrans index ' PORT_RATE 1 // Retrans index PORT_PARITY 2 // Retrans index ' PORT,STOP 3 // Retraos index ' PORT_WATCHDOG 4 // Retrans index PORT_FLOW 5 // Retrans index ' PORT_DATABITS 6 // Retrans index ' PORT_DEBUG 7 // Retrans index ' PORT_PARALLEL 8 // .Retrans index 'These are the index value:a for setting u p the port for use PORT_RETRANS 0 // Retrans index PORT-RATE 1 // Retrans index PORT PARITY 2 // Retrar~s index Z5 ' PORT STOP 3 // Retrans index ' PORT~WATCHDOG 4 // Retrans index PORT FLOW . 5 // Retrans index ' PORT~DATABITS 6 // Retrans index ' PORT_DEBUG 7 // Retrans index 20 ' PORT_PARALLEL 8 // Retrans index iError = EngCmd.KamPortPutConfic~(iLogicalPort, 0 , iPortRetrans, O) ' setting PORT
RETRANS

_ 1 iError = EngCmd.KamPortPutConfic~(iLogicalRort, , iPortRate, O) ' setting POF;T RATE

25 iError = EngCmd.KamPortPutCanfig~(iLogicalPort, 2 , iPortParity, 0) ' setting F~ORT
PARITY

_ 3 iError = EngCmd.KamPortPutCanfig~(iLogicalPort, , iPortStop, 0) ' setting PORT STOP

iError = EngCmd.KamPortPutConfig~(iLogicalPort, 4 , 30 iPortWatchdog, 0) ' setting' PORT WATCHDOG

iError = EngCmd.KamPortPutConfig~(iLogi.calPort, 5 , iPortFlaw, 0) ' setting PORT FLOW

iError = EngCmd.KamPortPutConfig(iLogicalPort, 6 , iPortData, 0) ' setting PORT DATABITS

We need to set the appropriate debug mode far display.
.

' this command can only be sent if the following is true ' -Controller is not connected . ' -port has not been mapped 40 ' -Not share ware version of application (Shareware ' always set to 130) ' Write Display Log Debug File Win Level Value ' 1 + 2 + 4 - 7 -> LEVEL1 -- put packets into 45 ' queues ' Z + 2 + 8 - 11 -> LEVEL2 -- Status messages ' send to window ' I + 2 + 16 - 19 -> LEVEL3 --1 + 2 + 32 - 35 -> LEVEL4 -- All system 50 ' semaphores/critical sections ' 1 + 2 + 64 - 67 -> LEVELS -- detailed debugging information ' 1 + 2 + 228 - '131 -> COMMONLY -- Read comm write ' camm ports 55 ' 'You probably only want to use values of 130. This will 'give you a display what is read or written to the 'controller. If you want to write the information to 'disk, use 131. The other information is not valid for 'end users.
' Note: 1. ~ This does effect the performance of you ' system: 130 is a save value for debug ' display. Always set the key to 1, a value ' ~ of 0 will disable debug ' 2. The Digitrax control codes displayed are ' encrypted. The information that you ' determine. from the control codes is that ' information is sent (S)' and a response is ° received (R) iDebugMode = 130 iValue = Value: Text' Display value fo:r reference iError = EngCmd.KamPortPutConfig(iLogicalPort., 7, iDebug, iValue)' setting PORT DEBUG
'Now map the Logical Port, Physical device, Command station.and Controller .
iError = EngCmd.KamPortPutMapControll~~r(iLogicalPort, ~iController, iComPort) iError = EngCmd.KamCmdConnect(iLogica:lPort) iError = EngCmd.KamOprPutTurnOnStation(iLogicalPort) If (iError) Then SetButtonState (False) Else SetButtonState (True) End If SetError (iError) 'Displays the error massage and error number End Sub ******************************
'Set the address button ~******************************
Private Sub DCCAddr_Click() Dim iAddr, iStatus As Integer ' All addresses must be match to a logical port to operate iDecoderType = 1 ' Set the decoder type to an NMRA
baseline decoder ( 1 - 8 reg) iDecoderClass = 1 ' Set the decoder class to Engine decoder (there are only two classes of decoders;
Engine and Accessory 'Once we make a connection, we u:~e the lEngineObject 'as the reference object to send control information If (Address. Text > 1) Then iStatus = EngCmd.KamDecoder~?utAdd(Address.Text, iLogicalPort, iLogical~?ort, 0, iDecoderType, lEngineObject) SetError (iStatus) WO 99!66999 PCTlUS99/14229 If(lEngineObject) Then Command. Enabled = True 'tu:rn on the control (send) button Throttle. Enabled = True ' Turn on the throttle 5 Else MsgBox ("Address not set, check error message") End If Else MsgBox ("Address must be greater then 0 and 10 less then 128"}
End If End Sub 15 ~*******************
'Disconenct button ~*******************
Private Sub Disconnect_Click(}
Dim iError As Integer 20 iError = EngCmd.KamCmdDisConnect:(iLogicalPort) SetError (iErrbr) SetButtonState (False) End Sub ~**********************
25 'Display error message ~******~***************
Private Sub SetError(iError As IntegE~r) Dim.szError As String Dim iStatus ' This shows how to retrieve a :aample error message from the interface for the status received.
iStatus = EngCmd.KamMiscGetErrorMsg(iError, szError) ErrorMsg.Caption = szError Result. Caption = Str(iStatus) End Sub ~**************************
'Set the Form button state ~**************************
Private Sub SetButtonState(iState As Boolean) 'We set the state of the button;; either connected' or disconnected If (iState) Then Connect. Enabled = Folse Disconnect. Enabled = True ONCmd.Enabled = True OffCmd.Enabled = True DCCAddr.Enabled = True UpDownAddress.Enabled = True 'Now we check to see if the Engine Address has been 'set; if it has we enable the send button If (lEngineObject > 0) Then Command. Enabled = True Throttle. Enabled = True Else Command. Enabled = False Throttle. Enabled = False End If Else Connect. Enabled = True Disconnect. Enabled = False Command. Enabled = False ONCmd.Enabled = False OffCmd.Enabled = False DGCAddr.Enabled = False UpDownAddress.Enabled = False Throttle. Enabled = False End If I5 End Sub ~*******************
'Power Off function .*******************
Private Sub OffCmd Click() Dim iError As~Integer iError = EngCmd.KamOprPutPowerOff(iLogicalPort) SetError (iError) End Sub ~******************
'Power On function ~******************
Private Sub ONCmd_Click() Dim iError As Integer iError = EngCmd.KamOprPutPowerOn(iLogicalPort) SetError (iError) End Sub ~************************
'Throttle slider control ~************************
Private Sub Throttle_Click() If (lEngineObject) Then If (Throttle. Value > 0) Then Speed. Text = Throttle. Value End If End If End Sub I. IDL COMMAND REFERENCE
A. Introduction This document describes the IDL interface to the KAM Industries Engine Commander ~~'rain Server. The Train Server DCOM server may reside 7_ocally or on a network node This server handles all the background details of controlling your railroad., You write simple, front end programs in a variety of.languages such as BASIC, Java, or C++ to provide the v~~sual interface to the user~while the server handles the=_ details of communicating with the command station, etc.
A. Data Types Data is passed to arid from the IDL interface using a several primitive data types. Array: of these simple types are also used. The exact type passed to and from your program depends on the programming language your are using.
The following primitive data types are used:
IDL Type BASIC Type C++ Type Java Type Description short short short short Shop~t signed integer int int int int Signed integer BSTR BSTR BSTR BSTR Texi: string long long long long Unsigned 32 bit value Name ID CV Rang e Valid CV's Functions Address Range Speed Steps NMRA Compatible 0 None None 2 1-99 14 Baseline 1 1-8 1-8 9 1-127 14 Extended 2 1-106 1-9, 17, 18, 1.<a, 23, 24, 29 , 49, 66-95 9 , 1-10239 ?4,28,128 All Mobile 3 1-106 1-106 9 1--10239 14,28,128 Name ID CV Ra nge Valid CV's Functions Address Range Accessory 4 513-593 513-59.3 8 0-511 All Stationary 5 513-1024 513-1024 8 0-511 A long lDecoderObject/D
value is returned by the KamDecoderPutAd d call if the decoder is successfully registered with the server. This unique opaque XD should be used for all subsequent calls to reference this decoder.

A. Commands to access the server configuration variable database This section describes the commands that access the server configuration variables (c:V~ database. These CVs are stored in the decoder and control many of its characteristics such as its address. For efficiency, a copy of each CV value is also stored in the server database. Commands such as KamCVGetValue and KamCVPutValue communicate only with t:he server, not the actual decoder. You then use the programming commands in the next section to transfer CVs to <ind from the decoder.

OKamCVGetValue Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
iCVRegint 1-1024 2 In CV register pCVValue int * 3 Out Pointer to CV value 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Range is 1~-1'024. Maximum CV for this decoder is given by KamCVGetMaxRegister.
3 CV Value pointed to has a range of 0 to 255.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success., Nonzero is an error number (see KamMiscGetErrorMsg). KamCVGetVa:lue takes the decoder object ID and configuration variable (CV) number as parameters. It sets the memory pointed to by pG'Walue to the value of the server copy of the configuration variable.
OKamCVPutValue Parameter List Type Range Direction Description lDecoderObjectID long 1 In. Decoder object ID
iCVRegint 1-1024 2 In CV' register iCVValue int 0-255 In CV' value 1 Opaque object ID handle returned. by KamDecoderPutAdd.
2 Maximum CV is 1024. Maximum CV for this decoder is given by KamCVGetMaxRegister.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCVPutValue takes the decoder object ID, configuration variable (CV) number, and a new CV value as parameters.
It sets the server copy of the specified decoder CV to iCVtTa I a a .
OKamCVGetEnable Parameter List Type Range Direction Description lDecoderObjectID long 2 In Decoder object ID
iCVRegint 1-1024 2 In CV number pEnable int * 3 Out Pointer to CV bit mask 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum CV is 1024. Maximum CV for this decoder is given by KamCVGetMaxRegister.
3 0x0001 - SET_CV_INTJSE 0x0002 - SET_CV_READ_DIRTY
0x0004 - SET_CV_WRITE DIRTY 0x0008 -SET_CV ERROR_READ
, Ox0010~- SET_CV ERROR_WRITE
Return Value Type ~ Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg). KamCVGetEnable takes the decoder object ID, configuration variable (CV) number, and a pointer to store the enable flag as parameters. It sets the location pointed to by pEnat~le.
OKamCVPutEnable Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object TD
iCVRegint 1-1024 2 In CV number iEnableint 3 In CV bit mask 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum CV is 1024. Maximum CV for this decoder is given by KamCVGetMaxRegister.
3 0x0001 - SET CV_INUSE 0x0002 - SET_CV_READ DIRTY
0x0004 - SET_~CV WRITE~DIRTY O~s:0008 -SET_CV_ERROR_READ
0x0010 - SET_CV ERROR_WRITE
Return Value Type ~ Range Descriptian iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCVPutEnable takes the decoder object ID, configuration variable (CV) number, and a new enable state as parameters. It sets the server copy of the CV bit mask to iEnab.Ie.
' OKamCVGetName Parameter List Type Range Direction Description iCV int 1-1024 In CV number pbsCVNameString BSTR * 1 Out Pointer to CV
name string 1 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description iError short 1 Error flag 1 .iError = 0 for success. Nonzero is an error number {see KamMiscGetErrorMsg).
KamCVGetName takes a configuration variable (CV) number as a parameter. It sets the memory pointed to by pbsCVNameString to the name of the CV as defined in NMRA
Recommended Practice RP 9.2.2.
OKamCVGetMinRegister Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
pMinRegister int * 2 Out Pointer to min CV
register number 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Normally 1-1024. 0 on error or if decoder does not support CVs.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).

KamCVGetMinRegister takes a decoder object ID as a parameter. It sets the memory pointed to by pMinRegister to the minimum possible CV register number for the specified decoder.

OKamCVGetMaxRegister Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
pMaxRegister int * 2 Out Pointer to max CV
10 register number 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Normally 1-1024. 0 on error or if decoder does not support CVs.
15 Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCVGetMaxRegister takes a decoder object ID as a 20 parameter. It sets the memory pointE:d to by pMaxRegister to the-maximum possible CV register number for the specified decoder.
25 A. Commands to program configuration variables This section describes the commands read and write decoder configuration variables (CVs). You should initially transfer a copy of the decoder CVs to the 30 server using the KamProgramReadDecode:rToDataBase command.
You can then read and modify this server copy of the CVs.
Finally, you can program one or more CVs into the decoder using the KamProgramCV or KamProgramL>ecoderFromDataBase commandt. Not that you must first enter programming mode by issuing the KamProgram command before any programming can be done.
OKamProgram Parameter List Type Range Di.recti.on Description lDecoderObjectID long 1 In Decoder abject ID
iProgLogPort int 1-65535 2 In Logical programming port ID
iProgMode int 3 In Programming mode 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum value for this server given by KamPortGetMaxLogPorts.
3 0 - PROGRAM_MODE_NONE
Z - PROGRAM_MODE_ADDRESS
2 - PROGRAM_MODE_REGISTER
3 - PROGRAM_MODE PAGE

4 - PROGRAM_MODE_~DIRECT

5 - DCODE_PRGMODE_OPS_SHOF:T

Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamProgram take the decoder object I:D, logical programming port ID, and programmingr mode as parameters.
It changes the command station mode fr~m normal operation (PROGRAM MODE NONE) to the specified: programming mode.
Once in programming modes, any number of programming commands may be called. When done, you must call KamProgram with a parameter of PROGR;AM_MODE NONE to return to normal operation. ~ .
OKamProgramGetMode Parameter List Type Range Direction Description lDecoderObjectlD long 1 I:n Decoder object ID
iProgLo,gPort int 1-65535 2 In Logical programming port ID
piProgMode int * 3 Out F~rogramming mode 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum value for this server given by KamPortGetMaxLogPorts.
3 0 - PROGRAM_MODE NONE
1 - PROGRAM_MODE~ADDRESS
2 - PROGRAM_MODE'REGISTER.
3 - PROGRAM_MODE~_PAGE
4 - PROGRAM_MODE_DIRECT
5 - DCODE_PRGMODE_OPS_SHO~RT
6 PROGRAM_MODE_OPS_LONf~
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 far success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamProgramGetMode take the decoder object ID, logical programming port ID, and pointer t.o a place to store the programming mode as parameters. It sets the memory pointed to by piProgMode to the present programming mode.
OKamProgramGetStatus Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
iCVRegint 0-1024 2 In CV number piCVAllStatus int * 3 Out Or'd decoder programming status 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 0 returns OR'd value for all CV's. Other values return status for just that CV.
3 0x0001 - SET_CV_INUSE
0x0002 - SET_CV READ_DIRTY
0x0004 - SET CV~_WRITE_DIRTY
0x0008 - SET_~CV ERROR READ
0x0010 - SET CV~ERROR~WRITE

Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamProgramGetStatus take the decoder' object ID and pointer to a place to store the ~R'd. decoder programming status as parameters. It sets the m~.emory pointed to by piProgMode to the present programming mode.
OKamProgramReadCV
Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID

iCVRegint 2 In CV number 1 Opaque object ID handle returned by 25 KamDecoderPutAdd.

2 Maximum CV is 1024. Maximum CV for this decoder. is given by KamCVGetMaxRegister.

Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).

KamProgramCV takes the decoder object ID , configuration variable (CV) number as parameters. It reads the specified CV variable value to the serve r database.

OKamProgramCV

Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID

iCVRegint 2 In CV number iCWalue int 0-255 In CV va lue 1 Opaque object ID handle returned by KamDecoderPutAdd.

2 Maximum CV is 1024. Maximum CV for this decoder is given by KamCVGetMaxRegister.

Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).

KamProgramCV takes the decoder object ID , configuration variable (CV) number, and a new CV value as parameters.

It programs (writes) a single decoder CV using the specified value as source data.

OKamProgramReadDecoderToDataBase Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID

1 Opaque object TD handle returned by KamDecoderPutAdd.

Return Value Type Range Description iError short . 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).

KamProgramReadDecoderToDataBase takes th e decoder object ID as a parameter. It reads all enabled CV values from the decoder and stores them in the serve r database.

OKamProgramDecoderFromDataBase Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
1 Opaque object ID handle returned by KamDecaderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzer~o is an error number (see KamMiscGetErrorMsg).
i0 KamProgramDecoderFromDataBase takes 'the decoder object ID
as a parameter. It programs (writes) all enabled decoder CV values using the server copy of the CVs as source data.
A. Commands to control all decoder types This section~describes the commands that all decoder types. These commands do things such getting the maximum address a given type of decoder supports, adding decoders to the database, etc.
OKamDecoderGetMaxModels Parameter List Type Range Direction Description piMaxModels int * I Out Pointer to Max model ID
1 Normally 1-65535. 0 bn error.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetMaxModels takes no parameters. It sets the memory pointed to by piMaxModels to t:he maximum decoder type ID.
OKamDecoderGetModelName Parameter List Type Range Direction Description iModel int 1-65535 1 In Decoder type ID
pbsModelName BSTR * 2 Out Decoder name string 1 Maximum value for this server given by KamDecoderGetMaxModels.
2 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description iError short 1 Error flag 1 .iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg). KamPortGet:ModelName takes a decoder type ID and a painter to a string as parameters.
It sets the memory pointed to by pbsNfodelName to a BSTR
containing the decoder name.

OKamDecoderSetModelToObj Parameter List Type Range Direction Description iModel int 1 In Decoder model ID
lDecoderObjectlD long 1 Iii Decoder object ID
1 Maximum value for this server given by KamDecoderGetMaxModels.
2 Opaque object ID handle returned by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderSetModelToObj takes a decoder ID and decoder object ID as parameters. It sets t:he decoder model type of. the decoder at address IDecoderO.bjectlD to the type specified by iModel.
OKamDecoderGetMaxAddress Parameter List Type Range Direction Description iModel int 1 In Decoder type ID
piMaxAddress int * 2 Out Maximum decoder address 1 Maximum value far this server .given by KamDecoderGetMaxModels.
2 Model dependent. 0 returned o:n error.
Return Value Type Range Description iError short 1 Error flag 1 .iError = 0 for success. Nonze:ro is an error number (see KamMiscGetErrorMsg).
KamDecoderGetMaxAddress takes a decoder type ID and a pointer to store the maximum address as parameters. ~Tt sets the memory pointed to by piMax?~ddress to the maximum address supported by the specified ~3ecoder.
OKamDecoderChangeOldNewAddr Parameter List Type Range Direction Description lOldObjID long 1 In Old decoder object ID
iNewAddr int 2 In Mew decoder address plNewObjID long * 1 Out Mew decoder object ID
1 Opaque object ID handle returned by KamDecoderPutAdd.
2 1-127 for short locomotive addresses. 1-1.0239 for long locomotive decoders. 0-511 fo:r accessory decoders.
Return Value Type Range Description iError short 1 Error flag 1 zError = 0 for success. Nonze:ro is an errar number (see KamMiscGetErrorMsg).
KamDecoderChange0ldNewAddr takes an old decoder object TD
and a new decoder address as parameters. It moves the specified locomotive or accessory decoder to iNewAddr and sets the memory pointed to by plNewt~bjlD to the new object ID. The old object ID is nova invalid and should no longer be used.

OKamDecoderMavePort~
Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
iLogicalPortID int 1-65535 2 In 7Logical port ID
5 1 Opaque object ID handle returncad by KamDecoderPutAdd. .
2 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description 10 iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderMovePort takes a decoder object ID and logical port ID as parameters. It moves the decoder specified by 15 lDecoderUbjectlD to the controller :specified by iLogica.IPortID.
OKamDecoderGetPort Parameter List Type Range Direction Description 20 lDecoderObjectID long 1 7.n Decoder object ID
piLogicalPortID int * 1-65535 2 Out Pointer to logical port ID
1 Opaque object ID handle returnE~d by KamDecoderPutAdd.
25 2 Maximum value for this server.given by KamPortGetMaxLogPorts. ' Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number 30 (see KamMiscGetErrorMsg).
KamDecoderMovePort takes a decoder object ID and pointer to a logical port ID as parameters. It sets the memory pointed to by piLogica.IPortID to they logical port ID
associated with IDecoderObjectlD.
OKamDecoderCheckAddrInUse Parameter List Type Range Direct;ion Description iDecoderAddress int 1 I:n Decoder address iLogicalPortID int 2 In Logical Port ID
iDecoderClass int 3 In Class of decoder 1 Opaque object ID handle returned by KamDecoderPutAdd.
. 2 Maximum value for this server given by KamPortGetMaxLogPorts.
3 1 - DECODER_ENGINE_TYPE, 2 - DECODER_SWITCH TYPE, 3 DECODER_SENSOR~TYPE.
Return Value Type ~ Range Description iError short 1 Error flag 1 iError = 0 for successful call and address not in use. Nonzero is an error number (se.e KamMiscGetErrorMsg). IDS_ERR-ADDRESSEXIST returned if call succeeded but the address exists.
KamDecoderCheckAddrInUse takes a decoder address, logical port, and decoder class as parameters. It returns zero WO 99!66999 PCT/US99/14229 if the address is not in use. It wi:Ll return IDS ERR ADDRESSEXTST if the call succeeds but the address already exists. It will return the appropriate non zero error number if the calls fails.
OKamDecoderGetModelFromObj Parameter List Type Range Direction Description lDecoderObjectlD long, 1 In Decoder object ID
piModelint * 1-65535 2 Out Pointer to decoder . type It7 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum value for this server given by KamDecaderGetMaxModels.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetModelFromObj takes a de<:oder object ID and pointer to a decoder type ID as parameters. It sets the memory pointed to by piModel to the dect~der type ID
associated with iDCCAddr.
OKamDecoderGetModelFacility Parameter List Type Range Direct_Lon Description lDecoderObjectlD long 1 II1 Decoder object ID
pdwFacility long * 2 Out Pointer to decoder facility mask 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 0 - DCODE_PRGMODE_ADDR
1 - DCODE_PRGMODE_REG
2 - DCODE_PRGMODE PAGE
3 - DCODE_PRGMODE~_DIR
4 - DCODE_PRGMODE FLYSHT
5 - DCODE_PR~MODE~_FLYLNG
6 - Reserved 7 - Reserved 8 - Reserved 9 - Reserved 10 - Reserved 11 - Reserved 12 - Reserved 13 - DCODE FEAT_DIRLIGHT

14 - DCODE~_FEAT_LNGADDR

15 - DCODE_FEAT_CVENABLE

17 - DCODE~_FEDMODET_REG

18 - DCODE_FEDMODE PAGE

19 - DCODE_FEDMODE~_DIR

20 - DCODE_FEDMODE_FLYSHT

Return Value Type Range Description iError short 1' Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetModelFacility takes a decoder object ID and pointer to a decoder facility mask a;s parameters. It sets the memory painted to by pdwFac.ility to the decoder facility mask associated with iDCCAdnr.
OKamDecoderGetObjCount Parameter List Type Range Direction Description iDecoderClass int 1 In Class of decader piObjCount int * 0-65535 Out Count of active decoders Z5 1 1 - DECODER_ENGINE_TYPE, 2 - DECODER SWITCH_TYPE, 3 - DECODER_~SENSOR TYPE.
Return Value Type r Range Description~
iError short 1 Error flag I iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetObjCount takes a decoder class and a pointer to an address count as parameters. 7=t sets the memory pointed to by piObjCount to the count: of active decoders of the type given by iDecoderC.Iass.
OKamDecoderGetObjAtIndex Parameter List Type Range Direction Description~
iIndex int 1 In Decoder array index iDecoderClass int 2 In Class of decoder plDecoderObjectlD long * 3 Out Pointer to decoder o~>ject TD
1 0 to (KamDecoderGetAddressCount - 1).
2 1 - DECODER_ENGINE_TYPE, 2 - DECODER SWITCH_TYPE, 3 - DECODERV_SENSOR TYPE.
3 Opaque object ID handle returnef, by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg):
KamDecoderGetObjCount takes a decader index, decoder class, and a pointer to an object ID as parameters. It sets the memory pointed to by plDecoderObjectlD to the selected object ID.
OKamDecoderPutAdd Parameter List Type Range Direction Description iDeeoderAddress int 2 In Decoder address iLogicalCmdPortID int 1-65535 2 In Logical command port ID

iLogicalProgPortID int 1-65535 2 In Logical programming port ID
iClearState int 3 In ~ CaLear state flag iModel int 4 In DE:coder model type ID
plDecoderObjectlD long * 5 Out Decoder obj ect ID
1 1-127 for short locomotive addrEases. 1-10239 for long locomotive decoders. 0-511 for accessory decoders.
2 Maximum value for this server g9.ven ~by KamPortGetMaxLogPorts.
3 0 - retain state, 1 - clear stage.
4 Maximum .value~for this server given by KamDecoderGetMaxModels.
5 Opaque object ID handle. The ok~ject ID is used to reference the decoder.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderPutAdd takes a decoder objs:ct ID, command logical part, programming logical point, clear flag, decoder model ID, and a pointer to a decoder object ID as parameters. It creates a new locomotive object in the locomotive database and sets the memory pointed to by plDecoderObjectlD to the decoder object ID used by the server as a key.
OKamDecoderPutDel Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
iClearState int 2 In Clear state flag 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 0 - retain state, 7. - clear stage.
Return Value Type Range Description~
iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderPutDel takes a decoder object ID and clear flag as parameters. Tt deletes the locomotive object specified by lDecoderObjectlD from the locomotive database.
OKamDecoderGetMfgName Parameter List Type Range Direction Description lDecoderObjectID long 1 Tn, Decoder object ID
pbsMfgName BSTR * 2 Out Pointer to manufacturer name 1 Opaque object ID handle returned. by KamDecoderPutAdd.
2 Exact return type depends on language. It is Cstring * for C++. Empty string on error.

Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetMfgName takes a decoder object ID and pointer to a manufacturer name string as parameters. It sets the memory pointed to by pbsMfgrJ'ame to the name of the decoder manufacturer.
OKamDecoderGetPowerMode Parameter List Type Range Direct~L~on Description lDecoderObjectlD long 1 In Decoder object ID
pbsPowerMode BSTR * 2 Out Pointer to decoder power mode 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact returm type depends on language. It is Cstring * for C++. Empty string on s:rror.
Return Value Type Range Description~
iError short 1 Error flag.
1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetPowerMode takes a decodE:r object ID and a pointer to the power mode string as parameters. It sets the memory pointed to by pbsPowerMode~ to the decoder power mode.
OKamDecoderGetMaxSpeed Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
piSpeedStep int * 2 Out Pointer to max speed step 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 14, 28, 56, or 128 for locomotive decoders. 0 for accessory decoders.
Return~Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamDecoderGetMaxSpeed takes a decodes- object ID and a pointer to the maximum supported speEad step as parameters. It_sets the memory pointed to by piSpeedStep to the maximum speed step supported by the decoder.
A. Commands to control locomotive decoders This section describes the commands that control locomotive decoders. These commands control things such as locomotive speed and direction. For efficiency, a copy of all the engine variables such speed is stored in the server. Commands such as KamEngGetSpeed communicate only with the server, not, the actual decoder.

You should first make any changes to the server copy of the engine variables. You can send. alI changes to the engine using the KamCmdCommand command.
5 OKamEngGetSpeed Parameter List Type Range Direction Description lDecode~ObjectlD long 1 In Decoder object ID
lpspeed int * 2 Out Pointer to locomotive speed 10 lpDirection int * 3 Out Pointer to locomotive direction 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Speed range is dependent on whether the decoder is 15 set to 14,18, or 128 speed steps and matches the values defined by NMRA S9.2 and RP 9.2.1. 0 is stop and 1 is emergency stop for all modes.
3 Forward is boolean TRUE and. reverse is boolean FALSE.
20 Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number {see KamMiscGetErrorMsg).
KamEngGetSpeed takes the decoder object ID arid pointers 25 to locations to store the locomotive speed and direction as parameters. It sets the memory pointed to by lpSpeed to the locomotive speed and the memory pointed to by lpDirection to the locomotive direction.
30 OKamEngPutSpeed Parameter List Type Range Direction Description~
IDecoderObjectID long 1 In Decoder object ID
iSpeed int 2 In Locomotive speed iDirection int 3 In Locomotive direction 35 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Speed range is dependent on whether the decoder is set to 14,18, or 128 speed steps and matches the values defined by NMRA S9.2 and RP 9.2.1. 0 is stop and 1 is 40 emergency stop for all modes.
3 Forward is Boolean TRUE and reverse is Boolean FALSE.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzer~o is an error number (see KamMiscGetErrorMsg).
KamEngPutSpeed takes .the decoder object ID, new locomotive speed, and new locomotive direction as parameters. It sets the locomotive database speed to iSpeed and the locomotive database direction to iDirection. Note: This command only changes the locomotive database. The data is not sent to the decoder until execution of the KamCmdCommand command. Speed is set to the maximum possible for the decoder if iSpeed exceeds the decoders range.

OKamEngGetSpeedSteps Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
lpSpeedSteps int * 14,28,128 Out Pointer to number of speed steps 1 Opaque object ID handle returnecl by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamEngGetSpeedSteps takes the decoder. object TD and a pointer to a location to store the number of speed steps as a parameter. It sets the memory ~>ointed to by lpSpeedSteps to the number of speed ateps.
OKamEngPutSpeedSteps Parameter List Type Range Direct~.an Description lDecoderObjectID long 1 In Decoder object ID
iSpeedSteps int 14,28,128 In Locomotive speed steps 1 Opaque object ID handle returned by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg)..
. KamEngPutSpeedSteps takes the decoder object ID and a new number of speed steps as a parameter. It sets the number of speed steps in the locomotive dat2~base to .iSpeedSteps.
Note: This command only changes the locomotive database.
The data is not sent to the decoder until execution of the KamCmdCommand command. KamDecodE:rGetMaxSpeed returns the maximum possible speed for the decoder. An error is generated if an attempt is made to set the speed steps beyond this value.
OKamEngGetFunction Parameter List Type Range Direction Description lDecoderObjectID long 1 Tn Decoder object ID
iFunctionID int 0-8 2 In Function ID number lpFunction int * 3 Out Painter to function value 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 FL is 0. F1-F8 are 1-8 respectively. Maximum for this decoder is given by KamEngGetFunctionMax. 3 Function active is Boolean TRUE and 5.nactive is Boolean FALSE.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzera is an error number (see KamMiscGetErrorMsg).
KamEngGetFunction takes the decoder object ID, a function ID, and a painter to the location to store the specified function~state as parameters. It seta the memory pointed to.by lpFuncfion to the specified function state.
OKamEngPutFunction Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
iFunctionID ~int 0-8 2 In Function ID number iFunction int 3 In Function value 1 Opaque object ID handle returned! by KamDecoderPutAdd.
2 FL is 0. F1-F8 are 1-8 respectively. Maximum for this decoder is given by KamEngGetFuncti.onMax.
3 Function active is boolean TRUE and inactive is boolean FALSE.
Return Value Type Range Description~
iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamEngPutFunction takes the decoder object ID, a function ID, and a new function state as parameters. It sets the specified locomotive database function state to iFunction. Note: This command only changes the locomotive database. The data is not sent to the decoder until execution of the KamCmdCommand command.
OKamEngGetFunctionMax Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
piMaxFunction int * 0-8 Out Pointer to maximum function number 1 Opaque object.ID handle returned by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamEngGetFunctionMax takes a decoder object ID and a pointer to the maximum function ID as parameters. It sets the memory pointed to by piMaxFunction to the maximum possible function number for the specified decoder.
OKamEngGetName Parameter List Type Range Direction Description lDecoderObjectID , long 1 In Decoder object ID
pbsEngName BSTR * 2 Out Pointer to locomotive name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact return type depends on language. It is Cstring * for C++.' Empty string on error.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrarMsg).

WO 99/bb999 PCTIUS99/14229 KamEngGetName takes a decoder object ID and a pointer to the locomotive name as parameters. It sets the memory pointed to by pbsEngNarrie to the name of the locomotive.
OKamEngPutName Parameter List Type Range Direction Description~
lDecoderObjectlD long 1 In. Decoder object ID
bsEngName BSTR 2 Out Locomotive name 1 Opaque object ID handle returned. by KamDecoderPutAdd.
2 Exact parameter type depends on language. It is LPCSTR for C++.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero~ is an error number (see KamMiscGetErrorMsg).
KamEngPutName takes a decoder object ID and a BSTR as parameters. It sets the symbolic locomotive name to bsEngName.
OKamEngGetFunctionName Parameter List Type Range Direction Description lDecoderObjectID long 1 In. Decoder object ID
iFunctionlD int 0-8 2 In Function ID number pbsFcnNameString BSTR * 3 Ou.t Pointer to function name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 FL is 0. F1-F8 are 1-8 respectively. Maximum for this decoder is given by KamEngGetFun.ctionMax. 3 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description iError short 1 Error flag 1 iError~ - 0 for success. Nonzero is an error number (see KamMiscGetErrarMsg).
KamEngGetFuncntionName takes a decoder object ID, function ID, and a pointer to the function name as parameters. It sets the memory pointed to by ' pbsFcnNameString to the symbolic name. of the specified function.
OKamEngPutFunctionName Parameter List Type Range Direction Description lDecoderObjectID long 1 In. Decoder object ID
iFunctionID int 0-8 2 In Function ID number bsFcnNameString BSTR 3 Tn. Function name I Opaque object ID handle returned. by KamDecoderPutAdd.
2 FL is 0. F1-F8 are 1-8 respectively. Maximum for this decoder is given by KamEngGetFun.ctionMax.
3 Exact parameter type depends on language. Tt is LPCSTR for C++.
Return Value Type Range Description iError short 1 Error flag WO 99/b6999 PCTlUS99/14229 4 ~4 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamEngPutFunctionName takes a decode~~ object ID, function ID, and a BSTR as parameters. It sets the specified symbolic 'function name to bsFcnNameSt:ring.
OKamEngGetConsistMax Parameter List Type Range Direction Description lDecoderObjectlD long I In Decoder object ID
piMaxConsist int * 2 Out Pointer to max consist number 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Command station dependent.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamEngGetConsistMax takes the decodex° object ID and a painter to a location to store the maximum consist as parameters. It sets the location pointed to by piMaxConsist: to the maximum number of locomotives that can but placed in a command station controlled consist.
Note that this command is designed for command station consisting. CV consisting is handled using the CV
commands.
OKamEngPutConsistParent Parameter List Type Range Direction Description 1DCCParentObjID long 1 Ire Parent decoder obj ect ID
iDCCAliasAddr int 2 In Alias decoder address 1 Opaque object ID handle returned by .
KamDecoderPutAdd.
2 1-127 for short locomotive addresses. 1-10239 for long locomotive decoders.
Return Value Type . Range Descriptiow iError short 2 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGeaErrorMsg).
KamEngPutCansistParent takes the parent object ID and an alias address as parameters. It makes the decoder specified by IDCCParentObjID the consist parent referred to by iDCCAliasAddr. Note that this command is designed for command station consisting. CV consisting is handled using the CV commands. If a new parent is defined for a consist; the old parent becomes a child in the consist.
To delete a parent in a consist without deleting the consist, you must add a new parent then delete the old parent using KamEngPutConsistRemoveObj.

OKamEngPutConsistChild Parameter List Type Range Direction Description 1DCCParentObjID long 1 ~Cn Parent decoder obj ect ID
5 ~1DCCObjID long 1 In Decoder object~ID
1 Opaque object ID handle returnE~d by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 10 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrbrMsg).
KamEngPutConsistChild takes the decoder parent object ID
and decoder object ID as parameters., It assigns the decoder specified by lDCCObjID to the consist identified 25 by 1DCCParentObjID. Note that this command is designed for command station consisting. CV consisting is handled using the CV commands. Note: This command is invalid if the parent has not been set previou;~ly using KamEngPutConsistParent.
OKamEngPutConsistRemoveObj Parameter List Type Range D.irect:ion Description lDecoderObjectlD Long 1 7.n Decoder object ID
1 Opaque object ID handle returnEad by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Errar flag 1 .iError = 0 for success. Nonzez-o is an error number (see KarnMiscGetErrorMsg).
KamEngPutConsistRemoveObj takes the decoder object TD as a parameter. It removes the decodes- specified by lDecoderObjectlD from the consist. Note that this command is designed for command station consisting. CV
consisting is handled using the CV commands. Note: If the parent is removed, all children are removed also.
A. Commands to control accessory decoders This section describes thE: commands that control accessory decoders. These commands control things such as accessory decoder activation state. For efficiency, a copy of all the enginE: variables such speed is stored in the server. Commands :>uch as KamAccGetFunction communicate only with the server, not the actual decoder. You should first make any changes to the server copy of the engine variax~les. You can send all changes to the engine using the KamCmdCommand command.

OKamAccGetFunction Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
iFunctionID int 0-31 2 In Function ID number lpFunction int * 3 Out Pointer to function value 1 ~ Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum for this decoder is given by~
KamAccGetFunctionMax.
3 Function active is Boolean TRUE and inactive is Boolean FALSE.
Return Value Type ~ Range Description iError short 1 Error flag ,1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamAccGetFunction takes the decoder object ID, a function ID, and a pointer to the location to store the~specified function state as parameters. It sets the memory pointed to by lpFunction to the specified function state.
OKamAccGetFunctionAll Parameter List Type Range Direction Description lDecoderObjectlD long 1 I:n Decoder object ID
piValue int * 2 Out Function bit mask 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Each bi.t represents a single function state.
Maximum for this decoder is given by KamAccGetFunctionMax:
Return Value Type Range Description iError short 2 Error flag 1 iError = 0 for success. Nonzer~o is an error number (see KamMiscGetErrorMsg).
KamAccGetFunctionAll takes the decoder object ID and a pointer to a bit mask as parameters. It sets each bit in the memory pointed to by piVa.Iue to 'the corresponding function state.
OKamAccPutFunction Parameter List Type Range Direction Description lDecoderObjectID long 1 T:n Decoder object ID
iFunctionID int 0-31 2 In Function ID number iFunction int 3 In Function value 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum for this decoder is given by KamAccGetFunctionMax.
3 Function active is Boolean TRUE and inactive is Boolean FALSE.
Return Value Type Range Description-iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).

KamAccPutFunction takes the decoder c>bject ID, a function ID, and a new function state as parameters. It sets the specified accessory database function state to iFunct.ion.
Note: This command only changes the accessory database.
The data is not sent to the decoder until execution of the KamCmdCommand command.
OKamAccPutFunctionAll Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
iValue int 2 In Pointer to function state array.
1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Each bit represents a single function state.
Maximum for this decoder is given by KamAccGetFunctionMax.
Return Value Type Range Description~
iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamAccPutFunctionAll takes the decoder object ID and a bit mask as parameters. It sets all decoder function enable states to match the state bite; in iValue. The possible enable states are TRUE and FALSE. The data is not sent to the decoder until execution of the KamCmdCommand command.
OKamAccGetFunctionMax Parameter List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
piMaxFunction int * 0-31 2 Out Pointer to maximum function number 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum for this decoder is given by KamAccGetFunctionMax.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzerc> is an error number (see KamMiscGetErrorMsg).
KamAccGetFunctionMax takes a decoder object ID and pointer to the maximum function number as parameters. It sets the memory pointed to by piMaxFunct.ion to the maximum possible function number fox the specified decoder.
OKamAccGetName Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
pbsAccNameString BSTR * 2 Out Accessory name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact return type depends on language. It is Cstring * for C+-t-. Empty string on error. .

WO 991bb999 PCT/US99I14229 Return Value Type Range Description iError .short I. Error flag 1 i.Error = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
'S KamAccGetName takes a decoder object ID and a pointer to a string as parameters. It sets the memory pointed to by pbsAccNameString to the name of theaccessory.
OKamAccPutName Parameter List Type Range Direction Description lDecoderObjectID long 1 I:n Decoder object ID
bsAccNameString BSTR 2 I:n Accessory name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact parameter type depends on language. It is LPCSTR far C++.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzer~o is an errar number (see KamMiscGetErrorMsg).
KamAccPutName takes a decoder abject ID and a BSTR as parameters. It sets the symbolic accessory name to bsAccNante .
OKamAccGetFunctionName Parameter List Type Range Direction Description lDecoderObjectlD long ~ 1 In Decoder object ID
iFunctionlD int 0-31 2 In Function ID number pbsFcnNameString BSTR * 3 Out Pointer to function name Z Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum for this decoder is given by KamAccGetFunctionMax.
3 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description~
iError short 1 Error flag 1 .iError = 0 for success. Nonzero is an error number {see KamMiscGetErrorMsg).
KamAccGetFuncntionName takes a decoder object ID, function TD, and a pointer to a string as parameters. It sets the memory pointed to by pbsFcnlVameString to the symbolic name of the specified function.
OKamAccPutFunctionName Parameter List Type Range Direction Description iDecoderObjectlD long 1 In Decoder object ID
iFunctionlD int 0-32 2 In Function TD number bsFenNameString BSTR 3 In Function name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum for this decoder is given by KamAccGetFunctionMax.

3 Exact parameter type depends on language. It is LPCSTR for C++.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamAccPutFunctionName takes a decoder object ID, function ID, and a BSTR as parameters. It sets the specified symbolic function name to bsFcnNameString.
OKamAccRegFeedback Parameter List Type Range Direction Description~
lDecoderobjectlD long 1 In Decoder object ID
bsAccNode BSTR 1 In Server node name iFunctionID int 0-31 3 In Function ID number 1 Opaque abject ID handle returned by KamDecoderPutAdd.
2 Exact parameter type depends oi~ language. It is LPCSTR for C++.
3 Maximum for this decoder is given by KamAccGetFunctionMax.
Return Value Type Range Description iError short 1 Error flag 1 iError~ - 0 for~success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamAccRegFeedback takes a decoder object ID, node name string, and function ID, as parameters. It registers interest in the function given by iFu~nct.ionTD by the method given by the node name string iSsAccNode.
bsAccNode identifies the server application and method to call if the function changes state. :Lts format is "\\{Server}\{App}.{Method}" where {Se:rver} is the server name, {App} is the application name, <~nd (Method} is the method name.
OKamAccRegFeedbackAll Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
bsAccNode BSTR 2 In Server node name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact parameter type depends an .Language. It is LPCSTR for C++.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamAccRegFeedbackAll takes a decoder object ID and node name string as parameters. It registers interest in all functions by the method given by the node name string bsAccNode, bsAccNode identifies the ;server application and method to call if the function ch<~nges.state. Its format is."\\{Server}\{App}.{Method)" where {Server} is the server name, {App} is the application name, and {Method} is the method name.

WO 99/66999 PCTlUS99/14229 OKamAccDelFeedback Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
bsAccNode BSTR 2 In Server node name 5 iFunctionlD int 0-31 3 In Function TD number 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact parameter type depends on language. It is LPCSTR far C++.
10 3 Maximum for this decoder is given lay KamAccGetFunctionMax.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number 15 (see KamMiscGetErrorMsg).
KamAccDelFeedback takes a decoder object ID, node name string, and function ID, as parameters. It deletes interest in the function given by iFunctionlD by the method given by the node name string bsAccNode.
20 bsAccNode identifies the server application and method to call if the function changes state. Its format is "\\{Server}\{App}.{Method}" where {Se.rver} is the server name, (App} is the application name, and {Method} is the method name.
OKamAccDelFeedbackAll Parameter List Type Range Direction Description~
iDecoderObjectlD long 1 In Decoder object ID
bsAccNode BSTR 2 In Server node name 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Exact parameter type depends on language. It is LPCSTR for C-1-+.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamAccDelFeedbackAll takes a decoder object ID and node name string as parameters. It deletes interest in all functions. by the method given by the node name string bsAccNode. bsAccNode identifies the server application and method to call if the function changes state. Its format is "\\(Server}\(App}.{Method}" where {Server} is the server name, {App} is the application name, and {Method} is the method name:
A. Commands to control the command station This section describes the commands that control the command station. These commands do things such as controlling command station power. The steps to control a given command station vary depending on the type of command station.

OKamOprPutTurnOnStation Parameter List Type Range Direction Description i.LogicalPortID int 1-65535 2 In Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 .iError = 0 for success: Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprPutTurnOnStation takes~a logical port ID as a parameter. It performs the steps necessary to turn on the command station. This command pfarforms a combination of other commands such as KamOprPutSt:artStation, KamOprPutClearStation, and KamOprPutPowerOn.
OKamOprPutStartStation Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short I Error flag 1 iError = 0 for success. Nonzerc> is an error number (see KamMiscGetErrorMsg).
KamOprPutStartStation takes a logical. port ID as a parameter. It performs the steps necessary to start the command station.
OKamOprPutClear5tation Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprPutClearStation takes a logical. port ID as a parameter. It performs the steps necessary to clear the command station queue.
OKamOprPutStopStation Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 Tn Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range DEacription iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprPutStopStation takes a logical part ID as a parameter. It performs the steps necessary to stop the command station.

OKamOprPutPowerOn Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 Tn Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprPutPowerOn takes a logical port ID as a parameter.
It performs the steps necessary to apply power to the track.
OKamOprPutPowerOff Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamoprPutPoweroff takes a logical port ID as a parameter.
It performs the steps necessary to remove power from the track.
OKamOprPutHardReset Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
1 Maximum value for this server given by KamPortGetMaXLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprPutHardReset takes a logical port ID as a parameter. It performs the steps necessary to perform a hard reset of the command station.
OKamOprPutEmergencyStop Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprPutEmergencyStop takes a logical port ID as a parameter. It performs.the steps necessary to broadcast an emergency stop command to all decoders.

OKamOprGetStationStatus Parameter List Type Range Direction Description iLogicalPortID int ~1-65535 1 In Logical port ID
pbsCmdStat BSTR * 2 Out Command station status string 1 Maximum value for this server given by KamPortGetMaxLogPorts.
2 Exact return type depends on language. It is Cstring * for C++.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamOprGetStatianStatus takes a logical port ID and a pointer to a string as parameters. It: set the memory pointed to by pbsCmdStat to the command station status.
The exact format of the status BSTR i.s vendor dependent.
A. Commands to configure the cammand station communication port This section describes the commands that con figure the command station communication port. These commands such as setting~BA,UD rate. Several do of things the cammands in thi s section use the numeric controller ID {iControllerlD) to identify a specific type of command troller. The following table shows station con the mapping between the controller ID (iControllerlD) and controller ControllerName) fc~r a given type of name (bs command troller.
station con iControllerID ntrollerName Description bsCo 0 UNKNOWN . Unknown controller type 2 SIMULAT Interface simulator 2 LENZ_lx Lenz version 1 serial support module 3 LENZ_2X Lenz version 2 serial support module 4 DIGIT~DT200 Digitrax direct drive support using 5 DIGIT_DCS100 Digitrax direct drive support using DCS 10 0 .

6 MASTERSERIES North coast engineering master series 7 SYSTEMONE System one 8 RAMFIX RAMFIxx system 9 SERIAL NMRA serial interface 10 EASYDCC CVP Easy DCC

1i MRK6050 Marklin 6050 interface (AC and DC) 12 MRK6023 Marklin 6023 interface (AC) 13 DIGIT_PR1 Digitrax direct drive using PR1 14 DIRECT Direct drive interface routine 15 ZTC ZTC system ltd 16 TRIX TRIX controller iIndex ~ Name iValue Values 1 RATE 0 - 300 BAUD, 1 - 1200 BAUD, 2 - 2400 BAUD, 3 - 4800 BAUD, 4 - 9600 BAUD, 5 - 14400 BAUD, 6 - 16400 BAUD, 7 - 19200 BAUD
2 PARITYO - NONE, 1 - ODD, 2 - EVEN, 3 - MARK, 3 STOP 0 - 1 bit, 1 - 1.5 bits, 2 - 2 bits 4 WATCHDOG 500 -65535 milliseconds. Recommended value 2048 5 'FLOW 0 - NONE, 1 - XON/XOFF, 2 - RTS/CTS, 3 BOTH
6 DATA 0 - 7 bits, 1 - 8 bits 7 DEBUGBit mask. Bit 1 sends messages to debug file.
Bit.2 sends messages to the screen. Bit 3 shows queue data. Bit.4 shows UI status. Bit 5 is reserved. Bit 6 shows semaphore and critical sections. Bit 7 shows miscellaneous messages. Bit 8 shows comm port activity. 230 decimal is recommended for debugging.

OKamPortPutConfig Parameter List Type Range Direction Description~
iLogicalPortID int 1-65535 1 In Logical port ID
iIndex int 2 In Configuration type index iValue int 2 In Configuration value iKey int 3 In Debug key 1 Maximum value for this server given by KamPortGetMaxLogPorts.
2 See Figure 7: Controller configuration Index values for a table of indexes and values.
3 Used only for the DEBUG iIndex value. Should be set to 0.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamPortPutConfig takes a logical part ID, configuration index, configuration value, and key .as parameters. It sets the port parameter specified by ilndex to the value specified by iValue. For the DEBUG .i.Index value, the debug file path is C:\Temp\Debug{POR~r}.txt where (PORT}
is the physical comm port ID.
OKamPortGetConfig Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 I;n Logical port ID
ilndex int 2 In Configuration type index piValue int * 2 Out Pointer to ~~onfiguration value 1 Maximum value for this server given by KamPortGetMaxLogPorts.
2 See Figure 7: Controller configuration Index values for a table of indexes and values.

Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzer~o is an error number (see KamMiscGetErrorMsg).
5 KamPortGetConfig takes a logical port ID, configuration index, and a pointer to a configuration value as parameters. It sets the memory pointed to by piValue to the specified configuration value.
10 OKamPortGetName Parameter List Type Range Direction Description iPhysicalPortID int 1-65535 1 In Physical port number pbsPortName BSTR * 2 Out Physical port name 15 1 Maximum value for this server given by KamPortGetMaxPhysical.
2 Exact return type depends on language. It is Cstring * for Cf+. Empty string on error.
Return Value Type Range Description 20 iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamPortGetName takes a physical port. ID number and a pointer to a port name string as parameters. It sets the 25 memory pointed to by pbsPortName to the physical port name such as "COMM1."
OKamPortPutMapController Parameter List Type Range Direct:ian Description 30 iLogicalPortID int 1-65535 1 I:n Logical port ID
iControllerlD int 1-65535 2 I:n Command station type xD
iCommPortID int 1-65535 3 I:n Physical comm port ID
35 1 Maximum value for this server given by KamPortGetMaxLogPorts.
2 See Figure 6: Controller ID to controller name mapping for values. Maximum value f=or this server is given by KamMiscMaxContrallerlD.
40 3 Maximum value for this server given by KamPortGetMaxPhysical.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonze~_°o is an error number 45 (see KamMiscGetErrorMsg).
KamPortPutMapController takes a logical port ID, a command station type ID, and a physical communicatians port ID as parameters. It maps iLo<~icalPortID to iCommPortID for the type of command station specified by 50 iControlIerID.

OKamPortGetMaxLogPorts Parameter List Type Range Direction Description~
piMaxLogicalPorts int * 1 out Maximum logical port ID
1 Normally 1 - 65535. 0 returned on error.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamPortGetMaxLogParts takes a pointer to a logical port ID as a parameter. It sets the memory pointed to by piMaxLogicalPorts to the maximum logical port ID.
OKamPortGetMaxPhysical Parameter List Type Range Direction Description pMaXPhysical int * 1 Out Maximum physical port ID
pMaxSerial int * 1 Out Maximum serial port ID
pMaxParallel int * 1 Out Maximum parallel port ID
1 Normally 1 - 65535. 0 returned on error.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamPortGetMaxPhysical takes a pointer to the number of physical ports, the number of serial ports, and the number of parallel ports as parameters. It sets the memory pointed to by the parameters to the associated values A. Commands that control command flow to the command station This section describes the commands that control the command flow to the command station. These commands do things such as connecting and disconnecting from the command station.
OKamCmdConnect Parameter List Type Range Direction Description~
iLogicalPortID int 1-65535 1 in Logical part ID
1 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCmdConnect takes a logical port ID as a parameter. It connects the server to the specified. command station.

OKamCmdDisConnect Parameter List Type Range Direction Description i_LogicalPartID int 1-65535 1 In Logical port ID
I. Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short I Error flag 1 iError = 0 for success . Nonzero is an error number (see KamMiscGetErrorMsg).
KamCmdDisConnect takes a logical port ID as a parameter.
It disconnects the server to the specified command station.
OKamCmdCommand Parameter List Type Range Direction Description lDecoderObjectID long 1 In Decoder object ID
1 Opaque object ID handle returned by KamDecoderPutAdd.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCmdCommand takes the decoder object ID as a parameter.
It sends all state changes from the server database to the specified locomotive or accessory decoder.
A. Cab Control Commands This section describes commands that control the cabs attached to a command station.
OKamCabGetMessage Parameter List Type Range Direction Description iCabAddress int 1-65535 1 In. Cab address pbsMsg BSTR * 2 Out Cab message string 1 ~ Maximum value is command station dependent.
2 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCabGetMessage takes a cab address and a pointer to a message string as parameters. It sets the memory pointed to by pbsMsg to the present cab message.
OKamCabPutMessage Parameter List Type Range Direction Description iCabAddress int 1 In Ca.b address bsMsg BSTR 2 Out Cab me~;sage string 1 Maximum value is command station dependent.
2 Exact parameter type depends on language. It is LPCSTR for C++.

Return Value Type Range Description iError short 2 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCabPutMessage takes a cab address and a BSTR as parameters. It sets the cab message to bsMsg.
OKamCabGetCabAddr Parameter List Type Range Direction Description~
lDecoderObjectID long 1 In Decoder object ID
piCabAddress int * 1-65535 2 Out Pointer to Cab address 1 Opaque object ID handle returned by KamDecoderPutAdd.
2 Maximum value is command station dependent.
Return Value Type Range Descriptions Error short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamCabGetCabAddr takes a decoder object ID and a pointer to a cab address as parameters. It set the memory pointed to by piCabAddress to the address of the cab attached to the specified decoder.
OKamCabPutAddrToCab Parameaer List Type Range Direction Description lDecoderObjectlD long 1 In Decoder object ID
iCabAddress int 1-65535 2 In Cab address 1 Opaque object~ID handle returned by KamDecoderPutAdd.
2 Maximum value is command station dependent.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nanzero is an error number (see KamMiscGetErrorMsg).
KamCabPutAddrToCab takes a decoder object ID and cab address as parameters. It attaches the decoder specified by iDCCAddr to the cab specified by iCabAddress.
A. Miscellaneous Commands This section describes miscellaneous commands that do not fit into the other categories.
OKamMiscGetErrorMsg Parameter List Type Range Direction Description iError int 0-65535 ~ In Error flag 1 iError =.0 for success. Nonzero indicates an error.
Return Value Type Range Description bsErrorString BSTR 1 Error string 1 Exact return type depends on language. It is Cstring for C++. Empty string on error.

WO 99166999 PCTlUS99114229 KamMiscGetErrorMsg takes an error flag as a parameter.
It returns a BSTR containing the descriptive error message associated with the specifie<~ error flag.
OKamMiscGetClockTime Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
iSelectTimeMode int 2 In Clock source piDay int * 0-6 out Day of week piHours int * 0-23 Out Hours piMinutes int * 0-59 Out Minute:;
piRatio int * 3 Out Fast clock ratio 1 Maximum value for this server given by KamPortGetMaxLogPorts.
2 0 - Load from command station and sync server.
1 - Load direct from server. 2 - Lo<~d from cached server copy of command station time.
3 Real time clock ratio.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscGetClockTime takes the port ID, the time mode, and pointers to locations to store the day, hours, minutes, and fast clock ratio as parameters. It sets the memory pointed to by piDay to the fast clock: day, sets pointed to by piHours to the fast clock hour;, sets the memory pointed to by p.iMinutes to the fast clock minutes, and the memory pointed to by piRatio to t:he fast clock ratio.
The servers local time will be returned if the command station does not support a fast clock.
OKamMiscPutClockTime Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In. Logical port ID
iDay int 0-6 In Day of week iHours int 0-23 In Hours iMinutes int 0-59 In Minutes iRatio int 2 In Fast clock ratio 1 Maximum value for this server given by KamPortGetMaxLogPorts. 2 Real time clock ratio.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscPutClockTime takes the fast clock logical port, the fast clock day, the fast clock hours, the fast clock minutes, and the fast clock ratio as parameters. It sets the fast clock using specified parameters.

WO 99/bb999 PCT/US99/14229 OKamMis~GetInterfaceVersion Parameter List Type Range Direction Description pbsInterfaceVersion BSTR * 1 Out Pointer to interface version string 5 1 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzex-o is an error number 10 (see KamMiscGetErrorMsg).
KamMiscGetlnterfaceVe,rsion takes a pointer to an interface version string as a parameter. It sets the memory pointed to by pbslnterfaceVersion to the interface version string. The version string may contain multiple 15 lines depending on the number of interfaces supported.
OKamMiscSaveData Parameter List Type Range Direction Description NONE
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamM.iscSaveData takes no parameters. It saves all server data to permanent storage. This command is run automatically whenever the server stops running. Demo versions of the program cannot save data and this command will return an error in that case.
OKamMiscGetControllerName Parameter List Type Range Direction Description iControllerID int 1-65535 1 In Command station type ID
pbsName BSTR * 2 Out fommand station type name 1 See Figure 6: Controller ID to controller name mapping for values. Maximum value for this server is given by KamMiscMaxControllerlD.
2 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description bsName BSTR 1 Command station type name Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscGetControllerName takes a command station type ID
and a pointer to a type name string as parameters. It sets the memory pointed to by pbsName to the command station type name.

OKamMiscGetControllerNameAtPort Parameter List Type Range Direction Description iLogicalPortID int 1-65535 1 In Logical port ID
pbsName BSTR * 2 Out C~~mmand station type ' name 1 Maximum value for this server given by KamPortGetMaxLogPorts.
2 Exact return type depends on language. It is Cstring * for C++. Empty string on error.
Return Value Type Range Description iError short° 1 Error flag 1 iError = 0 for success. Ntinzero is an error number (see KamMiscGetErrorMsg).
KamMiscGetControllerName takes a log_Lcal port ID and a pointer to a command station type name as parameters. It sets the memory pointed to by pbsNamE~ to the command station type name for that logical port.
OKamMiscGetCommandStationValue Parameter List Type Range Direction Description iControllerID int 1-65535 1 In Command station type ID
iLogicalPortID int 1-65535 2 In Logical port ID
ilndex int 3 In Command station array index piValue~int * 0 - 65535 Out Command station value Z See Figure 6: Controller ID to controller name mapping for values. Maximum value for this server is given by KamMiscMaxControllerID.
2 Maximum value for this server given by KamPortGetMaxLogPorts.
3 0 to KamMiscGetCommandStationlndex .
Return value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscGetCommandStationValue takes the controller ID, logical port, value array index, and a pointer to the location to store the selected value. It sets the memory pointed to by piValue to the specified command station miscellaneous data value:
OKamMiscSetCommandStationValue Parameter List Type Range Direction Description iControllerTD int 1-65535 1 In Command station type ID
iLogicalPortID int 1-65535 2 In Logical port ID
iIndex int 3 In Command station array index iValue int 0 - 65535 In Command station value 1 See Figure 6: Controller ID to controller. name mapping for values. Maximum value for this server is given by KamMiscMaxControllerID.
2 Maximum value for this server given by KamPortGetMaxLogPorts. 3 0 to KamMiscGetCommandStationIndex.

Return Value Type Range Description iError ahort 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiseSetCommandStationVaiue takes the controller ID, logical port, value array index, and neza miscellaneous data value. It sets the specified command station data to the value given by piValue.
OKamMiscGetCommandStationIndex Parameter List Type Range Direction Description iControllerlD int 1-65535 1 In Command station type ID
iLogicalPortID int 1-65535 2 In Logical port ID
piIndex int 0-65535 Out Pointer to maximum index 1 See Figure 6: Controller ID to controller name mapping for values. Maximum value for this server is given by KamMiscMaxControllerID.
2 Maximum value for this server given by KamPortGetMaxLogPorts.
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscGetCommandStationIndex takes the controller ID, logical port, and a pointer to the location to store the maximum index.. It sets the memory pointed to by piIndex to the specified command station maximum miscellaneous data index.
flKamMiscMaxControllerID
Parameter List Type Range Direction Description piMaxControllerlD int * 1-65535 1 Out Maximum controller type ID
1 See Figure 6: Controller ID to ,controller name mapping for a list of controller ID values. 0 returned on error.
Return Value Type Range Description iError short 2 Error flag Z iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscMaxControllerTD takes a pointer to the maximum controller ID as a parameter. It sets the memory pointed to by piMaxControllerID to the maximum controller type ID.

WO 99/66999 PCTlUS99/14229 OKamMiscGetControllerFacility Parameter List Type Range Direction Description iControllerID int 1-65535 1 In. Command station type ID
pdwFacility long * 2 Out Painter to command station facility mask 1 See Figure 6: Controller ID to c:antroller name mapping for values. Maximum value.for this server is given by KamMiscMaxControllerlD.
10. 2 0 - CMDSDTA PRGMODE_ADDR
1 - CMDSDTA~PRGMODE_REG
2 - CMDSDTA~_PRGMODE_PAGE
3 - CMDSDTA_PRGMODE_DIR
4 - CMDSDTA PRGMODE_FLYSHT
5 - CMDSDTA~_PRGMODE_FLYLNG
6 - Reserved 7 - Reserved 8 - Reserved 9 - Reserved 10 - CMDSDTA_SUPPORT_CONSIST
11 -.CMDSDTA SUPPORT LONG
12 - CMDSDTA_SUPPORT FEED
13 - CMDSDTA_SUPPORT~_2TRK
14 - CMDSDTA PROGRAM_TRACK
15 - CMDSDTA_~PROGMAIN_POFF
16 - CMDSDTA_FEDMODE_ADDR

18 - CMDSDTA~_FEDMODE~_PAGE
19 - CMDSDTA_FEDMODE_DIR
20 - CMDSDTA_FEDMODE_FLYSHT
21 - CMDSDTA_FEDMODE_FLYLNG
30 - Reserved 31 - CMDSDTA_SUPPORT_FASTCLK
Return Value Type Range Description iError short 1 Error flag 1 iError = 0 for success. Nonzero is an error number (see KamMiscGetErrorMsg).
KamMiscGetControllerFacility takes the control3.er ID and a pointer to the location to store the selected controller facility mask. It sets the memory pointed to by pdwFacility to the specified command station facility mask.
The terms and expressions which have been employed in the foregoing specification are used therein as terms of description and not of l~.mitation, and there is no intention, in the use of such germs and expressions, of excluding equivalents of the features shown and described or portions thereof, it being recognized that the scope of the invention is defined and limited only by the claims which follow.

Claims (54)

CLAIMS:

1. A method of operating a model train control system comprising the steps of:
(a) a user operating a user interface for transmitting a first command from a first client program to a resident external controlling interface through a first communications transport;
(b) a user operating a user interface for transmitting a second command from a second client program to said resident external controlling interface through a second communications transport;
(c) receiving said first command and said second command at said resident external controlling interface;
(d) said resident external controlling interface queuing said first and second commands; and (e) said resident external controlling interface sending third and fourth commands representative of said first and second commands, respectively, to a digital command station for execution on said model train control system.

2. The method of claim 1, further comprising the steps of:
(a) providing an acknowledgment to said first client program in response to receiving said first command by said resident external controlling interface prior to sending said third command to said digital command station; and (b) providing an acknowledgment to said second client program in response to receiving said second command by said resident external controlling interface prior to sending said fourth command to said digital command station.

3. The method of claim 2, further comprising the steps of:
(a) selectively sending said third command to one of a plurality of digital command stations; and (b) selectively sending said fourth command to one of said plurality of digital command stations.

4. The method of claim 3, further comprising the step of receiving command station responses representative of a state of devices of said model train control system from said plurality of digital command stations.

5. The method of claim 4, further comprising the step of comparing said command station responses to previous commands sent to at least one of said plurality of digital command stations to determine which said previous commands correspond with said response.

6. The method of claim 5, further comprising the steps of:
(a) maintaining a sending queue of commands to be transmitted to said plurality of digital command stations; and (b) retransmitting at least one of said commands in said sending queue periodically until removed from said sending queue as a result of the comparison of said command station responses to previous commands.

7. The method of claim 6, further comprising the step of updating a database of a state of said model train control system based upon said receiving command station responses representative of said state of devices of said model train control system.

8. The method of claim 7, further comprising the step of providing said acknowledgment to said first client program in response to receiving said first command by said resident external controlling interface together with state information from said database related to said first command.

9. The method of claim 8 wherein said first command and said third command are the same command, and said second command and said fourth command are the same command.

10. A method of operating a model train control system comprising the steps of:
(a) a user operating a user interface for transmitting a first command from a first client program to a resident external controlling interface through a first communications transport;
(b) receiving said first command at said resident external controlling interface; and (c) said resident external controlling interface selectively sending a second command representative of said first command to one of a plurality of digital command stations for execution on said model train control system based upon information contained within at least one of said first and second commands.

11. The method of claim 10, further comprising the steps of (a) a user operating a user interface for transmitting a third command from a second client program to said resident external controlling interface through a second communications transport;
(b) receiving said third command at said resident external controlling interface; and (c) said resident external controlling interface selectively sending a fourth command representative of said third command to one of said plurality of digital command stations for execution on said model train control system based upon information contained within at least one of said third and fourth commands.

12. The method of claim 11 wherein said first communications transport is at least one of a COM interface and a DCOM interface .

13. The method of claim 11 wherein said first communications transport and said second communications transport are DCOM interfaces.

14. The method of claim 10 wherein said first client program and said resident external controlling interface are operating on one computer.

15. The method of claim 11 wherein said first client program, said second client program, and said resident external controlling interface are all operating on different computers.

16. The method of claim 10, further comprising the step of providing an acknowledgment to said first client program in response to receiving said first command by said resident external controlling interface prior to sending said second command to said digital command station.

17. The method of claim 16, further comprising the step of receiving command station responses representative of a state of devices of said model train control system from said of digital command station.

18. The method of claim 17, further comprising the step of comparing said command station responses to previous commands sent to said digital command station to determine which said previous commands it corresponds with.

19. The method of claim 18, further comprising the steps of:
(a) maintaining a sending queue of commands to be transmitted to said digital command station; and (b) retransmitting at least one of said commands in said sending queue periodically until removed from said sending queue as a result of the comparison of said command station responses to previous commands.

20. The method of claim 19, further comprising the step of updating a database of a state of devices of said model train control system based upon said receiving command station responses representative of said state of devices of said model train control system.

21. The method of claim 20, further comprising the step of providing said acknowledgment to said first client program in response to receiving said first command by said resident external controlling interface together with state information from said database related to said first command.

22. The method of claim 10 wherein said resident external controlling interface communicates in an asynchronous manner with said first client program while communicating in a synchronous manner with said plurality of digital command stations.

23 A method of operating a model train control system comprising the steps of:
(a) a user operating a user interface for transmitting a first command from a first client program to a resident external controlling interface through a first communications transport;
(b) a user operating a user interface for transmitting a second command from a second client program to a resident external controlling interface through a second communications transport;
(c) receiving said first command at said resident external controlling interface;
(d) receiving said second command at said resident external controlling interface; and (e) said resident external controlling interface sending a third and fourth command representative of said first command and said second command, respectively, to the same digital command station for execution on said model train control system.

24. The method of claim 23 wherein said resident external controlling interface communicates in an asynchronous manner with said first and second client programs while communicating in a synchronous manner with said digital command station.

25. The method of claim 23 wherein said first communications transport is at least one of a COM interface and a DCOM interface.

26. The method of claim 23 wherein said first communications transport and said second communications transport are DCOM interfaces.

27. The method of claim 23 wherein said first client program and said resident external controlling interface are operating on the same computer.

28. The method of claim 23 wherein said first client program, said second client program, and said resident external controlling interface are all operating on different computers.

29. The method of claim 23, further comprising the step of providing an acknowledgment to said first client program in response to receiving said first command by said resident external controlling interface prior to sending said third command to said digital command station.

30. The method of claim 29, further comprising the step of receiving command station responses representative of a state of devices of said model train control system from said of digital command station.

31. The method of claim 30, further comprising the step of comparing said command station responses to previous commands sent to said digital command station to determine which said previous commands correspond with said response.

32. The method of claim 31, further comprising the steps of:
(a) maintaining a sending queue of commands to be transmitted to said digital command station; and (b) retransmitting at least one of said commands in said sending queue periodically until removed from said sending queue as a result of the comparison of said command station responses to previous commands.

33. The method of claim 32, further comprising the step of updating a database of a state of said model train control system based upon said receiving command station responses representative of said state of devices of said model train control system.

34. The method of claim 33, further comprising the step of providing said acknowledgment to said first client program in response to receiving said first command by said resident external controlling interface together with state information from said database related to said first command.

35. A method of operating a model train control system comprising the steps of:
(a) a user operating a user interface for transmitting a first command from a first client program to a first processor through a first communications transport;
(b) receiving said first command at said first processor; and (c) said first processor providing an acknowledgment to said first client program through said first communications transport indicating that said first command has properly executed prior to execution of commands related to said first command by said model train control system.

36. The method of claim 35, further comprising the step of sending said first command to a second processor which processes said first command into a state suitable for a digital command station for execution on said model train control system.

37. The method of claim 36, further comprising the step of said second processor queuing a plurality of commands received.

38. The method of claim 35, further comprising the steps of (a) a user operating a user interface for transmitting a second command from a second client program to said first processor through a second communications transport;
(b) receiving said second command at said first processor; and (c) said first processor selectively providing an acknowledgment to said second client program through said second communications transport indicating that said second command has properly executed prior to execution of commands related to said second command by said model train control system.

39. The method of claim 38, further comprising the steps of (a) sending a third command representative of said first command to one of a plurality of digital command stations for execution on said model train control system based upon information contained within at least one of said first and third commands; and (b) sending a fourth command representative of said second command to one of said plurality of digital command stations for execution on said model train control system based upon information contained within at least one of said second and fourth commands.

40. The method of claim 35 wherein said first communications transport is at least one of a COM interface and a DOOM interface.

41. The method of claim 38 wherein said first communications transport and said second communications transport are DCOM interfaces.

42. The method of claim 35 wherein said first client program and said first processor are operating on one computer.

43. The method of claim 38 wherein said first client program, said second client program, and said first processor are all operating on different computers.

44. The method of claim 35 further comprising the step of receiving command station responses representative of a state of devices of said model train control system from a digital command station.

45. The method of claim 44 further comprising the step of comparing said command station responses to previous commands sent to said digital command station to determine which said previous commands correspond with said response.

46. The method of claim 45 further comprising the steps of:
(a) maintaining a sending queue of commands to be transmitted to said digital command station; and (b) retransmitting at least one of said commands in said sending queue periodically until removed from said sending queue as a result of the comparison of said command station responses to previous commands.

47. The method of claim 46 further comprising the step of updating a database of a state of said model train control system based upon said receiving command station responses representative of said state of devices of said model train control system.

48. The method of claim 47 further comprising the step of providing said acknowledgment to said first client program in response to receiving said first command by first processor together with state information from said database related to said first command.

49. The method of claim 43 wherein said first processor communicates in an asynchronous manner with said first client program

50. A method of operating a model train control system comprising the steps of:
(a) a user operating a user interface for transmitting a first command from a first client program to an asynchronous command processor through a first communications transport;
(b) receiving said first command at said asynchronous command processor;
(c) said asynchronous command processor providing an acknowledgment to said first client program through said first communications transport indicating that said first command has properly executed prior to execution of said first command by said model train control system;
(d) sending said first command to a command queue where said asynchronous command processor considers said command queue and the intended destination device of said first command;
(e) receiving said first command from said command queue by a synchronous command processor; and (f) processing said first command by said synchronous command processor into a suitable format for execution by a digital command station for said model train control system.

51. The method of claim 50 further comprising the steps of:
(a) receiving responses from a digital command station; and (b) updating a first database of a state of devices of said model train control system based upon said responses from said digital command station.

52. The method of claim 51, further comprising the steps of:
(a) sending a first response to said command queue from said synchronous command processor where said synchronous command processor considers said command queue and the intended destination device of said first response;
(b) receiving said first response from said command queue by a asynchronous command processor; and (c) processing said first response by said asynchronous command processor into a suitable format for sending through said communications transport to said first client program.

53. The method of claim 52, further comprising the step of updating a second database of a state of devices of said model train control system by said asynchronous command processor based upon said first response from said synchronous command processor.

54. The method of claim 53, further comprising the step of querying said second database by said asynchronous command processor providing said acknowledgment to said first client program through said first communications transport providing the information requested and not sending said first command to said command queue.