Cicode Programming Reference > Cicode Function Categories > Task Functions Introduction > TaskNew


Creates a new Cicode task and returns the task handle. You pass the Name of the function (that creates the task) as a string, not as the function tag, and pass the arguments for that function in Arg. After the task is created, it runs in parallel to the calling task. The new task will run forever unless it returns from the function or is killed by another task.

By default, CitectSCADA requests necessary I/O device data and waits for the data to be returned before starting the task - the task is provided with the correct data, but there will be a delay in starting the task. If you add 16 to the Mode, CitectSCADA starts the task immediately, without waiting for any data from the I/O devices - any I/O device variable that you use will either contain 0 (zero) or the last value read.


When mode 16 is used, ensure either appropriate delays are applied before processing references to tags or check qualities of tags. Otherwise, the execution system may process invalid data and returns incorrect results.

Failure to follow these instructions can result in death, serious injury, or equipment damage.

You can specify that if the task is already running, the function will exit without launching a new task and an error will display. This is useful when you want only a single instance of the function running at any point in time.

It is also possible to run the task within the context of a particular cluster in a multi cluster system by setting the ClusterName parameter. If a cluster is not specified, the task will use the cluster context of the caller, be it a page or Cicode task. Please be aware that the cluster context cannot be changed once the code is running.

Any animation output for the new task is displayed in the window where it was created. If you want to send output to other windows, use the WinSelect() function.


TaskNew(sName, sArg, Mode [, ClusterName] )


The name of the function to create the task, as a string.


The set of arguments to be passed to the function. Individual arguments need to be separated by commas (,). Enclose string arguments in quotes "" and use the string escape character (^) around strings enclosed within a string. If the string in quotes is not enclosed, then the string is only the first tag found. The entire set of arguments need to be enclosed in quotes ("").


The mode of the task:

0 - Task runs forever.

1 - Task runs until the current page is changed.

2 - Task runs until the current window is freed.

4 - This mode is deprecated and not active. Currently, by default, task requests I/O device data before starting.

8 - If the task already exists, the function will exit without launching the new task.

16- Task doesn't wait for necessary I/O device data and starts immediately.

You can select any one of modes 0, 1 or 2 and may add mode 4 and/or mode 8 and/or mode 16. For example, set Mode to 6 to request I/O device data before starting the task, and to run the task until the current window is freed.


The name of the cluster context to be applied to the new Cicode task. This is optional if you have one cluster or are resolving the task via the current cluster context. The argument is enclosed in quotation marks "". You may pass "-" as the ClusterName argument to run the requested Cicode task without a cluster context.

Return Value

The task handle, or -1 if the task cannot be successfully created. The task handle identifies the table where data on the associated task is stored.

Related Functions

TaskCall,TaskHnd, TaskKill, TaskNewEx, TaskResume, TaskSuspend, ReRead, WinSelect


! Create a task that displays a message for 10 seconds.
! Continue to run while task runs.
MyFunc(STRING Msg)
FOR I=0 TO 10 DO
! Call a function which expects more complex argument
hTask=TaskNew("ArgFunc","^"string one^",^"string two^",1,2",0);
hTask=TaskNew("ArgFunc","^""+sOne+"^",^""+sTwo+"^","+iOne:##+","+ iTwo:##,0);
ArgFunc(STRING sOne, STRING sTwo, INT iOne, INT iTwo)

See Also

Task Functions