C language function

User’s manual

WUXI XINJE ELECTRIC CO., LTD.

 Catalog
1. Introduction .............................................................................................3
2. C function ................................................................................................3
2.1 Functions .....................................................................................3
2.1.1 Public functions .................................................................3
2.1.2 Performance functions .......................................................4
2.2 Predefined value type....................................................................4
2.3 Predefined value table .................................................................4
2.4 Macro ............................................................................................5
2.5 Direct operation for HMI internal registers ................................10
2.5.1 PSW registers ...................................................................10
2.5.2 PSB operation functions .................................................. 11
2.6 Notice .......................................................................................... 11
3. Application ............................................................................................12
3.1 Purpose ......................................................................................12
3.2 Device........................................................................................12
3.3 Reference manual ......................................................................12
3.4 Steps ..........................................................................................13
4. Make the project ...................................................................................13
4.1 Make C function .........................................................................13
4.2 Edit the C function ....................................................................14
4.3 Make the HMI program ............................................................16
Appendix 1 System tips ............................................................................18
Appendix 2 API functions.........................................................................19
Appendix 3 The calling limit for C function ............................................23

2/24
 1. Introduction
C language function is added in the Touchwin software v2.C.6 and higher
version. With this new function; TH and TP series HMI can realize more
complicated operations.
We will explain the C function programming rules with simple examples.

2. C function

2.1 Functions

The way of writing C function is the same as C language. C functions

include public functions and performance functions.

2.1.1 Public functions

Public functions: can be called by any performance functions. It needs to

write function prototype, parameters and return value are allowed.

Example:
DWORD Crc(BYTE* pBytes, int Length)
{
DWORD dwCrc = 0;
…
return dwCrc;
}

Call performance functions in public functions:

void CallFunction()
{
Func1();
}

3/24
2.1.2 Performance functions

Performance functions: no return value, no parameters. It no needs to

write function prototype, only has to specify the function name, direct
write the function body.
Performance functions can be called through the function button and
function field in Touchwin software.

Example:
BYTE byArray[10];
DWORD dwCrc = 0;
dwCrc = Crc(byArray, 10); // call public function

2.2 Predefined value type

UINT == unsigned int // 32bits, 4 bytes, same as DWORD

DWORD == unsigned long
WORD == unsigned short
BYTE == unsigned char
BOOL == unsigned char

2.3 Predefined value table

enum {FALSE = 0, TRUE = 1};

//
enum ECom
{
HMI_LOCAL_MCH = -1,
DOWNLOAD,
PLC,
EComMax
};

enum EInnerReg
{
TYPE_PSB = 0,
TYPE_PSW,
TYPE_PFW,
TYPE_PRW,

4/24
 TYPE_PHW,
TYPE_PUW,
TYPE_PCW,
EInnerRegMax
};

enum EDataType
{
TYPE_NONE,
TYPE_BIT,
TYPE_BYTE,
TYPE_WORD,
TYPE_DWORD,
TYPE_REGS,
TYPE_BYTE_3
};

2.4 Macro

1. Obtain the maximum

Max(a, b)
Example: Max(3, 4) == 4

2. Obtain the minimum

Min(a, b)
Example: Min(3, 4) == 3

3. Combine two bytes in one word

MAKEWORD(lb, hb)
Example: MAKEWORD(0x01, 0x02)== 0x0201

4. Combine two words in one double words

MAKELONG(lw, hw)
Example: MAKELONG(0x01, 0x02)== 0x00020001

5. Obtain the low byte of one word

LOBYTE(w)
Example: LOBYTE(0x0201) == 0x01

5/24
6. Obtain the high byte of one word
HIBYTE(w)
Example: HIBYTE(0x0201)== 0x02

7. Obtain the low word of one double-word

LOWORD(l)
Example: LOWORD(0x00020001) == 0x0001

8. Obtain the high word of one double words

HIWORD(l)
Example: HIWORD(0x00020001) == 0x0002

9. Read&write the register (for bit and register)

BOOL Read(int comID, int staID, int objType, int add1, int add2,
int dataType, void*pValue);
BOOL Write(int comID, int staID, int objType, int add1, int add2,
int dataType, DWORD dwValue);

Explanation:
comID: serial port (HMI_LOCAL_MCH=-1, DOWNLOAD=0, PLC=1)
staID: station no.
objType: register address type
add1, add2: register address
dataType: TYPE_BIT =1 occupy 1 byte
TYPE_BYTE =2 occupy 1 byte
TYPE_WORD =3 occupy 2 bytes
TYPE_DWORD =4 occupy 4 bytes
pValue: data buffer (the length must match dataType)
return value: TRUE/FALSE (succeed/fail)

Example:
BOOL bValue; //define a boolean variable
WORD wValue; //define a integer variable
Read(PLC,1,XINJE_XC_BIT_M,0,0,TYPE_BIT,&bValue); //read M0
Read(PLC,1,XINJE_XC_REG_D,0,0,TYPE_WORD,&wValue);//read
D[0]

10. Read&write the register group

BOOL Reads(int comID, int staID, int objType, int add1, int regs,
void*pRegs);
BOOL Writes(int comID, int staID, int objType, int add1, int regs,
void*pRegs);

6/24
Explanation:
comID: serial port (HMI_LOCAL_MCH=-1, DOWNLOAD=0, PLC=1)
staID: station no.
objType: register address type
add1: register address
regs: register quantity
pRegs: value buffer (length must match read&write register group)

Example:
WORDwValue[10]; //define a integer variable
Reads(PLC,1,XINJE_XC_REGS_D,0,1,wValue); //read D[0] group

Note: please refer to Read function.

11. Obtain the serial port

void Enter(BYTE ComID);
void Leave(BYTE ComID);

Enter, Leave: signal control, ensure the communication is synchronous.

Use with Send and Receive.

Example:
Enter(PLC);
Leave(PLC);

12. Send serial port data

BOOL Send(BYTE ComID,BYTE*SndBuf, WORDLen);

comID: serial port (DOWNLOAD=0,PLC=1)

SndBuf: sending buffer, type is byte
Len: sending data length, count by byte
Return value: TRUE/FALSE (succeed/fail)

Example:
BYTERcvArray[8]={0x01,0x01,0x00,0x10,0x00,0x10,0x3C,0x03}
Send(PLC,RcvArray,8)

13. Receive serial data

WORDReceive(BYTEComID,BYTE*RcvBuf,WORDLen,WORDTi
meOut,BYTETimeOutBytes);

comID: serial port (DOWNLOAD=0, PLC=1)

RcvBuf: receiving buffer, the type is byte

7/24
Len: receive data length, count by byte
Timeout: receiving timeout time (0: always wait). Unit: ms
TimeOutBytes: byte receiving timeout time (set to 6)
Return value: receiving data length, count by byte

Example:
BYTEbyArray[10];
Receive(PLC,byArray,10,0,6);

14. Apply heap space

Void *Malloc(UINT size)

Size: apply the space size (bytes)

Return: the address of applied space, NULL means application fail
Malloc: malloc applies memory to replace malloc in standard library
functions, the function is the same.

Note: please free the space in time.

Example:
Unit* p;
P=(Unit*) malloc (sizeof(Unit));

15. use with malloc() in pair, free the space applied by malloc
Void Free(void*pBuffer)

pBuffer: the space to be free

Free: replace Free in standard library functions, the function is the same

Example:
BYTE*pBuffer=Malloc(10);
Free(pBuffer)

16. Lock, UnLock: task lock, use them in pair

Void Unlock(void);
Void Lock(void);

Note: the locked area must be access management for global variables;
the lock area must be as small as possible.
Suitable case: if there are many performance functions need to access for
the same global variable, the task lock is needed.

8/24
17. Delay
Void Delay(UNIT ms);

ms: delay time (unit: ms). Max delay time=0xFFFF*delay accuracy

delay accuracy: TP, OP series is 10ms, TPA61, TH, MH series are 5ms.

Example:
Delay(10); //delay 10ms
Delay(1000); //delay 1s

18. Screen jump

WORD ScreenJump(WORD ScreenNo);

screenNo: screen no.

Return: the jump screen no.

Example:
ScreenJump(2); // jump to screen No.2

19. Open the window

Void OpenWindow(WORDwinNo,WORDwinX,WORDwinY);

winNo: window no.

winX: X-axis starting position of the window
winY: Y-axis starting position of the window

Example:
OpenWindow(2,10,10); //display window no.2 at (10,10)

20. Close the window

Void CloseWindow(WORDwinNo);

winNo: window no.

Example:
CloseWindow(2); //close window no.2

21. A buzzer
Void Beep(void);

Example:
Beep();

9/24
22. Light the screen (from the screen save state)
Void LightScreen(void);

Example:
LightScreen();

23. Calculate the value of Crc

UNIT Crc(BYTE*pHead, UNITnLen);

pHead: start address of data buffer

nLen: buffer length
Return: Crc value

Example:
BYTEbuffer[3]={0x01,0x02,0x03};
UNIT nCrc=Crc(buffer,3); // put the checksum of array buffer Crc to
variable nCrc

24. Calculate Crc16

UNIT Crc16(BYTE*pHead, UNIT nLen, UNITpoly, UNIT
good_crc);

pHead: starting address of data buffer

nLen: buffer length
poly: the polynomial produced by CRC16
good_crc: initial value
Return: Crc value

2.5 Direct operation for HMI internal registers

2.5.1 PSW registers

PSW registers can be operated directly, the type is unsigned short

(WORD).
Example:
PSW[300]++；// PSW[300]++ as the word

DWORD dwValue = *(DWORD*)(PSW + 300);

Or

10/24
DWORD dwValue=MAKEDWORD(PSW[300],PSW[301]);
/ / assign the value of PSW[300] and PSW[301] to one double words

float fValue = *(float*)(PSW + 300);

// read the value of PSW[300] and PSW[301] as the float format

*(DWORD*)(PSW + 300) = dwValue;

// assign one double words to PSW[300] and PSW[301]

2.5.2 PSB operation functions

GetPSBStatus(PSB_No); // obtain the value of PSB

Example: GetPSBStatus(300); //obtain the value of PSB300

SetPSB(PSB_No); // PSB=1
Example: SetPSB(300); //PSB300=1

ResetPSB(PSB_No); // PSB=0
Example: ResetPSB(300); //PSB300=0

Example: PSB301 = PSB300

if( GetPSBStatus(300) )
SetPSB(301);
else
ResetPSB(301);

2.6 Notice

1. When input API function, make sure the function name is together with
“(” and no space between them. Dialog and tip box will pop up by doing
this.
2. Capital and small letter is distinguished for the code.
3. It cannot assign initial value to the global variables defined in the
public function. The default value of global variables is 0.
4. When define the variables, the type must be the same to the data
source.
5. The performance function name must be English and cannot be the
same with others.
6. Press F7 to compile the program.
7. When declare the variables (global or local variables), don’t declare the
array whose space larger than 128 bytes. It can use special space
allocation function.
11/24
8. Cannot call malloc/ free directly, but please use Malloc / Free (first
letter is capital).
9. The execution environment of performance function is multi-tasking.
The execution mode of performance function: parallel execution,
sequential execution.
Sequential execution: The task which calls the performance function
enables to do the next operation after the performance function execution
is finished. So performance function must have suitable exit condition.
Parallel execution: The task which calls the performance function will
build new task to execute the function. The task will do the next
operation.
10. Use carefully as the multi-task system has task lock.

3. Application

3.1 Purpose

Get 3 integral from the PLC, show the min and max ones on the screen.

3.2 Device

This project needs the following devices:

1. TH series HMI: TH465-MT 1pcs
2. XC series PLC: XC3-24R-E 1pcs
3. Software: Touchwin version 2.c.6 and higher
4. Cables: USB download cable 1pcs, PLC cable 1pcs, PC

3.3 Reference manual

1. XC series PLC manual (instruction part and hardware part)

2. TH series HMI manual

12/24
3.4 Steps

1. Set value in PLC register D0, D2, D4 via the HMI.

2. Send the value of D0, D2, D4 to the HMI.
3. Call the C function to compare the three values.
4. Show the max value in PSW300, the min value in PSW301.

4. Make the project

4.1 Make C function

1. Open Touchwin V2.C.6 software, right click Function/Insert.

2. Input necessary information in below window, then click OK.

13/24
3. Click Func1 to edit the C function.

4.2 Edit the C function

1. Define the character according to the C writing rules.

14/24
WORD a,b,c,max,min;
Define the value type according to the data source type.

2. Collect the value to C function:

Read(PLC,1,XINJE_XC_REG_D,0,0,TYPE_WORD,&a);
//send the value of D0 to a
Read(PLC,1,XINJE_XC_REG_D,2,0,TYPE_WORD,&b);
//send the value of D2 to b
Read(PLC,1,XINJE_XC_REG_D,4,0,TYPE_WORD,&c);
//send the value of D4 to c
When you input “Read(”, it will pop up below window:

Unit type: the operation object type, select “register”

Station: input the PLC station No.
Object: input the object address D0
Data type: word
Notes: for details tips please refer to appendix.

3. Edit the compare program:

if(a>b)
{max=a;min=b;}
else
{max=b;min=a;}
if(max<c)
max=c;
if(min>c)
min=c;
4. Send the result to the HMI:

15/24
Write(HMI_LOCAL_MCH,0,TYPE_PSW,300,0,TYPE_WORD,max);
//write max value to PSW300
Write(HMI_LOCAL_MCH,0,TYPE_PSW,301,0,TYPE_WORD,min);
//write min value to PSW301

5. The Func1 program:

6. Press F7 to compile the C function. If the program is correct, it will

show below window:

4.3 Make the HMI program

1. Put 3 digital input buttons on the screen. Set the address to D0, D2 and
D4.
2. Put 2 digital display buttons on the screen. Make the address to
PSW300 and PSW301.
3. Put 1 function button on the screen to call the Func1.

16/24
4. The final screen:

5. Download the HMI program to the TH465. Connect PLC with the
TH465, power on. Input any value in a, b, c. Click Func button, the max
and min value will show on the screen.

17/24
Appendix 1 System tips
WORD a,b,c,g[4];
Read(PLC, 1, XINJE_XC_BIT_M, 0, 0, TYPE_BIT, &b);
//Read the value of M0 to b
Read(PLC,1,XINJE_XC_REG_D,2,0,TYPE_WORD,&b);
//Read the value of D2 to b
Reads(PLC, 1, XINJE_XC_REGS_D, 10, 4, g);
//Read the value of D10~D13 to g
Read(HMI_LOCAL_MCH, 0, TYPE_PSB, 300, 0, TYPE_BIT, &a);
//Read the value of PSB300 to a
Read(HMI_LOCAL_MCH, 0, TYPE_PSW, 300, 0, TYPE_WORD, &b);
//Read the value of PSW300 to b
Reads(HMI_LOCAL_MCH, 0, TYPE_PFW, 300, 4, g);
//Read the value of PFW300~PFW303 to array g
Write(PLC, 1, XINJE_XC_BIT_M, 0, 0, TYPE_BIT, 0);
//Set OFF M0
Write(PLC, 1, XINJE_XC_REG_D, 50, 0, TYPE_WORD, a);
//Write the value of a to D50
Writes(PLC, 1, XINJE_XC_REGS_D, 20, 4, g);
//write the value of array g to D20~D23
Write(HMI_LOCAL_MCH, 0, TYPE_PSB, 300, 0, TYPE_BIT, 1);
//Set ON PSB300
Write(HMI_LOCAL_MCH,0,TYPE_PSW,300,0,TYPE_WORD,max);
//write the value of max to PSW300
Writes(HMI_LOCAL_MCH, 0, TYPE_PFW, 300, 4, g);
//write the value of array g to PFW300~PFW303

18/24
Appendix 2 API functions

Take XC as an example:
/**********************************************************
*************************
Function: read and write register (for bit and register)
comID: serial port (HMI_LOCAL_MCH = -1
DOWNLOAD = 0,
PLC = 1)
staID: station number
objType: register address type
add1,add2: register address
dataType: TYPE_BIT = 1 occupy 1 byte
TYPE_BYTE = 2 occupy 1 byte
TYPE_WORD = 3 occupy 2 bytes
TYPE_DWORD = 4 occupy 4 bytes
pValue: value buffer (the length must match to dataTyp)
return value: TRUE / FALSE (successful/ failed)
***********************************************************
*************************/
BOOL Read (int comID, int staID, int objType, int add1, int add2,
int dataType, void* pValue);
BOOL Write(int comID, int staID, int objType, int add1, int add2,
int dataType, DWORD dwValue);
Example:
BOOL bValue = FALSE;
WORD wValue = 0;
Read(PLC, 1, XINJE_XC_BIT_M, 0, 0, TYPE_BIT, &bValue);
// read the bit
Read(PLC, 1, XINJE_XC_REG_D, 0, 0, TYPE_WORD, &wValue);
//read D[0]
Read(HMI_LOCAL_MCH, 0, TYPE_PFW, 300, 0, TYPE_WORD,
&wValue); //read PFW[300]
Write(HMI_LOCAL_MCH, 0, TYPE_PFW, 300, 0, TYPE_WORD,
wValue); //write PFW[300]

19/24
/**********************************************************
*************************
Function: read and write register array
comID: serial port (HMI_LOCAL_MCH = -1
DOWNLOAD = 0,
PLC = 1)
staID: station number
objType: register address type
add1: register address
regs: register quantity
pRegs: value buffer (the length must be match to the read&write register
array)
return value: TRUE / FALSE (successful/failed)
***********************************************************
*************************/
BOOL Reads(int comID, int staID, int objType, int add1, int regs,
void* pRegs);
BOOL Writes(int comID, int staID, int objType, int add1, int regs,
void* pRegs);
Example:
WORD wArray[10];
Reads(PLC, 1, XINJE_XC_REGS_D, 0, 10, wArray);
Writes(PLC, 1, XINJE_XC_REGS_D, 0, 10, wArray);

/**********************************************************
*************************
Function: Enter, Leave: signal control, ensure the communication is
synchronization mode. Use together with send and receive.
***********************************************************
*************************/
void Enter( BYTE ComID );
void Leave( BYTE ComID );
/**********************************************************
*************************
Function: send data of serial port
comID: serial port (DOWNLOAD = 0, PLC = 1)
SndBuf: sending buffer, the type is byte
Len: sending data length, count as byte
Return value: TRUE / FALSE (successful/failed)
/**********************************************************
**************************/
BOOL Send( BYTE ComID, BYTE *SndBuf, WORD Len );
/**********************************************************

20/24
*************************/
Function: receive the data of serial port
comID: serial port (DOWNLOAD = 0, PLC = 1)
RcvBuf: receiving buffer, the type is byte
Len: receiving data length, count as byte
Timeout: receiving timeout time (0:always waiting). Unit: ms
TimeOutByte: receiving timeout time of bytes (set to 6)
Return value: received data length, count as byte
/**********************************************************
**************************/
WORD Receive( BYTE ComID, BYTE *RcvBuf, WORD Len, WORD
TimeOut, BYTE TimeOutBytes);
Exp:
BYTE byArray[10] = {0x00, ….};

Enter(PLC); // apply the serial port

Send(PLC, byArray, 10);
Receive(PLC, byArray, 10, 0, 6);
Leave(PLC); // release the serial port

/**********************************************************
*************************
Function: Malloc, Free: instead of malloc, free.
Note: please release the applied space in time
***********************************************************
*************************/
/**********************************************************
*************************
Function: apply heap space
Size: apply the space size(bytes)
Return: the applied space address, NULL means the application is failed
***********************************************************
*************************/
void *Malloc( UINT size )
/**********************************************************
*************************
Function: release heap space
pBuffer: the space ready to release
***********************************************************
*************************/
void Free( void *pBuffer)
Example: BYTE* pBuffer = Malloc(10);
Free(pBuffer)

21/24
/**********************************************************
*************************
Function: Lock, UnLock: task lock, use them in pairs
Note: the locked area: access manage for global variables, make the
locked area as small as possible
Suitable case: the task lock is needed when there are many performance
functions need access for one global variable
***********************************************************
*************************/
void Unlock (void);
void Lock (void);

/**********************************************************
*************************
Function: Delay
ms: delay time (unit:ms), the max delay time = 0xFFFF * delay precision
delay precision: TP series(except TPA61-T) and OP series are 10ms;
TPA61-T and TH series are 5ms
***********************************************************
*************************/
void Delay( UINT ms);
Example:
Delay(1000); // delay 1s

22/24
Appendix 3 The calling limit for C function
This chapter will introduce the restricted library functions.
Most C functions can be used normally (except heap functions). However,
the following functions are limited when using.
1. The functions in alloca.h cannot be called, they are related to heap.
2. The assert functions in assert.h cannot be called.
3. The stream functions in stdio.h cannot be called, only the functions
for string (sscanf, sprint) can be used normally.
4. The heap functions in stdlib.h cannot be called, but they can be
instead by API functions.

23/24
WUXI XINJE ELECTRIC CO., LTD.
4th Floor, Building 7th, No.100 Dicui Rd,
Wuxi, China
Tel: 86-0510-85134139
Fax: 86-0510-85111290
www.xinje.com
Email: [email protected]

24/24