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


Creates a new Cicode task with an individual subscription rate 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 with tags updated at the specified time interval 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. Use Mode 16 when the task has to start immediately.


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 return 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 the 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.


TaskNewEx(sName, sArg, Mode, SubscriptionRate [, 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 you do not enclose the string in quotes, 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 all 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 subscription rate for the task, between 0 and 60000 milliseconds, which determines the frequency at which the I/ O Server reads I/O device data in order to provide tags with up-to-date Cicode variables. A value of -1 may be passed which will use the current task's subscription rate or the default value as set by the existing parameter [CODE]TimeData which defaults to 250.


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, TaskNew, TaskResume, TaskSuspend, ReRead, WinSelect


! Create a task that calls a function every half second.

See Also

Task Functions