• Home
• Function/Function Block Reference
• IEC 61131-3 Functions and Function Blocks
• Data Type Conversion
• TO_USINT

TO_USINT

Type	Function
Description	The overloaded function TO_USINT converts an input value of various data types into an output value of the data type USINT (see description of the input for the supported data types).
Parameters	Input IN Data type: The function is available for the following input data types: BOOL, BYTE, WORD, DWORD, LWORD Integers: SINT, INT, DINT, LINT, UINT, UDINT, ULINT Floating point numbers: REAL, LREAL STRING, WSTRING Output OUT Data type: USINT
Conversion rules	ANY_BIT conversion The conversion is done by copying the input value bitwise to the output value, i.e., a binary transfer from the input data type to the output data type is performed. If the input data type is bigger than the USINT output (> 8 bits), only the bits 0 to 7 of the input value are copied to the output value. ANY_INT conversion The data type conversion is done as follows: The source data type is converted to the largest data type of the same generic data type group (for example, an USINT value is converted to an ULINT value or a SINT value to a LINT value). The source value remains unchanged. The result is converted to the largest data type of the generic data type group to which the target data type belongs to (for example, a LINT value is converted to a ULINT value in case of an ANY_UNSIGNED conversion). The result is converted to the target data type. Input size <= output size: If the input data type is smaller or has the same size than the target data type, all bits of the value are copied to the output. In case of an unsigned integer input value, the "unused" bits in the target data type are set to 0. In case of a signed integer input value, the most significant bit is no longer considered as sign bit. Input size > output size: If the input data type is bigger than the target data type, only the bits of the input value that fits into the target data type are copied to the output value (for example, for a TO_UDINT conversion only the bits 0 to 31 of the input value are copied and for a TO_USINT conversion only the bits 0 to 7 are stored into the output variable.) Example: out := TO_USINT(INT#-5); The INT value INT#-5 is converted to the LINT value LINT#-5. The LINT value LINT#-5 is converted to the ULINT value ULINT#18446744073709551611. The ULINT value ULINT#18446744073709551611 is converted to the USINT value USINT#251. ANY_REAL conversion The type conversion is divided into two steps. First the floating point value is rounded to the next higher absolute integer according to standard rounding rules (for example, 2.5 is rounded to 3 and -2.5 is rounded to -3). In the second step the rounded input value is converted to the least significant bits of the output value. Note Due to the loss of significance in REAL values, only REAL values less than LINT_MAX should be applied. ANY_STRING conversion The string value has to be a valid numeric literal of the output data type, otherwise the function returns the value 0 and the runtime error 'Format string failure' occurs (see the note below). Additional characters except than whitespaces after or before the numeric literal are not permitted. The function returns the value 0 and generates a 'Format String Failure' if the string value contains unallowed characters. All leading and trailing whitespaces in the input string are ignored. ASCII codes regarded as whitespaces: Character Value Horizontal tab 9 (09h) Line feed 10 (0Ah) Vertical tab 11 (0Bh) Form feed 12 (0Ch) Carriage return 13 (0Dh) Blank 32 (20h) If the input value is out of the range for the output data type, the overflow value is returned and the runtime error 'Format string failure' occurs (see the note below). Binary, octal, hexadecimal and decimal integers are allowed. For example: INT#2#0101 (binary representation of 5) INT#8#606 (octal representation of 390) INT#10#100 (decimal representation of 100) INT#16#00FA (hexadecimal representation of 250) Note Controller stop on string error: The controller can be automatically stopped when a string error occurs. This allows you to locate the error in your project. To enable the automatic stop of the controller in case of a string error, activate the button in the Cockpit toolbar of the controller.
Error behavior	Error behavior The following table shows the errors which may occur while executing the function and the value returned by the function in the corresponding error case. Error case Output value RFC/NFC/AXC F 3152 Output value AXC F 2152 Overflow value (See the note for large real values below the table.) Overflow value Overflow value Real value >= LINT_MAX Overflow value Overflow value Note ENO stays TRUE. Real value <= LINT_MIN Overflow value Overflow value Real value > ULINT_MAX 0 TYPE_MAX Real value > -ULINT_MAX 0 1 Real: NaN 0 0 Real: Inf+ 0 TYPE_MAX Real: Inf- 0 1 Non-literal string (integer num, literal binary, octet, hex, dec) 0 0 String overflow (integer num, literal binary, octet, hex, dec) Note: Binary conversions do not result in overflow.) Overflow value Overflow value If any of the listed string errors occurs, an error is written to the Online log in the MESSAGES window. Note for large real values: Often the overflow results in 0 or the resulted value has gaps. The reason lies in the character of reals,which have only a number of significant digits. With REAL there are only 7 significant values. The larger the number is, the likeleness of 0 as the result (especially for small output types) will increase. Sample: 3.6000000E+7 => 3.600000E+7 => SINT: 0 3.6000001E+7 => 3.600000E+7 => SINT: 0 3.6000002E+7 => 3.600000E+7 => SINT: 0 3.6000003E+7 => 3.600004E+7 => SINT: 4 3.6000004E+7 => 3.600004E+7 => SINT: 4 ... The values 3.600001E+7, 3.600002E+7, 3.600003E+7 have no representation in REAL and will be set to the next possible REAL value. This results in gaps. The larger the number is, the larger the gap will be, until always 0 will be shown as result.
Examples	Examples in ST out := TO_USINT(16#7F);   (* results in 127 *) out := TO_USINT(16#FFFF);   (* results in 255 *) out := TO_USINT(16#AFFFFFF0);   (* results in 240 *) out := TO_USINT(INT#127);   (* results in 127 *) out := TO_USINT(INT#32767);   (* results in 255 *) out := TO_USINT(INT#-32768);   (* results in 0 *) out := TO_USINT(SINT#-128);   (* results in 128 *) out := TO_USINT(REAL#2.55E+002);   (* results in 255 *) out := TO_USINT(REAL#2.56E+002);   (* results in 0 *) out := TO_USINT('123');   (* results in 123 *)
Additional information	EN/ENO behavior The POU is only executed if TRUE is applied to the EN input. If EN = FALSE, the POU is not executed and ENO = FALSE indicates the inactivity. If any of the errors listed under "Error behavior" occurs while executing the function, ENO is set to FALSE. Further Info See the topic "General information on execution control with EN/ENO" for further details.