Usage

The TLM is named comgenius.tlm.so and is found as part of the standard SoftPLC 4.x installation in the /SoftPLC/tlm directory. To use it you merely have to enable it in NexGen's PLC | MODULES editor by enabling the Use checkbox in the same row as the COMGENIUS TLM.

Then you must edit the text file COMGENIUS.LST which is the TLM's configuration file. There is a text editor for this COMGENIUS.LST file within NexGen. It is easy to edit the configuration file from the PLC | MODULES editor. Simply click on the Configure button after selecting and enabling Use in the same row as the COMGENIUS TLM.

Fetch, Send, Load, and Save all have the same meaning as they do in the NexGen Module editor. You can see the helpfile for that editor by going to that editor and clicking on Help.

Use Send to transfer the configuration down to the SoftPLC. The next step is to cycle power on the SoftPLC for the changes to take place.

This TLM implements the following TLIs (ladder instructions).

This TLI throws away any bytes which are in the receiver buffer for the specified Port that have yet to be read in by COMSCAN. After this instruction is energized, no further input is possible with COMSCAN until more bytes actually arrive through the Port on the wire.

This TLI throws away any bytes in the transmitter buffer for the specified Port. After this instruction is energized, no further output will take place until a COMPRINT instruction is energized for this Port.

This TLI determines the number of characters available within the receive buffer for a particular Port.

The PRE field of the Counter is set to the size of the receive buffer. The ACC word is set to the count of received characters in the buffer. The overflow bit (OV) of the counter is set if there has been a receive buffer overflow. This internal flag is automatically reset during the next COMSCAN which removes enough characters to correct the overflow condition.

COMPRINT outputs a packet of characters which is dynamically assembled using powerful string formatting. COMPRINT is a general purpose output formatting function, similar in behavior to the C programming language's printf() function, but extended with automatic checksum generation capabilities. COMPRINT can print binary byte packets, not merely ASCII strings. For example, to print out a byte whose value is zero, simply put it into the format string with an octal escape sequence like this: \0.

COMPRINT converts and writes output to the Port under control of the string table string given by Format. The format string consists of a (potentially repeating) sequence of two types of objects: (a) ordinary characters, which are copied to the output Port verbatim, and (b) conversion specifications.

A conversion specification causes conversion and output of the next successive Param given to COMPRINT. Each conversion specification begins with the character % and ends with a conversion character. To output a %, use a %%.

A conversion specification consists of:

%[flag][width][.precision][l or L]conversion_char

where a % always signifies the beginning of a conversion specification.

As shown above, between the % and the conversion_char there may be, in order, the following fields:

The last part of of the conversion specification is the conversion_char. It tells what to do with the corresponding Param in the TLI and it also locks down the Required Type for the Param:

Any other conversion chars will cause an error.

STATUS BITS/TROUBLESHOOTING COMPRINT

The COMPRINT TLI uses a CONTROL parameter to execute asynchronously. The TLI starts its operation on a low to high rung transition. Unless and until the output buffer can hold the entire COMPRINT output, no partial output is performed. When the output is entered into the buffer, the DN bit comes on within the Control and the LEN is set to the number of bytes actually output. (Note that this may happen before the characters are actually transmitted out the physical Port.) The characters are in a ring buffer initially and the first one is or soon will be on its way out the physical Port. If the rung conditions go false before the TLI can get access to the sufficiently depleted Port buffer such that the entire output will fit, no output is performed.

There is no timeout associated with COMPRINT. At most 6 conversion Params and therefore at most 6 conversion specifications (of the type requiring a Param) may be specified in this TLI. COMPRINT can fail to print only if:

1. you never energize the rung
2. you have a bad format string INDEX
3. you have not allowed the rung to go false from the last time you fired it and the DN bit came on
4. you have a bad port number
5. you have an illegal format string (for example, "%k")

If none of the conditions 1) through 5) happen, then you expect the DN bit to come on and the ER bit will be reset by the instruction. You do not ever have to reset the ER bit on COMPRINT because successful completion clears the ER bit. Additionally, a false rung condition clears both DN and ER [condition 1) above].

COMSCAN reads bytes from the receive buffer for a port. Bytes read are first converted according to the encoding scheme to a batch of characters, and then the batch of characters are converted according to a format string and the values created are stored in the TLI's integer, float, and/or STRING element datatable Params. COMSCAN is similar to the C language "scanf" function, is a general purpose serial input function, and has very powerful and wide ranging pattern matching and conversion capabilities.

A major feature of this TLI, besides reading characters, is pattern matching on those characters according to the format string. The instruction either succeeds or fails based on the pattern matching, and this is indicated by the ER bit being on or off at the time the DN bit comes on.

The format string consists of a (potentially repeating) sequence of the following elements:

1. Spaces, tabs, carriage returns, line feeds, vertical tabs, and formfeeds which all cause input to be skipped up to the next character which is not whitespace. (Whitespace characters are blank, tab, line feed, carriage return, vertical tab, and formfeed.)
2. Other characters, except for % which are matched against the input.
3. A conversion specification:

%[* or #][width][.precision][modifier]conversion_char

where a % always signifies the beginning of a conversion specification.

A conversion specification determines the conversion of the next input field. The result of the conversion is placed in the next Param. Params are thus consumed one after another in this fashion. If there are less Params than conversion specifications an error is returned. Excess Params are ignored. If the * is present, the conversion is performed, but no Param is consumed.

An input field is normally a string of non-white space characters; it extends either to the next white space character or until the field width, if specified, is exhausted. This implies that COMSCAN may read across line boundaries to find its input, since newlines are white space.

The conversion_char indicates the interpretation of the input field. A % always signifies the beginning of a conversion specification. As shown above, between the % and the conversion_char there may be, in order, the following fields:

The last part of the conversion specification is the conversion_char. It tells how to convert the next non-whitespace field in the input character stream:

The COMSCAN TLI uses a Control parameter to execute asynchronously. The TLI starts its operation on a low to high rung condition transition. When the TLI finishes the DN (done) bit in the CONTROL element is set. If there is an error at completion, then also the ER (error) bit is set, else not. After the start of operation on the low to high rung transition, the following behavior is expected for each scan:

If the amount of input characters is insufficient to process the entire format string, and as long as the TLI remains energized by the rung, the instruction waits for several scans until enough data is available or until the Port specific TIMEOUT has expired.

COMSCAN can fail to scan if any of the following are true:

1. you never energize the rung, or de-energize it before the timeout expires
2. you have a bad format string INDEX
3. you have not allowed the rung to go false from the last time you fired it and the DN bit came on
4. you have a bad port number
5. you have an illegal format string (for example, “%k”)
6. you have a mismatch in the number of parameters indicated in the format string relative to the number supplied to the instruction, or a type mismatch on any parameter. (Eg: “%u” and then supply a float parameter to the TLI instruction, where %u requires an integer.)
7. a mismatch on the inbound data occurred, meaning the serial line data did not agree with the format string
8. a timeout occurred. This sets the EM, ER, and DN bits.

STRPRINT outputs a packet of characters which is dynamically assembled using powerful string formatting. STRPRINT is almost exactly like COMPRINT, except that the output is to a STRING element and not to a serial port, and this instruction executes to completion immediately (is not asynchronous). Read about COMPRINT and then return here.

STRSCAN reads characters from a STRING element. The characters are converted according to a format string and the values created are stored in the TLI's integer, float, and/or STRING element datatable Params. COMSCAN is similar to the C language "scanf" function, is a general purpose serial input function, and has very powerful and wide ranging pattern matching and conversion capabilities.

Study the operation of the COMSCAN TLI to better understand how STRSCAN works. They are the same except for the source of the characters.