ComGenius for SoftPLC® Runtime

LOGICAL PORT

Each port definition should use a unique number in the range 0-31, normally starting at zero. The LOGICAL PORT value is what will be needed when a COMPRINT or COMSCAN instruction is entered and you are asked for the port parameter.

PHYSICAL COMPORT

The is COM1 to COM31. Physical com ports on a SoftPLC runtime have a prefix of COM and are numbered starting at 1.

Encoding

Set this to ISO-8859-1 if you are working with 8 bit characters like ASCII or Latin-1. Otherwise if you are working with characters outside the range of 0-255, see here.

Baudrate

Normally 9600 or 19200 or 38400

Databits

May be 5, 6, 7, or 8. 8 is standard.

Parity

N = none O = odd E = even

Timeout

The time to wait for a COMSCAN instruction to complete, in milliseconds. COMSCAN gives up after this time duration.

Port:

The LOGICAL PORT configured in COMGENIUS.LST

Port:

The LOGICAL PORT configured in COMGENIUS.LST

Port:

The LOGICAL PORT configured in COMGENIUS.LST

Counter:

Where to put the received characters count as described above.

Control:

A datatable CONTROL element of type R which is used to track the progress of the print operation.

Port:

The LOGICAL PORT configured in COMGENIUS.LST

Format:

This is an integer index into the format string table. The first string is numbered 1, not zero. The chosen format string is the master specification for the conversion, as explained in detail below.

Param 1 to 6:

These are 6 optional parameters. Each one may supply either a STRING element, FLOAT word(s), or INTEGER word(s) for inclusion in the conversion as explained in detail below.

flag

one or more of the following flags, which modify the specification:

- : which specifies left adjustment of the converted argument in its field.

+ : which specifies that the number will always be output with a sign.

space : if the first character is not a sign, a space will be prefixed.

0 : for numeric conversions, specifies fill in the field with leading zeros up to the width.

# : specifies an "alternate form", and its interpretation varies by conversion_char. For o, the first digit will be zero. For x or X, 0x or 0X will be prefixed to a non zero result. For e, E, f, g, and G, the output will always have a decimal point; for g and G, trailing zeros will not be removed. For S, a two’s complement form (negated form) of checksum is generated instead of a simple positive summation. For R, the crc16 is computed by pre-loading the total with 0xFFFF as is required by Modbus RTU protocol.

width

is a sequence of decimal digits. Or it may be the character *, in which case the actual value is taken from the next integer Param and that Param is consumed. The interpretation of width varies based on conversion character:

S or R: See the S and R conversion characters below for details.

All others: minimum width of the field. The converted Param will be printed in a field at least this wide, and wider if necessary. If the converted Param has fewer characters than the field width it will be padded on the left (or right, if left adjustment has been requested) to make up the field width. The padding character is normally space, but is 0 if the zero padding flag is present.

' . ' (period)

is used to separate the width from the precision, as seen in the conversion specification template above.

precision

is a sequence of decimal digits. Or it may be the character *, in which case the actual value is taken from the next integer Param and that Param is consumed. If no digits appear after the '.' (period), then the precision is taken as 0. If the '.' does not appear, no precision may be specified and it defaults to 1. If the precision is the * character, then the value is taken from the next Param which must be supplied as type integer, and this next Param is thusly consumed. The interpretation of precision varies based on conversion character:

e, E, or f: the number of digits to be printed after the decimal point.

g or G: the number of significant digits.

c or C: the number of consecutive characters to output starting with the supplied Param.

o, i, b, u, or d: minimum number of digits to be printed (leading 0s will be added to make up the necessary width).

s: the maximum number of characters to be printed from a STRING. In the event the STRING is longer than this number, only the first precision number of characters will be output. S or R: see the conversion characters S and R below for details.

I or L

means long length: when used with the o, u, x, X, i, d, or b conversion characters, l or L indicates that the corresponding Param is to be output as a 32 bit long integer in displayable form. For example, if N7:0 is passed as the Param for this conversion specification within the format string: "%Ld" then two integer words are used and interpreted as a 32 bit long integer N7:0 and N7:1, with the least significant 16 bits of the long word being N7:0. For all other conversion characters l or L is ignored.

b

integer

output in displayable unsigned binary.

d

integer

output in displayable signed decimal.

i

integer

output in displayable signed decimal.

o

integer

output in displayable unsigned octal.

u

integer

output in displayable unsigned decimal.

x

integer

output in displayable unsigned hexadecimal, lowercase hex letters will be used.

X

integer

output in displayable unsigned hexadecimal, uppercase hex letters will be used.

s

STRING

The Param must be a STRING element. Each character in the STRING element is injected into the output by running it through the configured character encoding scheme. Use width to provide a minimum output field width if the input Param’s STRING element contains a shorter number of characters, and padding will be output. Use precision to provide a maximum output field width. For example, a conversion specification of "%12.12s" will print exactly 12 characters. If the STRING is less than 12 it will be padded because the width is 12. If the STRING is less than 12 it will be truncated because the precision is 12.

c

integer

A single byte is taken from the least significant 8 bits of the integer Param and promoted to character by setting the upper 8 bits of the promoted unicode character to zero. Then the character is output with no conversion other than travelling through the normal configured output character encoding scheme, which if is ISO-8859-1 simply throws away the upper 8 bits of the character, outputting only the least significant byte of the character. The end result is that the original input byte is output unchanged.

If the precision is specified and is greater than 1, then the process above is repeated precision times, but each time with a different input byte. After the first byte, the output continues with the most significant 8 bits of the Param, then the least significant 8 bits of the word following the Param, then the most significant 8 bits of the word following Param, and so on, until the precision requirements are met. For example, if you wanted to send 6 bytes of binary information stored at N7:10 through N7:12 (2 bytes per word, least significant byte first, 3 words total), you would use the format specification "%.6c" and a Param of N7:10.

This is the little endian output. See 'C' (upper case) for big endian output.

C

integer

A single byte is taken from the most significant 8 bits of the integer Param and promoted to character by setting the upper 8 bits of the promoted unicode character to zero. Then the character is output with no conversion other than travelling through the normal configured output character encoding scheme, which if is ISO-8859-1 simply throws away the upper 8 bits of the character, outputting only the least significant byte of the character. The end result is that the original input byte is output unchanged.

If the precision is specified and is greater than 1, then the process above is repeated precision times, but each time with a different input byte. After the first byte, the output continues with the least significant 8 bits of the Param, then the most significant 8 bits of the word following the Param, then the least significant 8 bits of the word following Param, and so on, until the precision requirements are met. For example, if you wanted to send 6 bytes of binary information stored at N7:10 through N7:12 (2 bytes per word, most significant byte first, 3 words total), you would use the format specification "%.6C" and a Param of N7:10.

This is the big endian output. See 'c' (lower case) for little endian output.

f

float

decimal string of the form [-]dd.dddd. The number of digits after the decimal point is given by the precision, which defaults to 6. If the precision is 0, no fractional digits or decimal points appear.

e or E

float

string using scientific notation in the form [-]d.dddddde+-dd. There is one digit before the decimal point and precision digits after. The precision defaults to 6. If the precision is 0, the decimal point is not written. E is used for the exponent instead of e if the E conversion character was specified. A minimum of two digits will appear in the exponent.

g or G

float

string using either f or e (or E if G was specified) format, depending on the value of the Param. e will be used if the exponent is less than -3 or greater than the precision. The precision gives the number of significant digits; it defaults to 6. The decimal point appears if followed by a digit; trailing 0s are truncated.

%

no Param consumed

The % character is printed.

S

no Param consumed

The output is a binary checksum on all the characters output from this COMPRINT starting from the character at offset width and continuing up to and including the character precision characters before the place in the output stream where the first character of the checksum will go. width defaults to 0 and precision defaults to 1, which means sum all the characters preceding the checksum. If precision were 2, then the character before the checksum would be excluded, etc. A sixteen bit checksum is used (two bytes) and output little endian, unless the "h" Length modifier is present indicating a one byte checksum. The output from this conversion is not likely to be displayable.

R

no Param consumed

The output is a binary Cyclic Redundancy Check (CRC-16) on all the characters output from this COMPRINT starting from the character at offset width and continuing up to and including the character precision characters before the place in the output stream where the first character of the checksum will go. width defaults to 0 and precision defaults to 1, and 1 means include the character just before the checksum. If precision were 2, then the character before the checksum would be excluded, etc. A sixteen bit checksum is used, and is output little endian. The output from this conversion is not likely to be displayable.

This conversion char is useful for implementing the Modbus RTU protocol using COMGIENIUS.

Control:

A datatable CONTROL element of type R which is used to track the progress of the scan operation.

Port:

The LOGICAL PORT configured in COMGENIUS.LST

Format:

This is an integer index into the format string table. The first string is numbered 1, not zero. The chosen format string is the master specification for the conversion, as explained in detail below.

Param 1 to 6

These are 6 optional parameters. Each one may receive either a STRING element, FLOAT word(s), or INTEGER word(s) as a result of parsing and converting fields in the batch of input characters, as explained in detail below.

*

is the assignment suppression indicator. Conversion verification and matching will take place, but no Param is consumed.

#

is the "alternate form" indicator, and its interpretation varies by conversion_char. For S, a two’s complement form (negated form) of checksum is generated instead of a simple positive summation. For R, the crc16 is computed by pre-loading the total with 0xFFFF as is required by Modbus RTU protocol.

width

is a sequence of decimal digits. It may NOT be the '*' character. The interpretation of width varies based on conversion character:

S or R: See the S and R conversion characters below for details.

All others: ignored.

. (period)

is used to separate the width from the precision.

precision

is a sequence of decimal digits. It may NOT be the '*' character. If the period '.' does not appear, no precision may be specified and it defaults to a sensible value based on the conversion_char. If present, the default is overridden and the interpretation of precision varies based on conversion_char:

S or R: See the S and R conversion characters below for details.

c or C: Specifies the number of bytes to be copied from the raw input stream.

s: Specifies the minimum number of characters to be copied into the STRING element. Matching and copying stop after precision characters, or if whitespace is encountered first.

o, u, x, X, i, d or b: Specifies the minimum number of numerical digits to expect excluding the prefix like +,- or 0x. Matching and conversion stop after precision characters, or if a non-digit is encountered first.

All others: ignored

modifier

may be one of L, l, H, or h.

L or l: indicates that the corresponding argument is to be converted to a 32 bit long integer when used with the o, u, x, X, i, d or b conversion_char. For all other conversion_chars it is ignored.

H or h: used only for the S conversion_char, see below.

b

integer

unsigned binary, like "1011011"

d

integer

match and convert a signed decimal field, like "-423" or "423" or "+432".

Using precision is normal, example: "%.3d"

i

integer

if the field starts with a zero (0), it is interpreted as octal, if it starts with 0x or 0X it is interpreted as hexadecimal, otherwise it is interpreted as decimal. Like "077" or "0xFF" or "12"

o

integer

unsigned octal, like "077"

u

integer

unsigned decimal, like "423"

x or X

integer

unsigned hexadecimal, like "AF9B"

c

integer

is a character copying input. precision number of input characters are copied verbatim starting at the destination integer Param. Only the least significant 8 bits of each character are used. precision defaults to 1. The lower 8 bits of each input character are copied and packed into the destination integer block using little endian copying, with up to 2 characters per integer word.

The first character is put into the least significant 8 bits of the integer Param, the next input character (if the precision is greater than 1) is put into the most significant byte of the integer Param, then the next input character is copied into the least significant byte of the next integer word after the Param, etc., until precision characters have been copied to the block of words given by the Param.

For example: “%.30c” would match and copy the next 30 characters from the input stream, regardless of their values, and would fill 15 integer words starting at Param.

Only the lower 8 bits of each character are used. This conversion_char effectively "matches" any character or precision number of characters. The lower 8 bits of each character are packed into the destination Param verbatim using little endian copying.

C

integer

is a character copying input. precision number of input characters are copied verbatim starting at the destination integer Param. Only the least significant 8 bits of each character are used. precision defaults to 1. The lower 8 bits of each input character are copied and packed into the destination integer block using big endian copying, with up to 2 characters per integer word.

The first character is put into the most significant 8 bits of the integer Param, the next input character (if the precision is greater than 1) is put into the least significant byte of the integer Param, then the next input character is copied into the most significant byte of the next integer word after the Param, etc., until precision characters have been copied to the block of words given by the Param.

For example: “%.30C” would match and copy the next 30 characters from the input stream, regardless of their values, and would fill 15 integer words starting at Param.

Only the lower 8 bits of each character are used. This conversion_char effectively "matches" any character or precision number of characters. The lower 8 bits of each character are packed into the destination Param verbatim using big endian copying.

e, E, f, g or G

float

floating point number is put into the Param.

%
' ' (space)
\t (tab)
\v (vertical tab)
\r (carriage return)
\n (line feed)
\f (form feed)

no Param consumed

Any one of the 7 conversion_chars may be given in the format string. precision is ignored. The given conversion_char is merely matched in the input stream of characters and thrown away. No Param is consumed.

Examples:
"% " matches a space
"%\t" matches a tab
"%\r" matches a carriage return

s

STRING

The Param is a STRING element like ST99:48 that receives the next non-whitespace block of input characters. Leading whitespace is ignored. The input characters are stored in the STRING element until:
• a whitespace character is encountered, or
• the STRING element is filled entirely (82 characters), or
• precision characters have been put into the STRING element. (precision defaults to 82.)

If the receive buffer runs out of input characters before any of the above 3 conditions are matched, then the matching fails.

All 16 bits of each character are saved into their respective character position within the STRING element.

If specific quantities of whitespace must be included in the input scan, here are some additional conversion_chars to consider:

1. use %c or %C with precision, for example: "%*.2c", will match any 2 characters and suppress assignment to a Param (i.e. throw away the next two characters).
2. use "% " (percent space), which matches a single space character and throws it away. See % above.

S

no Param consumed

The width defaults to 0 and the precision defaults to 1. The output is a binary checksum on all the characters received (NOT the same as converted) during this COMSCAN starting from the character at offset width up to and including the character precision characters before this field.

The calculated value is compared to the two characters in the input at this position (or 1 byte if the 'h' modifier is given).

R

no Param consumed

The width defaults to 0 and the precision defaults to 1. The output is a binary Cyclic Redundancy Check (CRC-16) on all the characters input during this COMSCAN starting from the character at offset width and continuing up to and including the character precision characters before this field. A sixteen bit CRC-16 is used.

The initial value of the CRC is preloaded with zero (0), unless the # flag is used in which case the initial value is 0xFFFF. The # flag is necessary when receiving Modbus RTU replies.

The CRC-16 computed in this way must match the 2 input characters at this position in little endian fashion. See the MODBUS example in the examples section.

n

integer

grabs the number of characters read up to this point.

All other characters are not conversion characters and will cause an error.

Sufficient input characters have been read to match all the conversion specifications in the format string.

Successful Completion.

DN: set
ERR: not set
LEN: set to total number of characters read
POS: set to number of conversion specs matched

Sufficient input characters have been read to determine that the matching of conversion specifications cannot succeed. The invocation fails and all input characters are put back into the receive buffer for another COMSCAN or COMRCVCLEAR.

Read characters are put back into the receive buffer for next scan.

Failed Completion.

DN: set
ER: set
LEN: set to total number or characters read and indicates the offset into the input stream where the mismatch occurred
POS: set to number of conversion specs matched

Insufficient characters are available in the receive buffer to complete a match, and the timeout has expired as set in the configuration file for this port. The time is measured starting from the low to high rung transition.

Read characters are put back into the receive buffer for next scan.

Failed Completion.

DN: set
ER: set
EM: set
LEN: set to total number of characters read
POS: set to number of conversion specs matched

Insufficient characters are available in the receive buffer to determine a match, and the timeout has yet to expire.

Read characters are put back into the receive buffer for next scan.

Not Completed. As long as the instruction stays energized by the rung, the instruction waits for further character input or the timeout

DN: not set
ER: not set
LEN: set to total number of characters read
POS: set to number of conversion specs matched

If the rung is de-energized before completion.

No Completion will occur.

EN: not set
DN: not set

String:

Where to print to. Up to 82 characters may be copied into this STRING element.

Format:

This is an integer index into the format string table. The first string is numbered 1, not zero. The chosen format string is the master specification for the conversion, as explained in detail below.

Param 1 to 6

These are 6 optional parameters. Each one may supply either a STRING element, FLOAT word(s), or INTEGER word(s) for inclusion in the conversion as explained in the COMPRINT detail.

Control:

A datatable CONTROL element of type R which is used to track the progress of the scan operation.

String:

The source of the input characters. Up to 82 characters may be read from this STRING element.

Format:

This is an integer index into the format string table. The first string is numbered 1, not zero. The chosen format string is the master specification for the conversion, as explained in detail below.

Param 1 to 6

These are 6 optional parameters. Each one may receive either a STRING element, FLOAT word(s), or INTEGER word(s) as a result of parsing and converting fields in the input characters, as explained in detail at COMSCAN.

Format: 1
Two parameters: integer, integer

Sample output: "Rack no: 5 has 2 modules."