Error codes¶
Every refusal and every check() finding names its rule in code.
The tables below list every code.
from laddercodec import Coil, FieldError
try:
Coil("X001")
except FieldError as error:
print(error.code, error.click_id, error.field)
# bank-not-allowed OBJ-004 Coil.operand
code is a Code, a string enum. Each code compares equal to its name, so
error.code == "bank-not-allowed" is true, and Code.BANK_NOT_ALLOWED is the same code.
A FieldError lists every refusal of one construction in errors, and each refusal has
its own code. A Finding from check() also has a code.
click_id is CLICK's own id for the error, such as OBJ-004 or C0202. It is None
when CLICK has no id for the error or when no id is known. One code can come with several
ids, and the tables list the ids that are known. A blank-field refusal has the id of the
check that refused the blank.
Operand rules¶
These rules are the same in every instruction. field names the field.
| Code | Meaning | CLICK id |
|---|---|---|
blank-field |
A field that needs a value is blank. | |
not-an-address |
Text that is no CLICK address or names no bank, or a value that is not text. | OBJ-002, OBJ-003, OBJ-004, OBJ-005 |
address-out-of-range |
A number outside its bank (DS5000, X017). |
OBJ-002, OBJ-003 |
bank-not-allowed |
An address in a bank the field doesn't take. | OBJ-003, OBJ-004 |
upper-byte-not-allowed |
XD0u or YD0u in a field that takes no upper byte. |
|
not-click-form |
A stored value in a form that CLICK never writes. It is an address, a Math keypad name or a Math hex constant that is not in display form (x1, sqrt), or a numeric tag that holds no number. A decoder keeps such a blob raw. |
|
not-writable |
An address the instruction can't write: a read-only SC bit, an SD outside the writable list, or a Send to a read-only Modbus type. | OBJ-003, OBJ-004, OBJ-018 |
pointer-outside-copy |
A pointer in any field but a single Copy's source or destination. | |
pointer-bank-not-allowed |
A pointer to a bank the field's pointer can't address. | OBJ-004 |
pointer-not-ds |
A pointer whose index is no DS address. | |
constant-kind-not-allowed |
A constant of a kind the field doesn't take, or a Python value of the wrong type, such as 2.5 for a Send or Receive quantity. |
|
not-a-constant |
Text read as neither an address nor a constant. | |
constant-out-of-range |
A constant outside the field's limits (its value, hex digits, float32, text length or typed length), or a minus sign where the field's lowest value is 0 or more. | OBJ-005, OBJ-023 |
invalid-constant |
A constant in a form the field refuses: a + where no sign is taken, a sign before hex, a space in a count, a real with more significant digits than CLICK keeps, or a hex constant that spells a bank name (DH) in Compare's Data B opposite a hex Data A. |
OBJ-005 |
invalid-char-code |
A $hh or a termination code that is no character code. |
OBJ-036 |
invalid-text-constant |
Quoted text holding a quote or a character CLICK doesn't keep. | |
not-a-flag |
A flag that is not True, False, 1 or 0. | |
invalid-choice |
Not one of the field's named values: a unit, type, op, format, kind, port, function code, stop or pattern cell. |
Shared rules¶
These rules apply to several instructions. invalid-subroutine-name and duplicate-subroutine-name apply to subroutine names in write_bundle and read_bundle. For duplicate-subroutine-name, write_bundle raises a CsvWriteError and read_bundle raises a CsvReadError, and field is None.
| Code | Meaning | CLICK id |
|---|---|---|
option-not-offered |
A field or option CLICK's dialog greys out for the other fields' values. | |
range-mixed-banks |
A range whose two ends are in two banks. | OBJ-008 |
range-not-ascending |
A range that ends below its start, such as C5..C1. |
OBJ-009 |
range-crosses-slot |
An X or Y range that crosses a 16-point slot. | OBJ-033, OBJ-1009 |
duplicate-address |
Two fields that must differ name one address, such as the two ends of the range C1..C1. |
OBJ-012, OBJ-014 |
timer-pair-mismatch |
A timer's or counter's done bit and accumulator with different numbers, such as T1 with TD2. |
|
immediate-contact-not-x |
An immediate contact outside X. | |
immediate-coil-not-y |
An immediate coil outside Y. | |
immediate-edge-contact |
Immediate on a rise or fall contact. | |
immediate-not-allowed |
Immediate on an instruction with no immediate form. | |
text-order-compare |
< or > on text, in a Compare or a Search. |
|
invalid-subroutine-name |
A subroutine name that is not text, is over 24 characters, holds a forbidden character or is a device name. | GUI-040 |
duplicate-subroutine-name |
Two subroutine names that are equal when the case of A-Z is ignored, such as Pump and pump. |
GUI-036 |
invalid-input-rows |
pin_rows that is not one ascending row (1 to 255) per box input. |
Copy family¶
Copy, Block Copy, Fill, Pack and Unpack.
| Code | Meaning | CLICK id |
|---|---|---|
copy-bank-incompatible |
A source bank or kind that can't copy into this destination bank. | OBJ-004, OBJ-024 |
constant-into-bit |
A single Copy of a constant into a bit address. | OBJ-004, OBJ-024 |
copy-converter-bank |
A converter the source and destination kinds don't offer. | |
copy-txt-needs-convert |
A single Copy between TXT and a number, or a Block Copy from TXT into numbers, with no converter. | |
copy-hex-reads-as-real |
A Copy source EH or 1EH. CLICK reads either one as a real. |
|
text-past-bank |
Text a Copy writes that runs past TXT1000. | OBJ-003 |
block-copy-end-mismatch |
A Block Copy dest_end that is not where the copy ends. |
|
pack-kind-mismatch |
A Pack or Unpack kind (bits, words or text) that doesn't match the bank. | |
pack-too-many |
A Pack source or Unpack destination past its count limit. | OBJ-003, OBJ-027, OBJ-032, OBJ-039, OBJ-040, OBJ-041, OBJ-042 |
Math¶
These rules apply to the formula of a Math instruction.
| Code | Meaning | CLICK id |
|---|---|---|
math-nickname |
A formula that holds a <nickname>. |
|
math-invalid-token |
A word or character that is no formula part, or a formula that is not text. | OBJ-1001 |
math-constant-kind |
A hex constant in a decimal Math, a constant without an h in a hex Math, or a text constant in any Math. |
OBJ-1001 |
math-constant-out-of-range |
Hex over 4 digits, a real past float32 or with more digits than CLICK keeps, an integer past int32, or leading zeros. | OBJ-1009 |
math-nesting-depth |
Parentheses more than 8 deep. | OBJ-1010 |
math-unbalanced-parens |
A ) with no (, or a ( with no ). |
OBJ-1004, OBJ-1005 |
math-function-mode |
A function, an operator or PI that only the other mode's keypad has, such as SIN in a hex Math or XOR in a decimal Math. |
OBJ-1006 |
math-syntax-error |
A formula with tokens out of order, a comma outside a call, : outside a range function, or a wrong first or last token. |
OBJ-1001, OBJ-037 |
math-arg-expression |
A function argument that is not one address or constant. | OBJ-1001 |
random-bound-type |
A RAND bound that is a real, or in a bank RAND doesn't take. | OBJ-1001, OBJ-1002 |
random-equal-bounds |
RAND with equal bounds. | OBJ-1001 |
math-operand-bank |
An address outside a SUM range, in a bank that the Math mode doesn't take. A decimal Math takes bit addresses only in a SUM range. |
OBJ-1002 |
sum-bank-unavailable |
SUM over a bank SUM doesn't read. | OBJ-1002 |
math-range-mixed-banks |
An a : b range in two banks. |
OBJ-1015 |
math-range-not-ascending |
An a : b range that runs high to low. |
OBJ-1014 |
median-range-too-large |
MDN over more than 1024 bytes. | OBJ-1013 |
sum-option-slot |
An X or Y SUM range with an end in the option slot. | |
math-formula-too-long |
A formula longer than 270 characters in the internal form that CLICK stores. | OBJ-1008 |
Other instructions¶
Compare, Search, Out variants, Drum, Send and Receive, For, and laddercodec's own types.
| Code | Meaning | CLICK id |
|---|---|---|
compare-mixed-types |
Compare operands in different groups (hex, numeric, text). | OBJ-007 |
search-value-bank |
A Search value whose kind or compare group doesn't search the table's bank. | OBJ-004 |
coil-time-unit |
An Out variant with a time unit its kind lacks. | |
debounce-needs-phase |
A debounce with neither phase filled. | OBJ-006 |
drum-size-out-of-range |
Drum steps or outputs outside 1 to 16. | |
drum-pattern-shape |
A drum pattern or event list that doesn't match its steps and outputs. | |
drum-step-empty |
A drum step with no event or duration. | OBJ-021, OBJ-022, OBJ-1019 |
function-code-mismatch |
A Modbus function code that doesn't fit the remote type or the count. | OBJ-004 |
count-out-of-range |
A Send or Receive count past its cap or room, or an odd TXT count. | OBJ-010, OBJ-029 |
txt-start-not-odd |
A Send of TXT that starts at an even address, such as TXT1000. |
OBJ-028 |
remote-address-out-of-range |
A remote start outside the MODBUS 984 ranges, or past FFFDh. | OBJ-010 |
invalid-modbus-target |
A Modbus target with a bad device_id, IP or port, or a Send or Receive target that is no Modbus target. | |
for-count-bank |
A For loop count in a bank the count doesn't take. | OBJ-004 |
invalid-token |
A CSV token that doesn't follow its instruction's syntax. | |
invalid-raw |
A RawInstruction field with a value of the wrong type or out of range, or a raw(...) token whose rows= does not fit its pins=. |
|
invalid-undecoded |
An Undecoded field refused. |
|
invalid-tee |
A Tee built around something other than one contact. |
|
invalid-circuit |
A Series, Parallel, Box, Branch or Circuit built from a part it doesn't take, such as a Parallel with one leg, an empty Series outside a Parallel, or a pin that the box doesn't use. |
check() findings¶
check() reports these.
| Code | Meaning | CLICK id |
|---|---|---|
not-series-parallel |
A circuit that is not series-parallel. | C0001 |
no-rail |
A contact whose input no rail reaches. | C0202 |
feeds-no-box |
A contact that feeds no box. | C0202 |
no-coil |
A path from the rail that reaches no box. | C0003 |
contact-feeds-only-nop |
A contact that feeds a NOP and no other box. | C0003 |
unwired-input |
A box input (a Reset input, a Down input, ...) that no rail or contact reaches. | C0202 |
output-above-box-inputs |
A box above a lower box that uses an input row, such as a .reset() row, where the upper box's main input is on the lower box's main input circuit. That is the lower box's main input net, or a net that its main input circuit runs through from the rail. The rail reaches that net through a contact. |
C000A |
shared-input-net |
A box input whose net another input shares. | C000A |
input-without-contact |
A box input with no contact of its own. | C0205, C0212 |
input-shares-enable |
A box input whose circuit shares contacts with an enable. | |
inputs-share-contacts |
A box input whose circuit shares contacts with another box input. | |
unpowered-box |
A box that no rail or contact reaches. | C0202 |
shorted-contact |
A wire that joins a contact's two sides. | C0002 |
undecoded-rung |
A rung that holds an Undecoded marker. The marker stands in for a rung that a decoder could not decode or that write_csv could not write. |
Layout¶
These codes come from laying a rung out. check() reports only layout-too-tall of them. lay_out() raises a LayoutError with one of these codes. When write_csv refuses a rung because of its layout, the __cause__ of its CsvWriteError can be a LayoutError with one of these codes. For a rung that needs more than 32 rows, read_csv raises a CsvReadError and write_csv raises a CsvWriteError, and the code of each is layout-too-tall.
| Code | Meaning | CLICK id |
|---|---|---|
layout-too-wide |
A layout that needs more than 31 condition columns. | |
layout-too-tall |
A rung that needs more than the 32 rows that a CLICK rung holds. | |
layout-nop-split |
A rung that CLICK would split into several rungs, and that holds a NOP behind a contact or has only NOPs as outputs. laddercodec does not know how CLICK splits such a rung. | |
layout-cannot-draw |
Nets that collide, cells that overlap, or a contact drawn twice. |