Overview

The utilities library contains a number of useful function blocks and functions with which TwinCAT PLC or operating system functions can be called. The function blocks are based, internally, on the system library.

By adding TcUtilities.Lib the following libraries are included automatically: Standard.Lib; TcBase.Lib; TcSystem.Lib;

Operating system functions

Name	Description
NT_Shutdown	Shuts down the operating system
NT_AbortShutdown	Aborts operating system shutdown command
NT_Reboot	Restarts the operating system
NT_GetTime	Reads the local Windows system time
NT_SetLocalTime	Sets the local Windows system time
NT_StartProcess	Starts a Windows application from the PLC
NT_SetTimeToRTCTime	Synchronize the local Windows system time to the real-time clock of the PC
FB_RegQueryValue	Reads system registry
FB_RegSetValue	Writes system registry
FB_EnumFindFileEntry	This function block searches a directory for a file or subdirectory whose name matches the specified file name.
FB_EnumFindFileList	This function block searches a directory for a file or subdirectory whose name matches the specified file name. Found entries are read block by block.
FB_GetAdaptersInfo	The function block retrieves adapter information for the local or remote computer.
FB_GetHostName	The function block returns the standard host name for the local or remote machine.
FB_GetHostAddrByName	Converts the host name to the (IPv4) Internet Protocol network address.
FB_GetTimeZoneInformation	Reads operating system time zone settings.
FB_SetTimeZoneInformation	Writes operating system time zone settings.
FB_LocalSystemTime	Reads local Windows System Time and Daylight-/Standard-time information.

TwinCAT PLC functions

Name	Description
PLC_Reset	Resets the PLC
PLC_Start	Starts the PLC
PLC_Stop	Stops the PLC
PLC_ReadSymInfo	Reads the PLC symbol information
PLC_ReadSymInfoByName	Reads the additional symbol information knowing the symbol name
PLC_ReadSymInfoByNameEx	Reads the additional symbol information knowing the symbol name and cuts comment string if the string exceeds the available buffer length.
Profiler	Reads the execution time of PLC program
WritePersistentData	Writes persistent data
FB_WritePersistentData	Writes persistent data (Extendedversion)

Checksum/CRC functions

Name	Description
F_CheckSum16	Calculates the 16 Bit CheckSum
F_DATA_TO_CRC16_CCITT	Calculates the CRC16-CCITT (cyclic redundancy check) of any data type
F_BYTE_TO_CRC16_CCITT	Calculates the CRC16-CCITT (cyclic redundancy check) of single data byte

TwinCAT system functions

Name	Description
TC_Restart	Restarts the TwinCAT system
TC_Stop	Stops the TwinCAT system
TC_Config	Starts the TwinCAT system in Config mode.
TC_CpuUsage	Reads the CPU usage of the TwinCAT system
TC_SysLatency	Reads the TwinCAT System latency time
GetRemotePCInfo	Reads the TwinCAT Router information about configured remote PCs
FB_GetLocalAmsNetId	Reads the local AmsNetId ( TwinCAT PC network address )
FB_GetRouterStatusInfo	Reads TwinCAT Router status information
FB_EnumRouteEntry	Enumerates TwinCAT Router connections
FB_AddRouteEntry	Adds one TwinCAT Router connection
FB_RemoveRouteEntry	Removes one TwinCAT Router connection

TwinCAT Scope View functions

Some functions can be used if only one View in the TwinCAT Scope View application is activated.

Name	Description
ScopeLoadFile	Loads Scope View Configuration Project (*.scp)
ScopeSetOnline	Switches Scope View in Online state
ScopeSetOffline	Switches Scope View in Offline state
ScopeGetState	Reads Scope View current state
ScopeManualTrigger	Performs manual trigger
ScopeSetRecordLen	Sets the record time
ScopeGetRecordLen	Reads the record time
ScopeASCIIExport	Exports Scope View in ASCII file
ScopeViewExport	Exports Scope View in binary file
ScopeSaveAs	Saves Scope View Project file
ScopeExit	Terminates Scope View instance (exe)

TwinCAT Scope Server

since library version 2.0.52

Name	Description
FB_ScopeServerControl	Controls (start/save..) the Scope Server for data logging

TwinCAT ADS Monitor functions

Name	Description
FB_AmsLogger	Start or stop the TwinCAT AMS logger

Converting functions

Name	Description
DT_TO_SYSTEMTIME	Converts DATE_AND_TIME to the Windows system time structure
DT_TO_FILETIME	Converts DATE_AND_TIME to file time
SYSTEMTIME_TO_DT	Converts Windows system time structure to DATE_AND_TIME
SYSTEMTIME_TO_FILETIME	Converts Windows system time structure to file time.
SYSTEMTIME_TO_STRING	Converts Windows system time structure to string.
STRING_TO_SYSTEMTIME	Converts string to Windows system time structure.
FILETIME_TO_DT	Converts Windows file time to DATE_AND_TIME.
FILETIME_TO_SYSTEMTIME	Converts Windows file time to Windows system time structure.
DEC_TO_BCD	Converts decimal numbers to BCD numbers
BCD_TO_DEC	Converts BCD numbers to decimal numbers
DEG_TO_RAD	Converts degrees to radiants
RAD_TO_DEG	Converts radiants to degrees
TIME_TO_OTSTRUCT	Converts TIME variable to structure with milliseconds, seconds, minutes, hours, days and weeks
OTSTRUCT_TO_TIME	Converts structure with milliseconds, seconds, minutes, hours, days and weeks to TIME variable
F_SwapRealEx	Converts bus controller REAL number to Intel PC REAL number format
BYTEARR_TO_MAXSTRING	Converts byte array to string
MAXSTRING_TO_BYTEARR	Converts string to byte array
F_TranslateFileTimeBias	Converts UTC time to local time and vice versa (using bias value)
FB_TzSpecificLocalTimeToFileTime	Converts local time (file time format) to UTC time
FB_TzSpecificLocalTimeToSystemTime	Converts local time (structured system time format) to UTC time
FB_FileTimeToTzSpecificLocalTime	Converts UTC time (file time format) to local time
FB_SystemTimeToTzSpecificLocalTime	Converts UTC time (structured system time format) to local time

String format functions

Name	Description
LREAL_TO_FMTSTR	Converts floating point numbers to string
DWORD_TO_DECSTR	Converts decimal numbers to decimal string
DWORD_TO_HEXSTR	Converts decimal numbers to hexadecimal string
DWORD_TO_OCTSTR	Converts decimal number to octal string
DWORD_TO_BINSTR	Converts decimal number to binary string
DINT_TO_DECSTR	Converts signed decimal number to decimal string
F_FormatArgToStr	Converts one argument (plc variable) to string
FB_FormatString	Converts (formats) up to 10 arguments (plc variables) to string
FB_EnumStringNumbers	Search for numbers in string
F_ToUCase	Converts a specified string to uppercase
F_ToLCase	Converts a specified string to lowercase
F_LTrim	Removes spaces on the left side of a string
F_RTrim	Removes spaces on the right side of a string
DATA_TO_HEXSTR	Converts binary data to hex string

64 bit functions (unsigned)

Name	Description
ULARGE_INTEGER	Initializes/sets 64 bit number value
UInt64Add64	Adds two 64 bit numbers
UInt64Add64Ex	Adds two 64 bit numbers (with overflow check)
UInt64Sub64	Subtracts two 64 bit numbers
UInt64Cmp64	Compares two 64 bit numbers
UInt32x32To64	Multiplies two 32 bit numbers. Result is 64 bit number.
UInt64Mul64	Multiplies two 64 bit numbers. Result is 64 bit number.
UInt64Mul64Ex	Multiplies two 64 bit numbers. Result is 64 bit number (with overflow check).
UInt64Div64	Division of one variable by another
UInt64Div64Ex	Division of one variable by another (including remainder)
UInt64Mod64	Modulo division of one variable by another
UInt64And	Bitwise AND of operands
UInt64Or	Bitwise OR of operands
UInt64Not	Bitwise NOT of operand
UInt64Xor	Bitwise XOR of operands
UInt64Rol	Bitwise rotation of an operand to the left
UInt64Ror	Bitwise rotation of an operand to the right
UInt64Shl	Bitwise left-shift of an operand
UInt64Shr	Bitwise right-shift of an operand
UInt64Min	Minimum function
UInt64Max	Maximum function
UInt64Limit	Limiting function
UInt64isZero	Checks if value of 64 bit integer is zero
UINT64_TO_STRING	Converts 64 bit number to STRING
UINT64_TO_LREAL	Converts 64 bit number to LREAL
STRING_TO_UINT64	Converts STRING to 64 bit number
LREAL_TO_UINT64	Converts LREAL to 64 bit number

64 bit functions (signed)

Name	Description
LARGE_INTEGER	Initializes/sets 64 bit number value
Int64Add64	Adds two 64 bit numbers
Int64Add64Ex	Adds two 64 bit numbers (with overflow check)
Int64Sub64	Subtracts two 64 bit numbers
Int64Cmp64	Compares two 64 bit numbers
Int64Div64Ex	Division of one variable by another (including remainder)
Int64Not	Bitwise NOT of operand
Int64isZero	Checks if value of 64 bit integer is zero
Int64Negate	Negates 64 bit number
INT64_TO_LREAL	Converts 64 bit number to LREAL
LREAL_TO_INT64	Converts LREAL to 64 bit number
LARGE_TO_ULARGE	Converts signed 64 bit number to unsigned 64 bit number
ULARGE_TO_LARGE	Converts unsigned 64 bit number to signed 64 bit number

16 bit fixed point (signed)

Name	Description
FIX16Add	Adds two fixed point numbers
FIX16Align	Changes the resolution of fixed point number
FIX16Sub	Subtracts two fixed point numbers
FIX16Div	Division of two fixed point numbers
FIX16Mul	Multiplies two fixed point numbers
LREAL_TO_FIX16	Converts LREAL to fixed point number
WORD_TO_FIX16	Converts WORD to fixed point number
FIX16_TO_LREAL	Converts fixed point number to LREAL
FIX16_TO_WORD	Converts fixed point number to WORD

Byte order converting functions

Name	Description
HOST_TO_BE16	Host-to-network converting (16 bit number)
HOST_TO_BE32	Host-to-network converting (32 bit number)
HOST_TO_BE64	Host-to-network converting (64 bit number)
HOST_TO_BE128	Host-to-network converting (128 bit number)
BE16_TO_HOST	Network-to-host converting (16 bit number)
BE32_TO_HOST	Network-to-host converting (32 bit number)
BE64_TO_HOST	Network-to-host converting (64 bit number)
BE128_TO_HOST	Network-to-host converting (128 bit number)

Other functions

Name	Description
FB_BasicPID	Simple PID controller
F_GetVersionTcUtilities	Returns library version info
IsFinite	Checks if REAL or LREAL variable can be represented in Institute of Electrical and Electronics Engineers (IEEE) format.
F_YearIsLeapYear	Determines whether the given year is a leap year.
F_GetMaxMonthDays	Returns the number of days in a month.
F_GetDOYOfYearMonthDay	Calculates the day number of the year
F_GetMonthOfDOY	Calculates the month from day number of the year
F_GetDayOfWeek	Returns the day number of a week.
F_GetWeekOfTheYear	Returns the week number of the year.
F_GetDayOfMonthEx	Calculates the day of month of specific month, month's week and year
RTC	RTC (Real Time Clock)
RTC_EX	RTC (Real Time Clock)
RTC_EX2	RTC (Real Time Clock)
FB_FileRingBuffer	Writes/reads datasets to/from file (FIFO).
FB_MemRingBuffer	Writes/reads datasets to/from memory buffer (FIFO).
FB_MemRingBufferEx	Writes/reads datasets to/from memory buffer (FIFO).
FB_StringRingBuffer	Writes/reads strings to/from memory buffer (FIFO).
FB_MemStackBuffer	Writes/reads datasets to/from memory buffer (LIFO).
FB_HashTableCtrl, F_CreateHashTableHnd	Simple hash table.
FB_LinkedListCtrl, F_CreateLinkedListHnd	Simple linked list (doubly-linked).
DCF77_TIME	Simple DCF77 decoder.
DCF77_TIME_EX	DCF77 decoder with plausibility check of two telegrams and time zone information.

CSV format helper

Name	Description
CSVFIELD_TO_STRING	Converts string containing data field in CSV format to PLC string value
STRING_TO_CSVFIELD	Converts PLC string value to string containing data field in CSV format
CSVFIELD_TO_ARG	Converts buffer containing data field in CSV format to any PLC variable value
ARG_TO_CSVFIELD	Converts any PLC variable value to buffer containing data field in CSV format
FB_CSVMemBufferReader	Splits memory buffer containing data records in CSV format to single data fields
FB_CSVMemBufferWriter	Creates data records in CSV format in memory buffer using single data fields