Application Programming Interface
and Driver
for Digital Modelrailroads

Version 3.3


Programmers Reference Manual for DigiAPI

Rob Hamerling
Vianen, The Netherlands

E-mail: r.hamerling@hccnet.nl
homepage: http://www.robh.nl/

Copyright © R. Hamerling, 1991, 2007
All Rights Reserved.


Table of Contents

Related publications


Function Syntax Rules

C-language

For each of the user callable functions of DigiAPI the syntax is given and the parameters explained. Function prototypes for C-language are specified in the include file DIGIAPI.H, which should be included with a source calling DigiAPI functions, like:

  #include "digiapi.h"

REXX

The syntax for the REXX functions is described too. This is in most cases a one-to-one translation, with few exceptions. For REXX the DigiAPI functions should be loaded first before these are available to REXX procedures. One could use the builtin function RxAddFunc for each required DigiAPI function, but is may be more convenient to load all functions in one operation with the provided DigiLoadFuncs function, like in:

  /* Start of REXX procedure */
     call RxFuncAdd 'DigiLoadFuncs', 'DigiRexx', 'DigiLoadFuncs'
     call DigiLoadFuncs

It is recommended also to drop the DigiAPI functions and the function with which these were loaded, otherwise these remain loaded and active, which may result in unexpected effects. Example of a graceful procedure termination:

  /* End of REXX procedure */
     call DigiDropFuncs

Another recommendation is to use at least a "Signal on Halt" statement to catch Ctrl-Break situations. See the provided sample REXX procedures.

Java

For Java programs or applets the "DigiJava.Class" and "DigiJAVA.DLL" are required. An instance of the DigiJava class has to be created, for example with:

  DigiJava Channel = new DigiJava();
before you can use the DigiAPI methods of the class.

The file DigiJava.Class must be in one of the ClassPath directories.

Parameter Specifications

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

For REXX nothing special has to be defined.

For Java the equivalent Java primitives will be used.

Numbering scheme

The numbering of components by DigiAPI starts with 1. DigiAPI 'translates' these numbers to the required decoder adresses and subaddresses of each supported digital modelrailroad system.
component Description
Locs A loc number matches its decoder address. Loc number 0 is not supported!
Function numbering starts with 'light' as the rightmost bit (bit 0) in a bitstring of 32 bits. Other function bits match the normal numbering of all supported systems (extra function 1 is in bit 1, etc). A function 'on' condition is value '1'.
Turnouts
switchpoints
signals
Numbering starts with the first port on the decoder with the lowest possible decoder address (turnout 1).
SensorGroups Sensors are handled by DigiAPI in groups of 8, starting with group 1. Within a group contact 1 is represented in bit 0, contact 2 in bit 1, etc. Contact 1 (bit 0) in group 1 represents the first contact of the feedback encoder with the lowest possible decoder address or the first encoder in the chain.

Note: DigiAPI does not support a translation facility to make your own numbering scheme, this is supposed to be a function of your application.

See Manufacturer Specific Information for some more details of the address/numbering translation of DigiAPI.


Specification of Functions

The following sections contain the specifications of available functions of DigiAPI in alphabetical sequence.

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
Syntax (C)
#include "digiapi.h"
ULONG  DigiClose(HFILE Channel)
Syntax (REXX)
DigiClose(Channel);
Syntax (Java)
int  DigiClose(int Channel);
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
Channel
Handle of a previously opened channel.
Return value
  • 0 - 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. So terminate your program always 'gracefully', such as intercepting Ctrl-Break in your program to prevent uncontrolled program termination!
When using muliple channels, secundary channels should be closed first, at least before the main channel (which is by definition the first channel being opened).

DigiCloseEventQueue

Name
DigiCloseEventQueue - stop sending event signals to application
Syntax (C)
#include "digiapi.h"
ULONG  DigiCloseEventQueue(HFILE Channel);
Syntax (REXX)
DigiCloseEventQueue(Channel)
Syntax (Java)
int DigiCloseEventQueue(int Channel)
Description
Terminate queuing event signals to application and destroy the queue.
Parameters
Channel
Channel handle.
Returnvalue
Returncode of DosCloseQueue
Related functions
DigiOpenEventQueue, DigiQueryEventQueue, DigiReadEventQueue, DigiWriteEventQueue
Remarks
None.

DigiCommand

Name
DigiCommand - Send number of characters and receive system response.
Syntax (C)
#include "digiapi.h"
ULONG DigiCommand(HFILE Channel,
                  UCHAR *pCommandBuffer,
                  ULONG CommandLenght,
                  UCHAR *pReplyBuffer,
                  ULONG ReplyBufSize,
                  ULONG *pBytesReceived);
Syntax (REXX)
DigiCommand(Channel,
            CommandBuffer,
            CommandCount)
Syntax (Java)
int  DigiCommand(int Channel,
                 byte[] CommandBuffer,
                 int    CommandLength,
                 byte[] ReplyBuffer,
Description
Send a characterstring into the channel and receive the response from the modelrailroad.
Parameters
Channel
Handle of a previously opened channel.
pCommandBuffer
Buffer containing the data to be transmitted.
CommandLength
Length of the command
pReplyBuffer
Buffer in which the reply (if any) will be returned.
ReplyBufSize
Maximum number of bytes expected.
pBytesReceived
Pointer to field receiving then length of the reply.
Returnvalue
0
For REXX the reply itself (if any) is returned, which may be a binary structure, depending of the command and the protocol.
Remarks
  • This function is present for cases where none of the other functions provides the required facility, but it is severely protocol dependent, and it is recommended to use it with care, or preferably not use it at all!
  • The commandbuffer is expected to contain a complete and valid command, according to the protocol for the specified channel.
    For the Intellibox it must not be preceeded with the lead-in character, since DigiAPI works in P50X protocol only mode.
    If there is a reply it will be returned in the specified buffer. Its format and contents are protocol dependent!

DigiControlLocFunction

Name
DigiControlLocFunction - Control functions of a loc.
Syntax (C)
#include "digiapi.h"
ULONG DigiControlLocFunction(HFILE Channel,
                             ULONG Loc,
                             ULONG Function,
                             ULONG State,
                             ULONG Delay);
Syntax (REXX)
DigiControlLocFunction(Channel,
                       Loc,
                       FunctionMask,
                       Delay)
Syntax (Java)
int DigiControlLocFunction(int Channel,
                           int Loc,
                           int FunctionMask,
                           int Delay);
Description
Switches train functions (lights, coupling, smoke generator) on or off.
Parameters
Channel
Handle of a previously opened channel.
Loc
Number of train or loc (decoder address).
FunctionMask
Bitstring with function settings. Bit 0 represents the light function, bit 1 Function '1', etc. Value 0 switches functions OFF, value '1' switches functions ON. All loc functions are controlled with a single call of this function.
Delay
Number of milliseconds after which the operation has to take place (not yet supported).
Returnvalue
  • 0 - function accepted
  • errorcode - DigiErrno will indicate type of error.
Related Functions
DigiOpen.
Remarks
None

DigiControlLocSpeed

Name
DigiControlLocSpeed - Set desired speed of a train.
Syntax (C)
#include "digiapi.h"
ULONG  DigiControlLocSpeed(HFILE Channel,
                           ULONG Loc,
                           long  Speed,
                           ULONG Delay,
                           ULONG Time);
Syntax (REXX)
DigiControlLocSpeed(Channel,
                    Loc,
                    Speed,
                    Delay,
                    Time)
Syntax (Java)
int  DigiControlLocSpeed(int Channel,
                         int Loc,
                         int Speed,
                         int Delay,
                         int Time);
Description
Set the speed of a train.
Parameters
Channel
Handle of a previously opened channel.
Loc
Number of the loc (decoder address).
Speed
Required speed value (range -127..+127).
Delay
Delay in milliseconds before execution has to start (not supported yet).
Time
Period in milliseconds after Delay to reach the desired speed. The driver will issue autonomically at intervals the necessary commands (not supported yet).
Returnvalue
  • 0 - command accepted
  • otherwise - command discarded
Related Functions
DigiQueryLocSpeed.
Remarks
  • The specified value will be rounded to the closest decoder speedstep.
  • When speed is specified as '1' an emergency stop will be executed when the system and loc decoder provides such an action.

  • DigiControlTurnout

    Name
    DigiControlTurnout - switch a turnout.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiControlTurnout(HFILE Channel,
                             ULONG Turnout,
                             ULONG State,
                             ULONG Time);
    
    Syntax (REXX)
    DigiControlTurnout(Channel,
                       Turnout
                       State,
                       Time)
    
    Syntax (Java)
    int DigiControlTurnout(int Channel,
                           int Turnout,
                           int State,
                           int Time);
    
    Description
    Switch a turnout or other equivalent like a signal, lamp, relay, etc. (in general a bi-stable device).
    Parameters
    Channel
    Handle of a previously opened channel.
    Turnout
    Number of the turnout or accessory
    State
    Indicators for the position of the turnout and to switch the it ON or OFF.
    Bit 0 indicates the position: 0 = green/straight, 1 = red/branch.
    Bit 1 indicates power: 0 = Off, 1 = On.
    For example the value 3 means: select position red/branch, switch power-on.
    Time
    Number of milliseconds switching time. After this time the turnout is automatically powered-off, either implicitly by the next turnout command, or explicitly by a power-off command generated by DigiAPI. The time parameter applies to each turnout individually and the value will remain in effect until changed by another command for this turnout. When a value '0' is specified the previous time value or the system default will be taken.
    Returnvalue
    • 0 - function accepted
    • errorcode - DigiErrno will indicate type of error.
    Related Functions
    DigiOpen, DigiQueryTurnout.
    Remarks.
    For systems with a built-in turnout power-off feature - in control unit or decoder - only a power-on command will be needed, and will be the only type accepted by DigiAPI (commands with the power-bit off will be ignored). In this case either the system/decoder itself or DigAPI will take care of sending a power-off command.
    When such a system supports explicit power-off commands (like the Intellibox) the Time parameter may override the configured system value, but of course only when it is shorter than the system-configured value.

    DigiEnableSensorGroup

    Name
    DigiEnableSensorGroup - start monitoring feedback contact.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiEnableSensorGroup(HFILE Channel,
                                ULONG Group);
    
    Syntax (REXX)
    DigiEnableSensorGroup(Channel,
                          Group)
    
    Syntax (Java)
    int DigiEnableSensorGroup(int Channel,
                              int Group);
    
    Description
    DigiAPI starts monitoring the specified feedback contact group.
    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 DigiQuerySensorGroup() 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 DigiQuerySensorGroup(). If a system supports reading train-decoder information (Lenz, Trix) this will be enabled automatically for active locs after a DigiEnableSensorGroup().
    Parameters
    Channel
    Handle of a previously opened channel.
    Group
    The number of the sensor group to be monitored.
    When specified as 0 (zero) all sensor monitoring is terminated.
    Return value
    Nothing
    Related functions
    DigiQuerySensorGroup.
    Remarks
    • Some systems (like Märklin, Trix) are 'passive' and need commands to return the status of feedback contacts.
    • Other systems (like Lenz, Loconet) are 'active' and return changes in the state of feedback contacts without being asked for it.
    • The Intellibox is somewhat 'in between', it supports both 'passive' (Märklin S88s) and 'active' (LocoNet) sensors encoders at the same time. The Intellibox monitors autonomically the changes of S88s contacts. To make this work correctly at least the monitoring of sensors connected to S88s should be enabled. Loconet sensor groups are monitored anyway, enabled or not.
    • 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.
    Even for active systems DigiAPI performs active monitoring as fail safe operation.

    DigiErrno

    Name
    DigiErrno - obtain value of DigiErrno.
    Syntax (C)
      (none)
    
    REXX
    DigiErrno()
    
    Syntax (Java)
      (none)
    
    Description
    DigiErrno is a global value, directly accessible in C-programs (see header file DigiAPI.h), and in Java ???
    With REXX the value of DigiErrno is available by means of a function without parameters.
    Parameters
    (none)
    Return value
    Value of DigiErrno.
    Related functions
    (none)
    Remarks
    See Error codes for possible values and corresponding meaning.

    DigiFlush

    Name
    DigiFlush - wait until all buffered output has been transmitted.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiFlush(HFILE Channel);
    
    Syntax (REXX)
    DigiFlush(Channel)
    
    Syntax (Java)
    int DigiFlush(int Channel)
    
    Description
    Wait until all queued output has been transmitted. When buffered data is apparently not being transmitted anymore (congestion), the remaining commands in the transmit buffers will be purged and the purge statistics are updated accordingly.
    Parameters
    Channel
    Handle of a previously opened channel.
    Returnvalue
    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.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiGo(HFILE Channel);
    
    Syntax (REXX)
    DigiGo(Channel)
    
    Syntax (Java)
    int DigiGo(int Channel);
    
    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
    Channel
    Handle of a previously opened channel.
    Returnvalue
    • 0 - command accepted
    • Errorcode
    Related functions
    DigiStop, DigiHalt
    Remarks.
    None.

    DigiHalt

    Name
    DigiHalt - send the 'halt' command.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiHalt(HFILE Channel);
    
    Syntax (REXX)
    DigiHalt(Channel)
    
    Syntax (Java)
    int DigiHalt(int Channel);
    
    Description
    A 'halt'-command will be send to the Interface.
    Parameters
    Channel
    Handle of a previously opened channel.
    Returnvalue
    • 0 - command accepted
    • Errorcode
    Related functions
    DigiGo, DigiStop
    Remarks.
    When the system doesn't support an emergency Halt function a DigiStop() will be issued in stead.

    DigiOpen

    Name
    DigiOpen - start communications with the modelrailroad
    Syntax (C)
    #include "digiapi.h"
    HFILE DigiOpen(UCHAR *DevName,
                   ULONG Protocol,
                   ULONG Speed);
    
    Syntax (REXX)
    DigiOpen(DevName,
             Protocol,
             Speed)
    
    Syntax (Java)
    int DigiOpen(String DevName,
                 int    Protocol,
                 int    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). Generally this will be "COM1" or "COM2", but any valid devicename (ASCIIZ-string) is allowed.
    Protocol
    Specifies the identifier (symbolic name or number) of the desired protocol, which should be one out of the list of supported protocols. The file digiapi.h contains the list of identifiers of supported protocols.
    With REXX the protocol number should be specified.
    Speed
    Transmission speed of the serial port. Supported range: 10..115200. 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
    Handle to channel
    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 documentation

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

    Related functions
    DigiClose, DigiQueryStatistics
    Remarks
  • Currently DigiAPI supports only standard COM-ports and the standard OS/2 device driver (COM.SYS) or equivalent device drivers (like Booster.SYS). With some protocols, in particular with Loconet, it doesn't work properly with Ray Gwinn's SIO drivers.
  • 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.
  • When using multiple channels, the first channel being opened is defined as the primary or main channel. Subsequent opens are for secundary or sub- channels.

  • DigiOpenEventQueue

    Name
    DigiOpenEventQueue - start sending event signals to application
    Syntax (C)
    #include "digiapi.h"
    HFILE DigiOpenEventQueue(HFILE Channel);
    
    Syntax (REXX)
    DigiOpenEventQueue(Channel)
    
    Syntax (Java)
    int DigiOpenEventQueue(int Channel);
    
    Description
    Start queuing event signals to be processed by application.
    Parameters
    Channel
    Channel handle.
    Returnvalue
    Handle to event queue.
    Related functions
    DigiCloseEventQueue, DigiQueryEventQueue, DigiReadEventQueue, DigiWriteEventQueue
    Remarks
  • When application does not process the signals fast enough DigiAPI will purge event signals.
  • ??

  • DigiPurge

    Name
    DigiPurge - purge output buffer
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiPurge(HFILE Channel);
    
    Syntax (REXX)
    DigiPurge(Channel)
    
    
    Syntax (Java)
    int DigiPurge(int Channel);
    
    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
    Channel
    Handle of a previously opened channel.
    Returnvalue
    zero (or invalid handle)
    Related functions
    DigiFlush
    Remarks.
    None.

    DigiQueryEventQueue

    Name
    DigiQueryEventQueue - Obtain number of unprocessed events.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiQueryEventQueue(HFILE Channel);
    
    Syntax (REXX)
    DigiQueryEventQueue(Channel)
    
    Syntax (Java)
    int DigiQueryEventQueue(int Channel);
    
    Description
    Returns number of events currently queued for processing by the application.
    Parameters
    Channel
    Handle of a previously opened channel.
    Returnvalue
    Number of events.
    Related functions
    DigiCloseEventQueue, DigiOpenEventQueue, DigiReadEventQueue, DigiWriteEventQueue
    Remarks
    None.

    DigiQueryLocFunction

    Name
    DigiQueryLocFunction - Obtain current setting of a train function
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiQueryLocFunction(HFILE Channel,
                               ULONG Loc);
    
    Syntax (REXX)
    DigiQueryLocFunction(Channel,
                         Loc)
    
    Syntax (Java)
    int DigiQueryLocFunction(int Channel,
                             int Loc);
    
    Description
    Returns current state of the train function settings.
    Parameters
    Channel
    Handle of a previously opened channel.
    Loc
    Number of the train or loc (decoder address).
    Return
    Function settings in a 32-bit string right to left. Function 0 is the rightmost bit, function 1 is the one left of 1, etc.
    Related functions
    None.
    Remarks
    Function number 0 is the 'auxiliary' function which is in most systems imbedded in the speed command, while functions 1 .. 4 (and higher) are the 'extra' functions.

    DigiQueryLocSpeed

    Name
    DigiQueryLocSpeed - Obtain current speed of a train
    Syntax (C)
    #include "digiapi.h"
    signed long DigiQueryLocSpeed(HFILE Channel,
                                  ULONG Address);
    
    Syntax (REXX)
    DigiQueryLocSpeed(Channel,
                      Address)
    
    Syntax (Java)
    int DigiQueryLocSpeed(int Channel,
                          int Address);
    
    Description
    Returns current speed of train (value in ranges -127..-1 and +1..+127) A positive values implies forward, negative backward. Values +1 and -1 mean that the actual speed is zero!
    Parameters
    Channel
    Handle of a previously opened channel.
    Address
    Number of the train or loc (decoder address).
    Returnvalue
    Current speed of the loc in the range -127 to +127.
    Related Functions
    DigiControlLocSpeed.
    Remarks
    The returned value is rounded as discussed with DigiControlLocSpeed. 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.
    The value +1 should be interpreted as "speed zero forward", and the value -1 as speed zero backward.

    DigiQueryOption

    Name
    DigiQueryOption - Obtain option value
    Syntax (C)
    #include "digiapi.h"
    long int DigiQueryOption(HFILE Channel,
                             ULONG Option);
    
    Syntax (REXX)
    DigiQueryOption(Channel,
                    Option)
    
    Syntax (Java)
    int DigiQueryOption(int Channel,
                        int Option);
    
    Description
    Returns value of a system option.
    Parameters
    Channel
    Handle of a previously opened channel.
    Option
    Number of the option.
    Returnvalue
    Current value of the specified option.
    Related Functions
    None.
    Remarks
    The returned value is the current value of a system option. This function is practically only useful with an Uhlenbrock Intellibox, in which case the value of the corresponding 'Special Option' will be returned. For most other systems a zero value will be returned.

    DigiQuerySensorGroup

    Name
    DigiQuerySensorGroup - get bit-pattern of a group of contacts
    Syntax (C)
    #include "digiapi.h"
    UCHAR DigiQuerySensorGroup(HFILE Channel,
                               ULONG Group);
    
    Syntax (REXX)
    DigiQuerySensorGroup(Channel,
                         Group)
    
    Syntax (Java)
    int DigiQuerySensorGroup(int Channel,
                             int Group);
    
    Description
    Get the status of a sensor group (8 bits).
    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 '6' as group number.
    When DigiQuerySensorGroup() is called with parameter value 0 (zero), all settings will be reset to zero, and a zero will be returned.
    Sensor monitoring will have to be started first with DigiEnableSensorGroup() before the result of DigiQuerySensorGroup 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
    Channel
    Handle of a previously opened channel.
    Group
    Number of the group of 8 bit contacts (feedback decoder number).
    Returnvalue
    A single byte (8-bit) containing the cumulated sensor contact 'on' status. Sensor numbering is from left to right (the leftmost bit is contact 1 of the group).
    Related functions
    DigiEnableSensorGroup
    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.
  • The 'ON' signals of feedback encoders are cumulated until a DigiQuerySensorGroup() 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 DigiQuerySensorGroup() is issued by the mainline, it may be necessary to issue DigiQuerySensorGroup() twice.
      With REXX a string of '0' and '1' characters is returned.

  • DigiQueryStatistics

    Name
    DigiQueryStatistics - obtain content of statistics counter.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiQueryStatistics(HFILE Channel,
                              ULONG Counter);
    
    Syntax (REXX)
    DigiQueryStatistics(Channel,
                        Counter)
    
    Syntax (Java)
    int DigiQueryStatistics(int Channel,
                            int 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
    Channel
    Handle of a previously opened channel.
    Counter
    Number of the counter (see table below).

    Parm
    Symbol
    Parm
    Value
    Statistics Description
    DIGI_STAT_CMD 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!
    DIGI_STAT_SEN 2 Number of internally generated commands for monitoring purposes (like for reading feedback encoders).
    DIGI_STAT_DSC 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.
  • DIGI_STAT_QUE 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) 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.
    DIGI_STAT_PRG 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!
  • DIGI_STAT_XMT 6 Number of bytes actually transmitted.
    DIGI_STAT_RCV 7 Number of bytes actually received (feedback data and/or status messages).
    DIGI_STAT_TRC 8 Number of trace records written.

    Specifying a counter number outside the indicated range will give unpredictable results.
    Returnvalue
    Contents of the specified counter (zero after reset).
    Related functions
    DigiOpen
    Remarks.
    None.

    DigiQueryState

    Name
    DigiQueryState - obtain actual system status information.
    Syntax (C)
    #include "digiapi.h"
    ULONG  DigiQueryState(HFILE Channel);
    
    Syntax (REXX)
    DigiQueryState(Channel)
    
    Syntax (Java)
    int DigiQueryState(int Channel);
    
    Description
    Obtain actual system status. The function returns the actual values of system state variables in the form of a bitstring.
    Parameters
    Channel
    Handle of a previously opened channel.
    Return value
    Bitstring representing system state. The following bits are defined:
    DIGISTARTED          0x80000000       Communications started
    DIGIDRIVERACTIVE     0x40000000       Protocol driver activated
    DIGICONNECTED        0x20000000       MRR Interface connected
    DIGITERMINATING      0x10000000       Termination in progress
    DIGITRIALTIME        0x08000000       DigiAPI trial runtime expired
    DIGINORESPONSE       0x00800000       Interface not responding
    DIGISTOPSTATE        0x00200000       stop-state ('STOP' command)
    DIGIHALTSTATE        0x00100000       halt-state (general 'HALT' cmd)
    DIGIMONITORING       0x00010000       Monitoring thread started
    DIGITURNOUTACTIVE    0x00008000       Turnout command service started
    DIGITURNOUTMOT       0x00000100       Turnout MOT protocol running
    DIGITURNOUTDCC       0x00000200       Turnout DCC protocol running
    DIGILOCACTIVE        0x00000080       Loc command service started
    DIGILOCMOT           0x00000001       Locthread MOT protocol running
    DIGILOCDCC           0x00000002       Locthread DCC protocol running
    DIGILOCSX            0x00000004       Locthread SX protocol running
    DIGILOCFMZ           0x00000008       LocThread FMZ protocol running
    
    Related functions
    None.
    Remarks.
  • The header file "digiapi.h" contains the symbolic names of the bit assignments for C-language.
  • 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.

  • DigiQueryTime

    Name
    DigiQueryTime - obtain time in milliseconds.
    Syntax (C)
    #include "DigiApi.h"
    ULONG DigiQueryTime(void);
    
    Syntax (REXX)
    DigiQueryTime()
    
    Syntax (Java)
    int DigiQueryTime();
    
    Description
    Returns the exact time in milliseconds after the first DigiOpen() after program start. This function provides accurate timing.
    Parameters
    None
    Returnvalue
    Time in milliseconds relative to program start.
    Related functions
    DigiSleep
    Remarks
    None.

    DigiQueryTurnout

    Name
    DigiQueryTurnout - obtain current position of an accessory, switch or signal.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiQueryTurnout(HFILE Channel,
                           ULONG Turnout);
    
    Syntax (REXX)
    DigiQueryTurnout(Channel,
                     Turnout)
    
    Syntax (Java)
    int DigiQueryTurnout(int Channel,
                         int Turnout);
    
    Description
    Returns current state of an accessory.
    Parameters
    Channel
    Handle of a previously opened channel.
    Turnout
    Turnout number.
    Return value
    State of the accessory.
    Bit 0 indicates the position: 0 = green/straight, 1 = red/branch.
    Bit 1 indicates the state: 0 = power-off, 1 = power-on.
    Related functions
    DigiControlTurnout.
    Remarks
    None.

    DigiQueryVersion

    Name
    DigiQueryVersion - obtain system firmware version
    Syntax (C)
    #include "digiapi.h"
    char *DigiQueryVersion(HFILE Channel,
                           char  *Buffer,
                           ULONG BufSize);
    
    Syntax (REXX)
    DigiQueryVersion(Channel)
    
    Syntax (Java)
    String DigiQueryVersion(int Channel);
    
    Description
    Returns a string with version information. The layout of the string is system dependent.
    Parameters
    Channel
    Handle of a previously opened channel.
    Buffer
    Pointer to a bufer to receive the version string.
    BufSize
    Size of the buffer.
    Returnvalue
    Pointer to the formatted buffer, (with REXX a string with version information is returned).
    Related functions
    None.
    Remarks
    This function gives real version information only when the particular system supports a command to obtain the version. In other cases a dummy string is returned, or the version of the system or protocol which DigiAPI supports.

    DigiReadEventQueue

    Name
    DigiReadEventQueue - read a queued event.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiReadEventQueue(HFILE Channel,
                             void  *Buffer,
                             ULONG BufSize,
                             ULONG *BytesReceived);
    
    DigiReadEventQueue(Channel)
    
    Syntax (Java)
    byte[] DigiReadEventQueue(int Channel);
    
    Description
    Receive event information.
    Parameters
    Channel
    Handle of a previously opened channel.
    Buffer
    pointer to a receive buffer.
    BufSize
    Size of the receive buffer.
    BytesReceived.
    Actual number of bytes returned in buffer.
    The contents and format of events has not been documented yet, since this facility is "under contruction".
    Returnvalue
    Return code, indicating success of read.
    With REXX the event information is returned (null if not available).
    Related functions
    DigiCloseEventQueue, DigiOpenEventQueue, DigiQueryEventQueue, DigiWriteEventQueue
    Remarks
    None.

    DigiReset

    Name
    DigiReset - restart communications with the model railroad system.
    Syntax (C)
    #include "digiapi.h"
    ULONG  DigiReset(HFILE Channel,
                     ULONG Type);
    
    Syntax (REXX)
    DigiReset(CHannel,
              Type)
    
    Syntax (Java)
    int DigiReset(int Channel,
                  int Type);
    
    Description
    This function is mainly useful for the Intellibox.
    Parameters
    Channel
    Handle of a previously opened channel.
    Type
    Type of reset action to be taken:
    0 - Send break to Interface
    1 - Soft reset of Interface (P50X command '@')
    2 - Hard reset of Interface (P50X command '@@')
    Returnvalue
    Returncode indicating if reset was successful (meaning communications was re-established successfully).
    Related functions
    None.
    Remarks
    None.

    DigiSleep

    Name
    DigiSleep - pause some time and yield processor
    Syntax (C)
    #include "digiapi.h"
    void DigiSleep(ULONG Interval);
    
    Syntax (REXX)
    DigiSleep(Interval)
    
    Syntax (Java)
    void DigiSleep(int Interval);
    
    Description
    This function provides two facilities:
    • It does not return to the caller before the indicated Interval (in milliseconds) has expired.
    • It releases the processor for this task.
    The pause should be specified in milliseconds. The specified pause-interval is exact (the high resolution timer device driver is user (TIMER0.SYS), but may be larger when other threads with higher priority are busy or ready.
    Parameters
    Interval
    Time to suspend the current task.
    Returnvalue
    Nothing.
    Related functions
    None.
    Remarks
    None.

    DigiStop

    Name
    DigiStop - send the 'stop' command.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiStop(HFILE Channel);
    
    Syntax (REXX)
    DigiStop(Channel)
    
    Syntax (Java)
    int DigiStop(int Channel);
    
    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
    Channel
    Handle to a previously opened channel.
    Returnvalue
    Error code (normally 0)
    Related functions
    DigiGo, DigiHalt
    Remarks
    The internal timer does not stop with a DigiStop(). This may cause strange effects from time-dependent calculations in your mainline!

    DigiTrace

    Name
    DigiTrace - start or stop trace
    Syntax (C)
    #include "digiapi.h"
    void DigiTrace(HFILE Channel,
                   ULONG Signal);
    
    Syntax (REXX)
    DigiTrace(Channel,
              Signal)
    
    Syntax (Java)
    void DigiTrace(int Channel,
                   int Signal);
    
    Description
    Start, stop or resume tracing of all data that is being sent to the and record the information, including a timestamp into a trace file. The filename represents the protocol (Lenz, Loconet, Marklin, P50X, Trix), the extension indicates the channel (TR1, TR2, etc).
    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 utility 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
    Channel
    Handle of a previously opened channel.
    Signal
    Signal to start trace activity (not zero), or terminate it (zero).
    Returnvalue
    Nothing.
    Related functions
    None.
    Remarks
    None.

    DigiWriteEventQueue

    Name
    DigiWriteEventQueue - queue an event for later processing.
    Syntax (C)
    #include "digiapi.h"
    ULONG DigiWriteEventQueue(HFILE Channel,
                              void  *Buffer,
                              ULONG CommandCode,
                              ULONG DataLength);
    
    Syntax (REXX)
    DigiWriteEventQueue(Channel,
                        Buffer,
                        CommandCode,
                        DataLength)
    
    Syntax (Java)
    int DigiWriteEventQueue(int    Channel,
                            byte[] Buffer,
                            int    CommandCode,
                            int    DataLength);
    
    Description
    Write event information to event queue.
    Parameters
    Channel
    Handle of a previously opened channel.
    Buffer
    pointer to an event buffer buffer.
    CommandCode
    Code of the related command (system/protocol dependent).
    Datalength
    Number of bytes of the event information.
    Returnvalue
    Return code, indicating success of write.
    Related functions
    DigiCloseEventQueue, DigiOpenEventQueue, DigiQueryEventQueue, DigiReadEventQueue
    Remarks
    None.

    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
    105 Protocol driver loading failure
    106 Interface not ready
    107 Interface not responding
    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)
    208 High resolution timer not installed, or not functioning. Check DEVICE=TIMER0.SYS is specified in Config.Sys (Warp 4.0+)
    Internal DigiAPI errors
    301 Function not supported
    302 Command queue overflow
    303 User not registered
    304 Trial period exceeded
    305 Invalid channel
    306 Invalid command for the channel protocol
    Any other errorcode: inform author of DigiAPI

    Event Signals

    Event signals ..... (to be provided later)


    Manufacturer Specific Information

    The following sections give an overview how DigiAPI supports the different brands of digital modelrailroad systems.

    DigiAPI currently supports the following protocols:
    Identifier Symbolic name Description
    1 PROTOCOL_MARKLIN Marklin Digital and Delta
    2 PROTOCOL_LENZ Lenz Digital Plus
    11 PROTOCOL_TRIX Trix Selectrix
    16 PROTOCOL_DIGITRAX
    PROTOCOL_LOCONET
    Digitrax Loconet with DigiTrax MS-100
    18 PROTOCOL_INTELLIBOX
    PROTOCOL_P50X
    Uhlenbrock Intellibox (P50X)
    20 PROTOCOL_LOCOBUF Digitrax Loconet with LocoBuffer of John Jabour
    functionally identical to PROTOCOL_LOCONET

    Märklin Digital

    Object Märklin documentation DigiAPI
    Locs 1..80 1..255
    Turnouts 1..256 double ports 1..256
    Sensors 496 contacts
    31 encoders with 16 contacts each
    1..62
    group 1 is contacts 1..8 of of first S88
    group 62 is contacts 9..16 of last S88
    Interface speed 2400 any, default 2400
    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 (V.2)
    1..9999 (V.3)
    1..255 (higher addresses not yet supported by DigiAPI)
    Turnouts 1..256 (V2)
    1..1024 (V.3)
    1..1024
    Contact Sensors 1024 contacts
    128 encoders with 8 contacts each (Note 1)
    1..128 sensor groups
    group 1 is encoder 1
    group 128 is encoder 128
    Interface speed 9600, 19200 (LI-100F) any, default 9600
    Character encoding 8,N,1 8,N,1
    Dataflow protocol half duplex; CTS output flow control

    Notes

  • Feedback encoders with 16 ports use 2 addresses and are handled as 2 groups with 8 contacts each.

    Trix Selectrix


    Turnout 1 is connected to port 1 of decoder with address 0.
    Turnout 896 is connected to port 8 of decoder with address 111.
    Formula: TurnoutNumber = DecoderAddress * 8 + PortNumber
    Object Trix documentation DigiAPI
    Loc 0..111 1..111 (address 0 not supported for locs)
    Turnouts 896 double ports
    decoders 0..111 with 8 ports each
    1..896
    Sensor groups 896 contacts
    encoders 0..111 with 8 contacts each
    1..112
    group 1 contains contacts 1 to 8 of encoder with address 0.
    group 112 contains contacts 1 to 8 of encoder with address 111.
    Formula: SensorGroup = DecoderAddress + 1.
    Interface speed 9600 any, default 9600
    Character encoding 8,N,2 8,N,2
    Dataflow protocol full duplex; no flow control

    DigiTrax Loconet

    This section applies to the Loconet attachment of the Uhlenbrock Intellibox, with a computer connection by a DigiTrax MS-100 or a LocoBuffer device of John Jabour or LocoBuffer-II by Dick Bronson.
    Object Digitrax documentation DigiAPI
    Locs 1..9999 1..255
    Turnouts 1..256 double ports
    decoders 1..64 with 4 double-ports each
    1..256
    Sensor contacts 1024 contacts
    128 encoders with 8 contacts each
    1..128
    group 1 is contacts 1..8 on first encoder
    group 128 is contacts 1..8 on last endocer
    Interface speed 16457 with MS-100;
    19200, 57600 with LocoBuffer
    16457 with MS-100;
    57600 with LocoBuffer
    Character encoding 8,N,1 8,N,1
    Dataflow Protocol full duplex;
  • with MS-100: carrier sense and collision detection
  • with LocoBuffer: CTS flow control
  • Uhlenbrock Intellibox

    Object Intellibox documentation DigiAPI
    Locs 1..9999 1..255 (high adresses not yet supported by DigiAPI)
    Turnouts 1..256 double ports
    decoders 1..64 with 4 double-ports each
    1..256
    Sensor contacts 496 contacts
    31 encoders with 16 contacts each
    1..62
    group 1 is contacts 1..8 of first S88
    group 62 is contacts 9..16 of last S88
    Interface speed 2400, 4800, 9600, 19200, 38400 any, default 19200
    Character encoding 8,N,2 8,N,2
    Dataflow Protocol full duplex; CTS output flow control half duplex; no CTS flow control (Note 1)

    Note 1. The Intellibox is handled by DigiAPI as a half duplex device: a command is not sent before the reply of a previous command has completely arrived. Since the primary receive buffer of the Intellibox is 8 bytes and no command exceeds this length, CTS flow control can be safely ignored. However CTS is checked before sending each command.


    End of DigiAPI Programming Reference Manual