Programming Reference Manual for
DigiAPI
Rob Hamerling
Vianen, The Netherlands
E-mail: r.hamerling@planet.nl
homepage: http://www.geocities.com/digithalys/
Copyright © R. Hamerling, 1991, 2000
All Rights Reserved.
List of user callable functions in alphabetically sequence
Parameter Specifications
Some semi-standard parametertypes are used with the functions, such as:
- UCHAR - unsigned character
- USHORT - unsigned short integer
- ULONG - unsigned long integer
- HFILE - (unsigned long integer) ChannelHandle returned by
DigiOpen().
It is a logical reference to an opened channel, used with most functions to
indicate the destination of the requested operation.
Specification of a wrong value will result in returncode 'Invalid Handle'
(6), and the operation will not be executed.
For C-language the function prototypes are specified in the include file
DIGIAPI.H.
For QuickBASIC the function specification are in DIGIAPI.INC, in which
the regular notational convention is used:
- $ - string variable
- % - integer (16 bits)
- & - long integer (32 bits)
When using the provided include file DIGIAPI.INC you don't have to worry
about the specifications.
Specification of Functions
The following sections contain the specifications of available functions
of DigiAPI in alphabetical sequence.
NOTE: The descriptions for C-language and QuickBASIC are both
given, but in the text mainly the C-language notations are used.
Guidelines how to use these functions can be found in the
Guide to Application Programming with DigiApi.
DigiClose
- Name
- DigiClose - terminate communications with the modelrailroad
- C-language
- #include "digiapi.h"
ULONG DigiClose(HFILE HChannel);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiClose& Cdecl (Byval HChannel&)
- Description
- The close-routine disables the communications task of the driver.
It should be called before terminating your program.
DigiClose does not return before pending output has been transmitted if
possible (implies DigiFlush()).
- Parameters
- HChannel
- Handle of a previously opened channel.
- Return value
- 0 when close successful
- 2 any error that prevented terminating communications, not all data
may have been transmitted.
- Related functions
- DigiOpen, DigiFlush
- Remarks
- DigiClose() is not a trivial function!
It must be used when DigiOpen() has been called successfully.
Under DOS your system may enter a hang-up situation when for no matter what
reason your communications port gives an interrupt.
So terminate your program always 'gracefully', such as intercepting
Ctrl-Break in your program to prevent uncontrolled program termination!
DigiEnableFeedback
- Name
- DigiEnableFeedback - start monitoring feedback contact.
- C-language
- #include "digiapi.h"
ULONG DigiEnableFeedback(HFILE HChannel, ULONG ulContact,
ULONG ulFlag);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiEnableFeedback& Cdecl (Byval HChannel&,
Byval Contact&, Byval Flag&);
- Description
- DigiAPI starts monitoring the specified feedback contact.
When starting the process to read feedback information for 'passive'
systems, a 'read with reset' is issued.
The first data may not reflect the actual situation (trains may have been
moved by manual actions)!
It is recommended to wait some time (depending on number of contactpoints
between 100 and 300 msecs) before issuing a DigiQueryFeedbackState() if you
need to know the actual situation!
The responses of the read-operation of feedback contacts are stored in an
internal table and returned by DigiQueryFeedbackState().
If a system supports reading train-decoder information (Lenz, Trix) this
will be enabled automatically for active locs after a DigiEnableFeedback().
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulContact
- The number of the feedback contact to be monitored.
- ulFlag
- Select monitoring of the specified contact.
With any non-zero value monitoring goes ON for the specified contact.
When monitoring was already ON the contact will be added to the previously
specified contacts.
With a zero value ALL monitoring is stopped.
- Return value
- Nothing
- Related functions
- DigiQueryFeedbackCount,
DigiQueryFeedbackState and
DigiQueryFeedbackTime.
- Remarks
- Some systems (like Märklin and Trix) are 'passive', and need a
command to return the status of feedback contacts.
- Other systems (like Lenz) are 'active' and return changes in the state
of feedback contacts without being asked for it.
- In any case monitoring should be activated as soon as a channel has
been opened, even if you don't actually use feedback contacts!
This is because, apart from reading feedback encoders, the monitoring task
will check if the modelrailroad is responding to any commands.
DigiFlush
- Name
- DigiFlush - wait until all buffered output has been transmitted.
- C-language
- #include "digiapi.h"
ULONG DigiFlush(HFILE HChannel);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiFlush& Cdecl (Byval HChannel&)
- Description
- Wait until all output is sent to the Interface.
In other words
When buffered data is apparently not being transmitted anymore, the
remaining commands in the transmit buffer will be purged and the purge
statistics are updated accordingly.
- Parameters
- HChannel
- Handle of a previously opened channel.
- Return value
- Depending on success
- 0 when no more commands to transmit (queue empty)
- >0 number of commands not transmitted.
- Related functions
- DigiPurge
- Remarks
- The flush may not wait until all commands are transmitted.
If for some reason (like a shortcut) the queue is not shrinking anymore the
function returns with the number of commands still queued.
DigiGo
- Name
- DigiGo - send the 'go' command.
- C-language
- #include "digiapi.h"
ULONG DigiGo(HFILE HChannel);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiGo& Cdecl (Byval HChannel&)
- Description
- A 'go'-command will be send to the Interface.
The flow control requirements of the Interface are ignored.
If an error occurs, for example the Interface does not repond, DigiGo will
return an error code.
- Parameters
- HChannel
- Handle of a previously opened channel.
- Return value
- Returncode (DOS: always 0)
- Related functions
- DigiStop
- Remarks.
- None.
DigiOpen
- Name
- DigiOpen - start communications with the modelrailroad
- C-language
- #include "digiapi.h"
HFILE HChannel DigiOpen(UCHAR *DevName,
ULONG ulProtocol, ULONG ulSpeed);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiOpen& Cdecl (Byval DevNameOffset%,
Byval DevNameSegment%, Byval Protocol&, Byval
Speed&)
- Description
- Initialise the connection between computer and modelrailroad interface.
- Parameters
- DevName
- Name of the Computer-device being used for the connection with the
modelrailroad(-Interface).
Genearlly this will be "COM1" or "COM2",
but any valid devicename (ASCIIZ-string) is allowed.
For QuickBasic the devicename must be passed as a far pointer to a fixed
length string.
See the sample Quickbasic Framework for how
this could be specified.
- ulProtocol
- Specifies the identifier (symbolic name) of the required protocol, which
should be one out of the list of supported protocols.
The files digiapi.h and DigiAPI.Inc each contain the list of
identifiers of supported protocols.
- ulSpeed
- Transmission speed of the serial port.
Supported range: 2..57600.
When the specified value is outside the indicated range DigiAPI will replace
it by the default value for the specified Protocol parameter.
It is recommended to specify 0 (zero) to make your program independent of
the type of system.
See Manufacturer Information.
- Returnvalue
- FileHandle
When DigiOpen returns the value 0 (zero) external variable
DigiErrno will contain one of the following values:
- 0 - port opened successfully
- 21 - port not ready
- 32 - port probably occupied by another device
- 110 - port not available
- other - see OS/2 or DOS documentation
All statistics counters are set to zero with DigiOpen().
- Related functions
- DigiClose, DigiQueryStatistics
- Remarks
-
- The DigiOpen function for DOS expects a far pointer to the name of the
device to be used.
With QuickBasic Device has to be specified as an (offset,segment)
pair of a fixed length ASCIIZ string (with terminating null).
For example like:
DIM Port as string * 8
Port = "COM2" + CHAR$(0)
Hchan2 = DigiOpen(VARPTR(Port), VARSEG(Port), PROTOCOL_LENZ, 0)
- Currently DigiAPI supports only COM-ports, or device drivers emulating a
regular COM-port (like Booster.SYS for OS/2).
- After DigiOpen successfully established communications with the device,
it transmits a 'go' command to be able to transmit data should the Interface
be in stopped state.
DigiPurge
- Name
- DigiPurge - purge output buffer
- C-language
- #include "digiapi.h"
ULONG DigiPurge(HFILE HChannel);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiPurge& Cdecl (Byval HChannel&)
- Description
- Discard queued commands.
If the output queued contains any commands not yet transmitted,
these will not be sent to the Interface, and processing continues
immediately as if the application never requested these.
- Parameters
- HChannel
- Handle of a previously opened channel.
- Return value
- zero (or invalid handle)
- Related functions
- DigiFlush
- Remarks.
- None.
DigiQueryAccessoryState
- Name
- DigiQueryAccessoryState - obtain current position of an
accessory, switch or signal.
- C-language
- #include "digiapi.h"
ULONG DigiQueryAccessoryState(HFILE HChannel,
ULONG ulAccessory);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryAccessoryState& Cdecl (Byval
HChannel&, Byval Accessory&)
- Description
- Returns current state of an accessory.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulAccessory
- Accessory number.
- Return value
- State of the accessory 0 (zero) for Off, any non-zero value means Off.
- Related functions
- None
- Remarks
- None.
DigiQueryFeedbackCount
This function is not yet implemented.
- Name
- DigiQueryFeedbackCount - obtain 'on' count of feedback contact.
- C-language
- #include "digiapi.h"
ULONG DigiQueryFeedbackCount(HFILE HChannel,
ULONG ulContact);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryFeedbackCount& Cdecl (Byval HChannel&,
Byval Contact&)
- Description
- Returns number of times the contact flipped from 'off' to 'on' state
since the last time the counter was reset.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulContact
- The number of the contact for which the count is requested.
- Return value
- Number of times the specific contact was activated since the last time
this function was called for this contact (read-with-reset).
- Related functions
- DigiEnableFeedback
- Remarks
-
- When monitoring for this channel has not been enabled previously, the
returned information is undefined for 'passive' systems.
- Currently the highest value ever returned is 1.
DigiQueryFeedbackState
- Name
- DigiQueryFeedbackState - get bit-pattern of a group of contacts
- C-language
- #include "digiapi.h"
UCHAR DigiQueryFeedbackState(HFILE HChannel, ULONG ulGroup);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryFeedbackState& Cdecl (Byval
HChannel&, Byval GROUP&)
- Description
- Get a single byte (8 bits) of feedback information.
The required parameter specifies:
- Lenz and Trix: the feedback groupnumber (in the range 1..max).
- Märklin: the relative position of the 'half' S88.
For example to get the status of the second half of the third S88 specify
DigiQueryFeedbackState(6)
When DigiQueryFeedbackState() is called with parameter value 0 (zero), all
settings will be reset to zero, and a zero will be returned.
System monitoring feedback will have to be started first with
DigiEnableFeedback() before the result of DigiQueryFeedbackState gives
meaningful results.
This function does not generate any action to the Interface and returns
the latest obtained status immediately.
See for a further explanation:
Reading Feedback Encoders in the
Application Programming Guide.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulGroup
- Number of group of 8 bit contacts (feedback decoder number).
- Return value
- A single byte (8-bit) containing the cumulated contact point 'on' status.
- Related functions
- DigiEnableFeedback
- Remarks
-
- When monitoring has not been enabled previously for this channel, the
returned information is undefined for 'passive' systems, it may contain
actual information for 'active' systems (like Lenz).
- The 'ON' signals of feedback encoders are cumulated until a
DigiQueryFeedbackState() is called for a specific group of contacts.
The caller obtains all occupied signals, and then the bits in the group are
refreshed to reflect the current setting.
See for details:
Reading Feedback Encoders.
Depending on the type of contacts used on the model railroad, and the
frequency in which DigiQueryFeedbackState() is issued by the mainline, it
may be necessary to issue DigiQueryFeedbackState() twice.
DigiQueryFeedbackTime
This function is not yet implemented.
- Name
- DigiQueryFeedbackTime - obtain time since contact has turned 'on'.
- C-language
- #include "digiapi.h"
ULONG DigiQueryFeedbackTime(HFILE HChannel, ULONG ulContact);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryFeedbackTime& Cdecl (Byval HChannel&,
Byval Contact&)
- Description
- Returns time in milliseconds the contact was turned on since the last
time the time was reset.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulContact
- Contact number
- Return value
- Time in milliseconds the specific contact flipped from 'off' to 'on'
state since the last time this function was called for this contact
(read-with-reset).
- Related functions
- DigiEnableFeedback
- Remarks
-
- When monitoring has not been enabled previously for this channel, the
returned information will be zero for 'passive' systems.
- Currently the highest value ever returned is 1.
DigiQueryStatistics
- Name
- DigiQueryStatistics - obtain content of statistics counter.
- C-language
- #include "digiapi.h"
long DigiQueryStatistics(HFILE HChannel, ULONG ulCounter);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryStatistics& Cdecl (Byval
HChannel&, Byval Counter&)
- Description
- Obtain value of an internal counter in DigiAPI for statistical purposes.
There is a separate set of counters for each channel.
All counters of a channel will be set to zero with DigiOpen(),
but may also be reset by specifying 0 (zero) as counter number.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulCounter
- Number of the counter (see table below).
| 1 |
Number of accepted commands including internally generated commands for
monitoring.
Since DigiAPI uses a command-queuing mechanism, not all of these commands
may have been physically transmitted! |
|---|
| 2 |
Number of internally generated commands for monitoring purposes (like
for reading feedback encoders). |
|---|
| 3 |
Number of commands that were discarded.
Reasons may be:
- System was in 'stop-state' while attempting to issue commands
- Commands could not be accepted due to a 'full' condition of the transmit
queue at some time.
|
|---|
| 4 |
Maximum number of commands that were queued for transmission at any
point in time.
This value should be related to the maximum number of available slots (1024
with OS/2, 512 with DOS) to determine if the currently fixed ('hard
coded')queuesize is adequate for your program.
It may be reported as 'bug' if the queue is not large enough under
'normal' circumstances.
|
|---|
| 5 |
Number of commands purged: not actually transmitted after first being
accepted.
Reasons for purging a command may be:
- Commands were in the transmit buffer during a call to DigiPurge().
- There were commands buffered while DigiStop() was called.
- DigiFlush() could not complete (timeout).
Note: Discarded commands will not be counted as 'purged', since these
commands were not accepted and never put in the transmit queue!
|
|---|
| 6 |
Number of bytes actually transmitted.
|
|---|
| 7 |
Number of bytes actually received (feedback data and/or status
messages). |
|---|
Specifying a counter number outside the indicated range will give
unpredictable results.
- Return value
- Contents of the specified counter (zero after reset).
- Related functions
- DigiOpen
- Remarks.
- None.
DigiQuerySystemState
- Name
- DigiQuerySystemState - obtain actual system status information.
- C-language
- #include "digiapi.h"
ULONG DigiQuerySystemState(HFILE HChannel, SYSTEMSTATE
*SystemState);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQuerySystemState& Cdecl (Byval HChannel&,
SEG SystemState as SYSTEMSTATERECORD)
- Description
- Obtain actual system status.
The function returns the actual values of system state variables in a
record provided by the caller.
- Parameters
- HChannel
- Handle of a previously opened channel.
- SystemState
- Pointer to a user provided record which will receive the system state
variables.
- Return value
- The systemstate itself is also returned (0=go, 1=stop) as returnvalue of
the function.
If appropriate an 'invalid channel handle' errorcode will be returned,
in which case the contents of the SystemState record are undetermined.
- Related functions
- DigiOpen, DigiGo,
DigiStop.
- Remarks.
- The layout of the record is defined in the header file "digiapi.h" for
C-language, in "DIGIAPI.INC" for QuickBASIC.
- The stop-state will be returned after the application called DigiStop, or
after the modelrailroad (Interface) reported a stop-condition (for example
issued by a Lenz handheld control LH100).
The stop-state will also be reported when the system status monitor task
of DigiAPI does not receive reponses on feedback commands from the Interface
and CTS is not true.
Prerequisite is that feedback monitoring has been enabled by the
application, and is applicable for the corresponding channel.
DigiQueryTrainFunction
- Name
- DigiQueryTrainFunction - Obtain current setting of a train function
- C-language
- #include "digiapi.h"
ULONG DigiQueryTrainFunction(HFILE HChannel, ULONG ulTrain);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryTrainFunction& Cdecl (Byval HChannel&,
Byval Train&)
- Description
- Returns current position of a train function.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulTrain
- Number of the train or loc (decoder address).
- Return
- Function settings in a 32-bit string right to left.
Function 1 is the rightmost bit, function 2 is the one left of 1, etc.
- Related functions
- None.
- Remarks
- Function number 1 is the 'auxiliary' function which is in most systems
imbedded in the speed command, while functions 2 .. 5 and above are the
'extra' functions.
DigiQueryTrainSpeed
- Name
- DigiQueryTrainSpeed - Obtain current speed of a train
- C-language
- #include "digiapi.h"
ULONG DigiQueryTrainSpeed(HFILE HChannel, ULONG ulTrain);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiQueryTrainSpeed& Cdecl (Byval
HChannel&, Byval Train&)
- Description
- Returns current speed of train (value -1000 .. +1000)
- Parameters
- HChannel
- Handle of a previously opened channel.
- Address
- Number of the train or loc (decoder address).
- Return
- Current speed of the loc in the range -1000 to +1000.
- Related Functions
- DigiSetTrainSpeed.
- Remarks
- The returned value is rounded as discussed with DigiSetTrainSpeed.
In passive systems (like Märklin Digital) it represents the value of
the last command, with 'active' systems (like Lenz Digital Plus) it
represents either the value of the last command or the last value returned
by the Interface.
DigiSendReceive
This function is not provided by DigiAPI and
documented for compatibility with Railroad & Co.
- Name
- DigiSendReceive - Send number of characters and receive system
response.
- C-language
- #include "digiapi.h"
ULONG DigiSendReceive(HFILE HChannel, UCHAR *pSendBuffer,
ULONG ulSendCount, UCHAR *pReceiveBuffer, ULONG
ulReceiveCount, ULONG ulMaxWaitTime);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSendReceive& Cdecl (Byval HChannel&,
Seg SendBuffer$, Byval SendCount&,
Seg ReceiveBuffer$, Byval ReceiveCount&,
Byval )
- Description
- Send a characterstring into the channel and receive the response from
the modelrailroad.
- Parameters
- HChannel
- Handle of a previously opened channel.
- pSendBuffer
- Buffer containing the data to be transmitted.
- ulSendCount
- Number of bytes to transmit
- pReveiveBuffer
- Buffer where the received data will be returned.
- ulReveiveCount
- Maximum number of bytes expected.
- ulMaxWaitTime
- Maximum number of milliseconds to wait for the expected number of bytes
to arrive.
- Return
- 0
- Remarks
- None.
DigiSetContactOff
- Name
- DigiSetContactOff - set an accessory in 'OFF' position
- C-language
- #include "digiapi.h"
ULONG DigiSetContactOff(HFILE HChannel, ULONG Accessory,
ULONG ulContact, ULONG ulDelay);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSetContactOff& Cdecl (Byval
HChannel&, Byval Accessory&)
- Description
- Switch an accessory contact OFF.
- Parameters
- HChannel
- Handle of a previously opened channel.
- Accessory
- Number of the accessory.
- Contact
- Number of the Concact (0 | 1).
- Delay
- Number of milliseconds to wait before actually switching the contact OFF.
- Returns
- Zero means function accepted
non zero: error, DigiErrno will indicate type of error.
- Related Functions
- DigiOpen DigiSetContactOn.
- Remarks
- See also the explanations with the specifications of DigiContactOn().
DigiSetContactOn
- Name
- DigiSetContactOn - set an accessory in 'ON' position
- C-language
- #include "digiapi.h"
ULONG DigiSetContactOn(HFILE HChannel, ULONG ulAccessory,
ULONG ulContact, ULONG ulDelay);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSetContactOn& Cdecl (Byval HChannel&,
Byval Accessory&, Byval Contact&,
Byval Delay&);
- Description
- Set an accessory contact ON.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulAccessory
- Number of the accessory.
- Contact
- Contact to be switched on (0 | 1)
For switchpoints the value '0' represents the (red) 'branch' button and
the value '1' the (green) 'straight' button.
- ulDelay
- Number of milliseconds to wait before actually switching the contact ON.
- Returns
- Zero means function accepted
non zero: error, DigiErrno will indicate type of error.
- Related Functions
- DigiOpen DigiSetContactOff.
- Remarks
- None.
DigiSetFeedbackAction
This function is not provided by DigiAPI and
documented for compatibility with Railroad & Co.
- Name
- DigiSetFeedbackAction - register a monitoring task.
- C-language
- #include "digiapi.h"
ULONG DigiSetFeedbackAction(HFILE HChannel, ????
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSetFeedBackAction& Cdecl (Byval
HChannel&, &???
- Description
- Register an action to be initiated with a certain event.
- Parameters
- HChannel
- Handle of a open previously opened channel.
- ????
- Pointer to action record.
- Return value
- 0 if OK.
- Related functions
- DigiEnableFeedback
- Remarks
-
- When monitoring has not been enabled previously for this channel, the
call is not meaning full, since no action will ever be executed, even
if the condition is met!
- This function is currently not provided by DigiAPI.
DigiSetTrainFunction
- Name
- DigiSetTrainFunction - Control speed of a loc / train
- C-language
- #include "digiapi.h"
ULONG DigiSetTrainFunction(HFILE HChannel, ULONG ulTrain,
ULONG ulFunction, ULONG ulState, ULONG ulDelay);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSetTrainFunction& Cdecl (Byval
HChannel&, Byval Train&, Byval Function&,
Byval Function&, Byval State&,
Byval Delay&)
- Description
- Switches a train function (lights, coupling, smoke generator) on or off.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulTrain
- Number of train or loc (decoder address).
- ulFunction
- Number of the function (1..nn).
- ulState
- Indicator to switch function ON or OFF.
Value 0 (zero) switches the function OFF, any non-zero value switches the
function ON.
- ulDelay
- Number of milliseconds after which the operation has to take place.
- Returns
- Zero means function accepted
non zero: error, DigiErrno will indicate type of error.
- Related Functions
- DigiOpen.
- Remarks
-
DigiSetTrainSpeed
- Name
- DigiSetTrainSpeed - Set desired speed of a train.
- C-language
- #include "digiapi.h"
ULONG DigiSetTrainSpeed(HFILE HChannel, ULONG ulTrain,
long slSpeed, ULONG ulDelay, ULONG ulTime);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSetTrainSpeed& Cdecl (Byval HChannel&,
Byval Train&, Byval Speed&, Byval Delay;,
Byval Time&)
- Description
- Set the speed of a train.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulTrain
- Number of the loc (decoder address).
- slSpeed
- Required speed value (range -1000..+1000).
- ulDelay
- Delay in milliseconds before execution has to start.
- ulTime
- Period in milliseconds after ulDelay to reach the desired speed.
The driver will issue autonomically at intervals the necessary commands.
- Return value
-
- 0 - command accepted
- otherwise - command discarded
- Related Functions
- DigiQueryTrainSpeed.
- Remarks
-
- The speed is used as "promilage" of the maximum speed (backward and
forward).
The specified value will be rounded to the closest decoder speedstep.
For example: when a loc runs with 14 speed steps, each step is about 7.2%% of
the maximum speed, and values between 36 and 108 will have the same result:
a speed command of '1' will be transmitted to the decoder.
DigiSleep
- Name
- DigiSleep - pause some time and yield processor
- C-language
- #include "digiapi.h"
void DigiSleep(ULONG ulInterval);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Sub DigiSleep Cdecl (Byval Interval&)
- Description
- This function provides two facilities:
- It does not return to the caller before the indicated
Interval (in milliseconds) has expired.
- In a multitasking environment (OS/2, DesqView, Windows) it releases
the processor for this task.
In the library this function is equivalent to DosSleep() in OS/2.
In the DOS-driver it is implemented as a loop.
But it respects a multitasking environment!
The pause should be specified in milliseconds.
The specified pause-interval is rounded to the next timer tick, but may
be even larger when the multitasker decides not to give control yet to
this task after expiration of the interval!
When running a DOS-program in a multitasking environment (OS/2,
Desqview, Windows, etc.), it is desirable to return control to the
multitasker, when the program does not need the processor for some time.
This part of DigiSleep() is experimental, it may not work with
all multitaskers.
The use of DigiSleep is not absolutely needed with pre-emptive
multitaskers (like OS/2), but is strongly recommended.
In all cases it reduces CPU utilisation and leaves processor time for
other tasks.
- Parameters
- ulInterval
- Time to suspend the current task.
- Return value
- Nothing.
- Related functions
- DigiSound.
- Remarks
- None.
DigiSound
- Name
- DigiSound - give a 'beep'
- C-language
- #include "digiapi.h"
void DigiSound(ULONG ulFrequency, ULONG ulDuration)
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare SUB DigiSound Cdecl (Byval Frequency&, Byval
Duration&)
- Description
- Produces a beep-tone with frequency 'freq' expressed in Hertz,
during a period 'time' expressed in milliseconds.
A beep can be stopped prematurely by calling DigiSound()
with a zero frequency, or by DigiClose().
A beep can be changed by DigiSound() with a different frequency.
This will stop any previous beep.
The tone is played in background, all processing continues without
delays or slowdown of the system.
DigiSound is implemented with DosBeep() and thus behaves exactly like it.
It is included in the OS/2 driver only for source compatibility between
OS/2 and DOS programs using DigiAPI.
The tone causes the calling thread to block for the duration of the tone.
- Parameters
- ulFrequency
- Pitch of the required tone (in Hertz).
- ulDuration
- Time in milliseconds during which the speaker will sound.
- Return value
- Nothing.
- Related Functions
- DigiSleep.
- Remarks
- Under OS/2 the function does not return until after the beep,
under DOS it returns immediately ('background' sound).
DigiStop
- Name
- DigiStop - send the 'stop' command.
- C-language
- #include "digiapi.h"
ULONG DigiStop(HFILE HChannel);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiStop& Cdecl (Byval HChannel&)
- Description
- Signal the modelrailroad to 'emergency stop'.
All commands pending for transmission will be purged.
If an error occured, DigiStop will return an error code.
Resume control is possible by a DigiGo() or manually putting the
modelrailroad in 'go' state.
- Parameters
- HChannel
- Handle to a previously opened channel.
- Return value
- Error code
- Related functions
- DigiGo
- Remarks
- The internal timer does not stop with a DigiStop().
This may cause strange effects from time-dependent calculations in your
mainline!
DigiSwitchAccessory
- Name
- DigiSwitchAccessory - switch an accessory.
- C-language
- #include "digiapi.h"
ULONG DigiSwitchAccessory(HFILE HChannel, ULONG ulAccessory
ULONG ulState, ULONG ulDelay>, ULONG ulTime);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiSwitchAccessory& Cdecl (Byval HChannel&,
Byval Accessory&, Byval State&, Byval
Delay&, Byval Time&)
- Description
- Switch an accessory.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulAccessory
- Number of the accessory
- ulState
- Indicator to switch the accessory ON or OFF.
The value 0 (zero) switches the contact OFF, a non-zero value switches the
contact ON.
- ulDelay
- Number of milliseconds to wait before actually execute the switch
operation.
- ulTime
- Number of milliseconds switching time (usually 100 milliseconds).
After this time the accessory is automatically switched back to the previous
position.
This function is typically used with pulse-operated accessories like
switchpoints (turnouts), whereby 'ulTime' is the duration of the pulse.
- Returns
- Zero means function accepted
non zero: error, DigiErrno will indicate type of error.
- Related Functions
- DigiOpen.
- Remarks.
- None.
DigiTime
- Name
- DigiTime - obtain time in milliseconds.
- C-language
- #include "DigiApi.h"
ULONG DigiTime(void);
- QuickBASIC
- ' $Include 'Digiapi.Inc'
Declare Function DigiTime& Cdecl ()
- Description
- Returns the exact time in milliseconds after the first DigiOpen() after
program start.
This function provides accurate timing.
- Parameters
- None
- Return value
- Time in milliseconds relative to program start.
- Related functions
- DigiSleep
- Remarks
- None.
DigiTrace
- Name
- DigiTrace - start or stop trace
- C-language
- #include "digiapi.h"
void DigiTrace(HFILE HChannel, ULONG ulSignal);
- QuickBASIC
- Trace facility is not provided in the driver for DOS
(thus also not for Basic).
- Description
- Start, stop or resume tracing of all data that is being sent to the and
record the information, including a timestamp into the file DigiAPI.TRC
The following actions are possible:
- With a non-zero value of signal tracing will be started.
With a positive value of signal a new tracefile will be opened.
When signal is negative new trace records will be appended to the end
of an existing trace file.
- When signal is zero the trace is stopped and the trace file
closed.
Thus tracing can be suspended if desired.
It is my intention to replace this 'on/off' switch with a trace level
facility (selection of events or data to be traced).
For outgoing commands the timestamp is the time the command is delivered to
the COM-port driver, which means it is a fraction before physical
transmission.
The utilities DIGITRC.EXE can be used to produce a formatted trace
report.
All commands are printed hexadecimal and interpreted.
See for details the appendix Trace Facility
with a sample output.
- Parameters
- HChannel
- Handle of a previously opened channel.
- ulSignal
- Signal to start trace activity (not zero), or terminate it (zero).
- Return value
- Nothing.
- Remarks
- Tracing is not provided by the DOS-drivers, but a dummy function is
provided for programs that may be compiled for OS/2 or DOS.
Error Codes
Function calls of DigiAPI may return an error code,
or the code may be stored in global variable DigiErrno.
The meaning of the returned values is explained in the table below.
Table of error codes
| Modelrailroad operational errors
|
|---|
| Error Code |
Description |
|---|
| 101 |
Attempt to transmit commands in Stopped State |
| 102 |
Timeout |
| 103 |
No License, user's trial period expired |
| 104 |
Short Cut |
| Errors with use of API function calls
|
|---|
| 201 |
No channel free - the maximum of supported channels has been
reached |
| 202 |
Protocol Not Supported |
| 203 |
Invalid handle - handle could not be related to an open channel |
| 204 |
Parameter Invalid |
| 205 |
Communications Error |
| 206 |
No memory for transmit or receive buffer |
| 207 |
Too many commands (command queue full) |
| Any other errorcode: inform author of DigiAPI
|
|---|
Manufacturer Specific Information
Support signals:
- Y - supported in 'native' mode
- N - not supported
- D - supported in a DOS-box of OS/2 and Windows 95/98.
Märklin Digital
Märklin properties
| Object |
Märklin documentation |
DigiAPI |
| Locs |
1..80 |
1..80 |
| Switchpoints and signals |
1..256 double ports decoders 1..64 with 4 double-ports each |
1..256 |
| Feedback contacts |
496 contacts 31 groups of 16 bits |
1..496
1 = contact 1 on first S88
496 = contact 16 on 31st S88 |
| Interface speed |
2400 |
any |
| Character encoding |
8,N,2 |
8,N,2 |
| Dataflow Protocol |
half duplex; CTS output flow control |
|
Lenz Digital Plus
| Object |
Lenz documentation |
DigiAPI |
| Loc |
1..99 |
1..99 |
| Switchpoints and signals |
1..256 double ports decoders 1..64 with 4 double-ports each |
1..256 |
| Feedback contact |
1024 contacts 128 encoders with 8 contacts
(note 1) |
1..1024
1 = contact 1 on encoder with address 1
512 = contact 8 on encoder with address 64 |
| Interface speed |
9600 |
any |
| Character encoding |
8,N,1 |
8,N,1 |
| Dataflow protocol |
half duplex; CTS output flow control |
|
Note 1. Feedback encoders with 16 ports use 2 addresses and are handled
as 2 encoders with 8 contacts each.
Trix Selectrix
| Object |
Trix documentation |
DigiAPI |
| Loc |
0..111 |
1..111 (address 0 not supported for locs) |
| Switchpoints and signals |
896 double ports decoders 0..111 with 8 ports each |
1..896 |
| Feedback contact |
896 contacts encoders 0..111 with 8 contacts |
1..896
1 = contact 1 on encoder with address 0
896 = contact 8 on encoder with address 111 |
| Interface speed |
9600 |
any |
| Character encoding |
8,N,2 |
8,N,2 |
| Dataflow protocol |
full duplex, no flow control |
|
Uhlenbrock Intellibox
Märklin properties
| Object |
Märklin documentation |
DigiAPI |
| Locs |
1..80 |
1..80 |
| Switchpoints and signals |
1..256 double ports decoders 1..64 with 4 double-ports each |
1..256 |
| Feedback contacts |
496 contacts 31 groups of 16 bits |
1..496
1 = contact 1 on first S88
496 = contact 16 on 31st S88 |
| Interface speed |
2400 |
any |
| Character encoding |
8,N,2 |
8,N,2 |
| Dataflow Protocol |
half duplex; CTS output flow control |
|