Application Programming Interface
and Driver
for Digital Modelrailroads

Version 2.3



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.


Table of Contents

Related publications


Overview of available Functions

List of user callable functions in alphabetically sequence


Parameter Specifications

Some semi-standard parametertypes are used with the functions, such as:

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:


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
Related functions
DigiOpen, DigiFlush
Remarks

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

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
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:

All statistics counters are set to zero with DigiOpen().

Related functions
DigiClose, DigiQueryStatistics
Remarks

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

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: 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

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

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.

    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

    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
    Related Functions
    DigiQueryTrainSpeed.
    Remarks

    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: 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

    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

    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: 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

    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

    Table of known and supported protocols
    Manufacturer and System Protocol OS/2 DOS Win 3.1 Win 95
    Märklin Digital PROTOCOL_MAERKLIN Y Y N D
    Lenz Digital Plus PROTOCOL_LENZ Y Y N D
    Märklin 6023 TRAIN-ING PROTOCOL_MAERKLIN_6023 Y Y N D
    Trix Selectrix PROTOCOL_TRIX Y Y N D
    Uhlenbrock Intellibox PROTOCOL_INTELLIBOX Y Y N D

    Support signals:

    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