Open Rails

Additional signal script functions

Registered by r.roeterdink on 2017-02-07

This blueprint proposes to introduce a series of additional signal script functions.
This also includes the functions linked to the proposed introduction of signal variables as well as the proposed introduction of subtypes for NORMAL signals, see the relevant blueprints on these proposals for details.

Functions using signalid as identification for the signal from which information is required.

As detailed in the blueprint on the introduction on signal variables, it may be necessary to gather multiple items on information from another signal. To avoid unnecessary repetitive search actions to identify the required signal, functions have been made available which can retreive the required information through use of the signal ident.

Functions to obtain the signal ident :

* sigid = next_sig_id(SIGFN_Type) : returns the ident of the next signal of type SIGFN_Type
* sigid = next_nsig_id(SIGFN_Type, <n>) : returns the ident of the nth next signal of type SIGFN_Type
* sigid = opp_sig_id(SIGFN_Type, <n>) : returns the ident of the next signal of type SIGFN_Type in opposite direction

Functions using signal ident equivalent to existing functions :

* state = id_sig_enabled(sigid) : returns the ‘enabled’ state of signal identified by sigid,
value = 1 if signal is enabled, otherwise 0
* sigasp = ID_SIG_LR(sigid) : returns the least restrictive aspect as set by the signal identified by sigid

Functions related to signal variables :

* store_lvar(key, value) : store a value in variable identified by key
* value = this_sig_lvar(key) : retrieve value linked to this signal identified by key
* value = next_sig_lvar(SIGFN_Type, key) : retrieve value of next signal of type SIGFN_Type, identified by key
* value = id_sig_lvar(sigid, key) : retrieve value of signal identified by sigid, value is identified by key.

Functions to adjust the SignalNumClearAhead values:

* increase_signalnumclearahead(n) : increases SignalNumClearAhead by value n
* decrease_signalnumclearahead(n) : decreases SignalNumClearAhead by value n
* set_signalnumclearahead(n) : sets SignalNumClearAhead to value n
* reset_signalnumclearahead() : resets SignalNumClearAhead to the value specified in the signal type definition.

Note that the functions which increase or decrease the value of SignalNumClearAhead use the default value as specified in the signal type definition as the actual value, so, for instance, repetitive calls to increase_signalnumclearahead does not further increase the value each time it is called.

Functions to query the subtype of a NORMAL signal :

* state = this_sig_hasnormalsubtype(ORSUBTYPE_type) : queries if this signal has subtype ORSUBTYPE_type;
    state = 1 if the signal has this subtype, otherwise state = 0
* state = next_sig_hasnormalsubtype(ORSUBTYPE_type) : queries if next NORMAL signal has subtype ORSUBTYPE_type;
    state = 1 if the signal has this subtype, otherwise state = 0
* state = id_sig_hasnormalsubtype(sigid, ORSUBTYPE_type) : queries if signal identified by sigid has subtype ORSUBTYPE_type;
    state = 1 if the signal has this subtype, otherwise state = 0

Additional Approach Control functions :

* approach_control_position_forced(distance) : will clear signal when train is at required distance,
    regardless of any signals inbetween train and this signal
    (normal approach control will only clear if signal is first signal ahead of train)
* approach_control_lock_claim() : will lock the train’s claim ability
    (normally if a train approach a signal at danger it will try to claim the track sections beyond the signal)

Other functions :

* allow_clear_to_partial_route() : allows the signal to clear to a partial route
    (i.e. not reaching end of track or next signal) if signal is propagated
    (normally a signal will only clear to a partial route if it is the first signal ahead of the train)
* state = train_requires_next_signal(sigid, position) :
    checks if the route of the train approaching this signal runs as for as the signal identified by sigid.
    If position = 0, it is checked if the route reaches the required signal;
    if position = 1; it is checked if the route extends beyond the required signal.
    The returned state = 1 if the route does extend as indicated, otherwise state = 0;
* sigid = find_req_normal_signal(ORSUBTYPE_type) :
    searches along the train’s route to locate the next normal signal with subtype ORSUBTYPE_type,
    if found, the return value is the ident of that signal, otherwise sigid = -1.
    Note that this function uses the train’s route to locate the signal, and not the route as may presently be set beyond the signal.
* state = route_cleared_to_signal(sigid) :
    checks if the full route upto signal identified by sigid, has been cleared for the train which is approaching the signal
    (i.e. for which the signal is enabled).
    Function returns BLOCK_CLEAR if route is fully available, otherwise the value BLOCK_JN_OBSTRUCTED is returned.
* state = route_clear_to_signal_callon(sigid) :
    as above, but also checks if callon is allowed if the route is occupied.
    Function returns BLOCK_CLEAR if route is fully available, BLOCK_JN_OBSTRUCTED if route is not available at all,
    and returns BLOCK_OCCUPIED if part of the route is occupied by call-on is allowed.
* this_sig_noupdate() : calling this function will exclude this signal for the normal update sequence.
    This can be used for signals which have a fixed setting, e.g. speed signals or signals at end of track.
    Note that the script for such signals is always executed once so the required state will always be set.
    Setting the option not to update the signal reduces the overall program load.