Follow-On Topics

Related Topics

# About the King Task Centre Task API

The King Task Centre API offers a structured, powerful and easy-to-use interface to access the King Task Centre Software Suite’s server. It provides the ability to import tasks, enumerate tasks in folders, access basic task information, enable / disable a task, set / read task variables, set / read task categories, set / read task run parameters, and to run a task.

The API itself is COM-based and can therefore be used by any development environment supporting COM ,such as, Microsoft Visual Basic, Microsoft Visual C++, ASP, or VBScript and so on.

Accessing the TCAPI System Object

The Main Object is called `TCAPI`:

|  | prog-id —"`Iwcltcp.TCAPI`"

|  | CLSID `{A5FA9D80-A516-498D-9B1B-A7E9F224E11C}`.

|  | Its default interface is `ITCAPI`.

The following methods may be used for accessing thtaske TCAPI System Object:

VBScript

To create this object in VBScript would take a command similar to the following:

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

The TCAPI Object is then ready to use.

Visual Basic 6

In Visual Basic 6 you can either use CreateObject as in the above example for VBScript or you can add the type library to Visual Basic's References Dialog.

C++
Using a type library or including the header file directly

In C++ you can use a type library or include the header file directly. We do recommend that you include `iwcltcp.h` directly as it provides additional types for interface pointers like `LPTCAPI`, and so on. If you are to include the type library use the `no_namespace raw_interfaces_only named_guids` attributes:

    #include iwcltcp.h or

    #import iwcltcp.tlb no_namespace raw_interfaces_only named_guids

Using CComPtr<> as an Interface Helper Class

Using the ATL Smartpointer template class `CComPtr< >` makes interface handling much easier and also makes the code easier to read. To make this document more readable use ATL Smart Pointers throughout.

To use the ATL Wrapper CComPtr use a command similar to the following:

    CComPtr<ITCAPI> spTCAPI;

    hResult = spTCAPI.CoCreateInstance(CLSID_TCAPI, NULL, CLSID_INPROC_SERVER);

Using Interfaces and COM Directly

If you prefer to use COM Directly (without ATL Helper Classes):

    LPTCAPI pTCAPI = NULL; // (use ITCAPI* if using the type library instead of the header file)

    hResult = CoCreateInstance(CLSID_TCAPI, NULL, CLSCTX_INPROC_SERVER, IID_ITCAPI, (LPVOID*)&pTCAPI);

    pTCAPI->Release();

NOTE:

There are many other ways of accessing the TCAPI System, all depending on the Languages COM Access System. Also the C++ COM wrapper classes may be used by omitting the `raw_interfaces_only attribute` from the `#import` command. Documentation for accessing the API this way is beyond the scope of this document but users who prefer to use the API this way should still be able to use this document as a guide to using the King Task Centre API.

Logging on and creating a TCAPI Session

Once the TCAPI System object has been created we need to logon to the King Task Centre server. This is done by calling the `Logon` method of the TCAPI System object.

Method Usage

|  | C++
    HRESULT Logon(LOGONTYPE LogonType, VARIANT ServerName, VARIANT UserName, VARIANT Password, VARIANT Domain, LPTCAPISESSION *ppSession);

|  | VB
    Function Logon(LogonType, ServerName, UserName, Password, Domain) As ITCAPISession

The first parameter, `LogonType`, can be set to either `1` or `2` depending on the type of logon required. It is recommended that the following be placed at the top of code when using VBScript:

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

When using C++ with `iwcltcp.h` these values should already be defined.

The second parameter, `ServerName`, is required and should contain the name of the King Task Centre server to connect to.

The `UserName`, `Password`, and `Domain` parameters are optional variants; in VB this means they can just be omitted, in other languages you need to pass a variant of type `VT_ERROR` with the error code `DISP_E_PARAMNOTFOUND` this is sometimes available as `vtMissing`.

Whether a parameter is omitted depends on the value specified for `LogonType`:

|  | If `LogonType` is `1` then the `Domain` parameter should be omitted as King Task Centre users do not have domains

|  | If `LogonType` is `2` then either all three parameters can be passed to allow log on as the specified Windows user or none of them can be passed (Transparent Login using current logged on user)

When logon is successful a TCAPI Session object will be returned for future use of the API.

Errors returned will usually be either a Windows Sockets error (with `FACILITY_WIN32 7`), a Security API Error (`FACILITY_SECURITY 9`) or a King Task Centre interface specific error (`FACILITY_ITF 4`)

Sample Usage in VBScript

    Dim TCAPI, Session

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

Sample Usage in C++

    CComPtr<ITCAPI> spTCAPI;

    CComPtr<ITCAPISession> spTCAPISession;

    CComVariant varServer = "localhost";

    CComVariant varUsername = "administrator";

    CComVariant varPassword = "";

    hResult = spTCAPI.CoCreateInstance(CLSID_TCAPI, NULL, CLSID_INPROC_SERVER);

    hResult = spTCAPI->Logon(LogonKing Task Centre, varServer, varUsername, varPassword, vtMissing, &spTCAPISession);

The TCAPI Session Object (ITCAPISession

Once the logon has been successful the TCAPI Session object is the main object used to access the API. It allows access to two collections:

|  | Folders collection — A collection of folder objects that appear in the root of the tree as displayed in the King Task Centre client. Accessing the folders collection is explained later.

|  | Categories collection — A collection of category objects that are available from King Task Centre.

It also has two methods:

|  | Resolve a Task using a Task Path

|  | Open a task item based on a Task Path or ID

Object Members

Supported Members

|  | `ResolveTaskID`

|  | `OpenTaskItem`

|  | `Folders`

|  | `Categories`

ResolveTaskID Method

|  | C++
    HRESULT ResolveTaskID(BSTR TaskPath, LONG* plTaskID);

|  | VB
    Function ResolveTaskID(TaskPath As String) As Long

This method is used to resolve a path to a Task into a Task ID.

WARNING:

This method has not yet been implemented.

OpenTaskItem Method

|  | C++
    HRESULT OpenTaskItem(VARIANT TaskPathID, LPTCAPITASKITEM *ppTaskItem);

|  | VB
    Function OpenTaskItem(TaskPathID) As ITCAPITaskItem
This method is used to open a Task Object by specifying its ID

Sample Usage in VBScript

    Dim TCAPI, Session, TaskItem

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set TaskItem = Session.OpenTaskItem(13)

Folders Property

|  | C++
    HRESULT get_Folders(LPTCAPITASKFOLDERS *ppFolders);

|  | VB
    Property Get Folders() As ITCAPITaskFolders
This property exposes the Root Folders Collection. For more information on this object see the documentation for the Folders Collection object detailed later in this document

Sample Usage in VBScript

    Dim TCAPI, Session, Folders

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set Folders = Session.Folders

Categories Property

|  | C++
    HRESULT get_Categories(LPTCAPICATEGORIES *ppAvailableCategories);

|  | VB
    Property Get Categories() As ITCAPICategories
This property exposes the Root Categories Collection. For more information on this object see the documentation for the Categories Collection object detailed later in this document

Sample Usage in VBScript

    Dim TCAPI, Session, Categories

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set Categories = Session.Categories

Task Folders Collection Object (ITCAPITaskFolders)

This object can either be obtained from the session object's `Folders` property or the `ChildFolders` property of a `Folder` object. The Collection is a collection of Task Folder objects (detailed later).

Object Members

Supported Members:

|  | `_NewEnum`

|  | `Count`

|  | `Item`

Objects of this type implement the OLE Enumeration Interfaces to allow a `For Each, Next` type arrangement to be used. Also available is a `Count` and an `Item` property.

The Default property is `Item` therefore when using VBScript, `Folders(0)` is the same as `Folders.Item(0)`.

Sample Usage in VBScript

    Dim TCAPI, Session, Folders, FirstFolder, FolderCount

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set Folders = Session.Folders

    FolderCount = Folders.Count

    Set FirstFolder = Folders(0)   ' First Folder

    MsgBox "There are " & FolderCount & " Folders and the first is " & FirstFolder.Name

Task Folder Object (ITCAPITaskFolder)

Objects of this type can be obtained from the Folders Collection object either using the OLE Enumeration method or the `Count/Item` properties.

Object Members

Supported Members:

|  | `Name`

|  | `ChildFolders`

|  | `Contents`

|  | `Categories`

Properties

The object is used to represent a single folder in the tree. It has no methods and four properties. The properties expose:-

Name Property

The name of the folder.

|  | Type:

|  | String

|  | Read Only

|  | C++:

|  | `HRESULT get_Name(LPBSTR lpbstrName);`

|  | VB:

|  | `Property Get Name() As String`

ChildFolders Property

This property exposes the child folders of the current folder as a collection of Folder Items.

|  | Type:

|  | ITCAPITaskFolders Object

|  | C++:

|  | `HRESULT get_ChildFolders(LPTCAPITASKFOLDERS *ppTaskFolders);`

|  | VB:

|  | `Property Get ChildFolders() As ITCAPITaskFolders`

Contents Property

This property exposes the contents of the folder as a collection of Task Item Objects.

|  | Type:

|  | ITCAPITaskItems Object

|  | C++:

|  | `HRESULT get_Contents(LPTCAPITASKITEMS *ppTaskItems);`

|  | VB:

|  | `Property Get Contents() As ITCAPITaskItems`

Categories Property

The categories associated with this folder.

Sample Usage in VBScript

    Dim TCAPI, Session, Folders, FirstFolder

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set Folders = Session.Folders

    Set FirstFolder = Folders(0)   ' First Folder

    MsgBox "Folder name is " & FirstFolder.Name

    MsgBox "The Folder has " & FirstFolder.ChildFolders.Count & " Child Folders"

    MsgBox "The Folder has " & FirstFolder.Contents.Count & " Task Items"

    MsgBox "The Folder has " & FirstFolder.Categories.Count & " Categories"

Task Items Collection Object (ITCAPITaskItems)

Objects of this type can be obtained from the Contents property of a Folder object. The Collection is a collection of Task Item objects (detailed later)

Object Members

Supported Members:

|  | `_NewEnum`

|  | `Count`

|  | `Item`

The object implements the OLE Enumeration Interfaces to allow a `For Each, Next` type arrangement to be used. Also available is a `Count` and an `Item` property.

The Default property is `Item`. Therefore when using VBScript: `Contents(0) is the same as Contents.Item(0)`.

Sample Usage in VBScript

    Dim TCAPI, Session, Folders, TasksFolder, TaskItems

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set Folders = Session.Folders

    Set TasksFolder = Folders(1)   ' 1=Tasks Folder

    Set TaskItems = TasksFolder.Contents

    MsgBox "There are " & TaskItems.Count & " Items in the Task Item Collection"

    MsgBox "The First Task's Name is " & TaskItems(0).Name

Task Item Object (ITCAPITaskItem)

Objects of this type can be obtained from the Folders Collection object either using the OLE Enumeration method or the Count/Item properties.

Object Members

Supported Members:

|  | `Name`

|  | `TaskID`

|  | `Disabled`

|  | `TaskOwner`

|  | `Description`

|  | `Variables`

|  | `Reload`

|  | `RunSync`

|  | `RunAsync`

|  | `QueueTask`

|  | `Categories`

The object is used to represent a single task. It has a number of methods and properties to both describe and interact with the task.Supported features include:

|  | Reading Task Details

|  | Running a Task

|  | Setting Task Parameters

|  | Setting Default Variable Values

|  | Disabling/Enabling a Task

The default property is the `Name` property so `MsgBox Folder.Contents(0)` would display the tasks name for the first task in the folder.

Properties
Name Property (Default)

This property exposes the name of the Task as set in the Task's configuration. This property is Read Only, therefore it is not possible to set the Task's Name through this property.

|  | Type:

|  | String

|  | Read Only

|  | C++

|  | `HRESULT get_Name(LPBSTR lpbstrName);`

|  | VB:

|  | `Property Get Name() As String`

Description Property

This property exposes the Task's Description as set in the Task configuration. This property is Read Only, therefore it is not possible to set the Task's Description through this property.

|  | Type:

|  | String

|  | Read Only

|  | C++:

|  | `HRESULT get_Description(LPBSTR lpbstrName);`

|  | VB:

|  | `Property Get Description() As String`

TaskID Property

This property exposes the Task's numeric ID. This property is Read Only therefore it is not possible to set this Property.

|  | Type:

|  | Long

|  | Read Only

|  | C++:

|  | `HRESULT get_TaskID(LONG *pTaskID);`

|  | VB:

|  | `Property Get TaskID() As Long`

Disabled Property

This property is True if the Task is disabled and False if the Task is Enabled. The property is Read/Write so it can also be used to Enable and Disable a Task. To Disable a task just set the Property to True.

|  | Type:

|  | Boolean

|  | Read/Write

|  | C++:

|  | `HRESULT get_Disabled(VARIANT_BOOL *pVal);`

|  | `HRESULT put_Disabled(VARIANT_BOOL newVal);`

|  | VB:

|  | `Property Get Disabled() As Boolean`

|  | `Property Put Disabled(BoolVal As Boolean)`

TaskOwner Property

This property exposes the Task's Owner UserName as a String. The property is Read Only.

|  | Type:

|  | String

|  | Read Only

|  | C++:

|  | `HRESULT get_TaskOwner(LPBSTR lpbstrName);`

|  | VB:

|  | `Property Get TaskOwner() As String`

Variables Property

This property provides access to the Task's Variables Collection Object.

|  | Type:

|  | Task Variables Collection

|  | C++:

|  | HRESULT get_Variables(LPTCAPITASKVARIABLES *ppTaskVars);

|  | VB:

|  | `Property Get Variables() As ITCAPITaskVariables`

Categories Property

This property provides access to the Task's Categories Collection Object

|  | Type:

|  | Categories Collection

|  | C++:

|  | `HRESULT get_Categories(LPTCAPICATEGORIES *ppCategories);`

|  | VB:

|  | `Property Get Categories() As ITCAPICategories`

Methods
Reload Method

This method forces the API to reload the Task Details from the Data Store. It is used to ensure that the task information being read via the API is up to date.

|  | C++:

|  | `HRESULT Reload(LONG lReserved);`

|  | VB:

|  | `Sub Reload(Reserved As Long)`

RunSync Method

This method runs the Task synchronously. Therefore the call will not return until the task run has completed. The task will run using any Task Parameters set through the Variables property.

|  | C++:

|  | `HRESULT RunSync();`

|  | VB:

|  | `Sub RunSync()`

RunAsync Method

This method runs the Task asynchronously. Therefore as long as the server is able to allocate a slot for the task the call will return immediately. The task will run using any Task Parameters set through the Variables property. To obtain notification of when the Task Run completes you will need to Implement a Connection Point Sink, see later in this document for information on implementing this.

|  | C++:

|  | `HRESULT RunAsync(LONG lInstanceID);`

|  | VB:

|  | `Sub RunAsync(InstanceID As Long)`

QueueTask Method

This method runs the task by queuing a Task Run Request on the server therefore the call will return immediately. As the request is queued the task may run when the call is made or after the call returns. The task will run using any Task Parameters set through the Variables property. Using this method, it is not possible to be notified when the Task Run Completes.

|  | C++:

|  | `HRESULT QueueTask();`

|  | VB:

|  | `Sub QueueTask()`

Sample Usage in VBScript

    Dim TCAPI, Session, TaskItem

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "password")

    Set TaskItem = Session.OpenTaskItem(0) ' 1 is the Task ID

    DispStr = "Task No " & TaskItem.TaskID & " (" & TaskItem.Name & ") is "

    If TaskItem.Disabled = True Then

      DispStr = DispStr + "Disabled"

    Else

      DispStr = DispStr + "Enabled"

    End If

    MsgBox DispStr

    MsgBox "Running Task"

    TaskItem.RunSync

    If TaskItem.Disabled = False Then

      MsgBox "Task Run Completed"

    else

      MsgBox "Task Disabled - therefore not run"

    End If

Task Variables Object (ITCAPITaskVariables)

Objects of this type can be obtained from the Variables Property of the Task Item object. It can be used to see what variables exist on a task, change the default value of a variable and set task parameter values.

Object Members

Supported Members:

|  | `_NewEnum`

|  | `Count`

|  | `Item`

|  | `Reload`

|  | `UpdateStore`

The object implements the OLE Enumeration Interfaces to allow a `For Each, Next` type arrangement to be used. Also available is a `Count` and an `Item` property.

The Default property is Item therefore when using VBScript: `Contents(0)` is the same as `Contents.Item(0)`.

Methods
Reload Method

Reloads the Task Variables from the Tasks entry in the Data Store. This is used to ensure that the Task Variables collection contains the latest correct values for all variables in the collection.

UpdateStore Method

Updates the Variable Values to the Task Entry in the Data Store. This is used when variable default values are changed using the variables collection and need to be written back to the Task Entry.

Sample Usage in VBScript

    Dim TCAPI, Session, TaskItem, Vars

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set TaskItem = Session.OpenTaskItem(1) ' 1 is the Task ID

    Set Vars = TaskItem.Variables

    Msgbox "There are " Vars.Count & " variables"

Task Variable Object (ITCAPITaskVariable)
Object Members

Objects of this type can be obtained from the Variables Collection object either using the OLE Enumeration method or the `Count/Item` properties.

Supported Members:

|  | `Name`

|  | `Description`

|  | `Parameter`

|  | `VarType`

|  | `VarFlags`

|  | `Value`

|  | `ParameterValue`

Properties
Name Property

This property exposes the name of the variable.

|  | Type:

|  | String

|  | Read Only

|  | C++:

|  | `HRESULT get_Name(LPBSTR lpbstrName);`

|  | VB:

|  | `Property Get Name() As String`

Description Property

This property exposes the description of the variable.

|  | Type:

|  | String

|  | Read Only

|  | C++:

|  | `HRESULT get_Description(LPBSTR lpbstrDesc);`

|  | VB:

|  | `Property Get Description() As String`

Parameter Property

This property is True if the Variable is a Task Parameter Variable, False if it is not.

|  | Type:

|  | Boolean

|  | C++:

|  | `HRESULT get_Parameter(VARIANT_BOOL *pParam);`

|  | VB:

|  | `Property Get Parameter() As Boolean`

VarType Property

This property exposes the Type of the Variable. The possible types are part of an enumeration. The enumeration values are available in the type library or via `iwcltcp.h`.

|  | Type:

|  | LPTCAPI_TVT

|  | C++:

|  | `HRESULT get_VarType(LPTCAPI_TVT *pVarType);`

|  | VB:

|  | `Property Get VarType() As TCAPI_TVT`

The types available are:

|  | `TvtVariant 0`

|  | `TvtStructured 5`

VarFlags Property

This property will contain a bitmask representing whether a parameter variable is In, In/Out, or Out.

|  | Type:

|  | LPTCAPI_TVF

|  | C++:

|  | `HRESULT get_VarFlags(LPTCAPI_TVF *pVarFlags);`

|  | VB:

|  | `Property Get VarFlags() As TCAPI_TVF`

The flags available are:

|  | `TpfIn 1`

|  | `TpfOut 2`

|  | `TpfIn | TpfOut 3`

Value Property

The `Value` property will set the default value of the variable which can be persisted back to the task's entry in the Data Store. Currently this is only available for non-array and non-structured types. Valid variants are variants such as String, Long, Currency, Date/Time etc.

|  | Type:

|  | VARIANT

|  | Read/Write

|  | C++:

|  | `HRESULT get_Value(LPVARAINT pVar);`

|  | `HRESULT put_Value(VARIANT var);`

|  | VB:

|  | `Property Get Value()`

|  | `Property Put Value(Var)`

See Reload and UpdateStore for information on the loading and saving of these values.

ParameterValue Property

The `ParameterValue` property will set the parameter values to use before a task is run, they apply to the task run only and do not normally affect the task in the store directly. This property can vary considerably depending on the variable type.

|  | Type:

|  | VARIANT

|  | Read/Write

|  | C++:

|  | `HRESULT get_ParameterValue(LPVARAINT pVar);`

|  | `HRESULT put_ParameterValue(VARIANT var);`

|  | VB:

|  | `Property Get ParameterValue()`

|  | `Property Put ParameterValue(Var)`

ParameterValue with String, Long, Currency, Date/Time types

When used with simple types, the `ParameterValue` variant can just be used to carry the data as normal.

ParameterValue with Structured Types

When used with structured types, the `ParameterValue` will contain an instance of an object that can be used to set the structured type members.

For example:

    Var.ParameterValue.Filename = "file.txt"

    Var.ParameterValue.Size = 200

ParameterValue with Array Types

When the `ParameterValue` is an array type, the `ArraySize` and `Element` properties are used to access the elements in the array and the `CreateNewItem` and `AddItem` methods are used to build the array.

To access the elements in the array:

    For elementIndex = 0 to Var.ParameterValue.ArraySize - 1

    Set element = Var.ParameterValue.Element(elementindex)

… etc ..

Next

e.g. To add simple value elements to the array:

    Var.ParameterValue.AddToArray 10

    Var.ParameterValue.AddToArray "String"

e.g. To add a structured value to the array:

    Set newitem = Var.ParameterValue.CreateNewItem()

    newitem.Member1 = value

    newitem.Member2 = value

    Var.ParameterValue.AddToArray newitem

The Variable Array Accessor (ITCAPIVarArrayAccessor)
Object Members

Objects of this type can be obtained from the `ParameterValue` property of Variable objects of type `Array`.

Supported Members:

|  | `Element`

|  | `ArraySize`

|  | `CreateNewItem`

|  | `AddItem`

Element

This property allows array elements to be accessed. It is possible to both write to and read from an element in the array.

|  | Type:

|  | Variant

|  | Read/Write

|  | C++:

|  | `HRESULT get_Element(LONG lIndex, LPVARIANT pVar);`

|  | `HRESULT put_Element(LONG lIndex, VARIANT var);`

|  | VB:

|  | `Property Get Element()`

|  | `Property Put Element(var)`

ArraySize

This is a read only property exposing the number of elements in the array.

|  | Type:

|  | Long

|  | Read Only

|  | C++:

|  | `HRESULT get_ArraySize(LONG *lSize);`

|  | VB:

|  | `Property Get ArraySize() As Long`

CreateNewItem

This method is only appropriate for arrays of structured variables. This method creates a new Structured Variable object which can be added to the array with `AddItem()`.

|  | C++:

|  | `HRESULT CreateNewItem(LPDISPATCH *ppDisp);`

|  | VB:

|  | `Function CreateNewItem() As Object`

AddItem

This method allows elements to be added to the array. Depending on the variable type you can add either values or structured variable objects created by `CreateNewItem()`

|  | C++:

|  | `HRESULT AddItem(VARIANTARG varg);`

|  | VB:

|  | `Sub AddItem(var)`

Categories Collection Object (ITCAPICategories)

This object can either be obtained from the session objects `Categories` property or the `Categories` property of a Folder or Item object. The Collection is a collection of Category objects (detailed later)

Object Members

Supported Members:

|  | `_NewEnum`

|  | `Count`

|  | `Item`

Objects of this type implement the OLE Enumeration Interfaces to allow a `For Each, Next` type arrangement to be used. Also available is a `Count` and an `Item` property.

The Default property is `Item` therefore when using VBScript: `Categories(0)` is the same as `Categories.Item(0)`.

Sample Usage in VBScript

    Dim TCAPI, Session, Folders, CategoryCount

    Const LogonKing Task Centre = 1

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonKing Task Centre, "localhost", "administrator", "")

    Set Folders = Session.Folders

    Set FirstFolder = Folders(0)   ' First Folder

    MsgBox "There are " & Session.Categories.Count & " Categories available and " & FirstFolder.Categories.Count & " categories apply to the " & FirstFolder.Name & " folder."

Import Options Object (IImportOptions)

This object can either be obtained from the session objects ImportOptions. The Collection is a collection of Import objects (detailed later)

Object Members

Supported Members:

|  | `Tasks`

|  | `Folders`

|  | `Repositories`

|  | `Variables`

|  | `Functions`

|  | `OverwriteOption`

|  | `DoNothingOption`

|  | `CreateNewOption`

|  | `RepositoryOverWriteSchemaOnlyOption`

Sample Usage in VBScript

    Option Explicit

    Dim TCAPI, Session, ImportOptions

    Const LogonWindows = 2

    Set TCAPI = CreateObject("Iwcltcp.TCAPI")

    Set Session = TCAPI.Logon(LogonWindows, "localhost")

    Set ImportOptions = CreateObject("iwcltcp.ImportOptions")

    ImportOptions.Tasks = ImportOptions.DoNothingOption

    ImportOptions.Folders = ImportOptions.OverwriteOption

    ImportOptions.Repositories = ImportOptions.RepositoryOverWriteSchemaOnlyOption

    ImportOptions.Variables = ImportOptions.DoNothingOption

    ImportOptions.Functions = ImportOptions.DoNothingOption

    ImportOptions.Formulas = ImportOptions.DoNothingOption

    Session.ImportTaskFile "taskname.tks", "\", ImportOptions

Category Object (ITCAPICategory)

Objects of this type can be obtained from the Folders Collection object either using the OLE Enumeration method or the `Count/Item` properties.

Object Members

Supported Members:

|  | `Name`

|  | `Description`

The object is used to represent a single category. It has no methods and two properties.

Name Property

Description Property

This property exposes the Category's Description as set in the configuration. This property is Read Only, therefore it is not possible to set the Description through this property.

|  | Type:

|  | String

|  | Read Only

|  | C++:

|  | `HRESULT get_Description(LPBSTR lpbstrName);`

|  | VB:

|  | `Property Get Description() As String`

Properties

TCAPI Session Events Interface (ITCAPISessionEvents)

This is an events interface which is used to receive notifications from the API. It is optional and can be implemented to allow the TCAPI System to provide notifications on particular events occurring within the King Task Centre system.

|  | IDL:

`[id(1)] HRESULT NotifyAsyncCallComplete([in] LONG InstanceID);`

The `NotifyAsyncCallComplete` Event Handler will receive notifications when an Asyncronous Task run has completed. The `InstanceID` will match the `InstanceID` passed to the initial call to `RunAsync()`. Currently the Task out parameters are not available from an `RunAsync` request.

|  | IDL:

`[id(2)] HRESULT APINotify([in] LONG lNotifyInfo);`

The `APINotify` Event Handler will receive general notifications regarding the connection to the server. Currently the only notification is the notification that the API has had to reconnect to the server.

Triggering Tasks to run from a web page

The following sample code may be used to trigger a Task to run from a web page.

    <%

      Const LogonKing Task Centre = 1

      Const LogonWindows = 2

      RequestType = Request.QueryString("Btn")

      InpValue = Request.QueryString("Inp1")

      If RequestType = "RunTask" Then

      Set TCAPI = Server.CreateObject("Iwcltcp.TCAPI")

      Set TCAPISession = TCAPI.Logon(LogonKing Task Centre, "kpdev", "script", "script")

      Set TaskItem = TCAPISession.OpenTaskItem(0)

      Set Vars = TaskItem.Variables

      Vars.Item("test").ParameterValue = InpValue

      TaskItem.RunSynch

      var = CStr(Vars.Item("test").ParameterValue)

      End If

    %>

    <HTML>

      <BODY>

        <FORM action ="<%=Request.ServerVariables("URL") %>"method="get">

          <BR>Push Button - <input type="Submit" value="RunTask" name="Btn" id="Btn">

          <input type="text" name="Inp1" value="<%=var%>">

        </FORM>

      </BODY>

    </HTML>

## Examples of Usage

Passing Single Values of Simple Types to Tasks — OrderNo is a Variant In Parameter Variable

    Dim tcapi

    Set tcapi = WScript.CreateObject("iwcltcp.TCAPI")

    Set session = tcapi.Logon(1, "localhost", "administrator", "password")

    Set taskitem = session.OpenTaskItem(taskid)

    taskitem.Variables("OrderNo").ParameterValue = "12345"

    taskitem.RunSync

Passing Single Structured Type Values to Tasks — FileInfo is a Datafile In Parameter Variable

    Dim tcapi

    Set tcapi = WScript.CreateObject("iwcltcp.TCAPI")

    Set session = tcapi.Logon(1, "localhost", "administrator", "password")

    Set taskitem = session.OpenTaskItem(taskid)

    taskitem.Variables("FileInfo").ParameterValue.Filename = “file.txt”

    taskitem.Variables("FileInfo").ParameterValue.Data = “Data2”

    taskitem.Variables("FileInfo").ParameterValue.Size = 5

    taskitem.RunSync

Passing Structured Type Arrays to Tasks (that is, Array’s of Datafile objects) — FileArray is a Datafile Array In Parameter Variable

    Dim tcapi

    Set tcapi = WScript.CreateObject("iwcltcp.TCAPI")

    Set session = tcapi.Logon(1, "localhost", "administrator", "password")

    Set taskitem = session.OpenTaskItem(taskid)

    Set arrayparam = taskitem.Variables("FileArray").ParameterValue

    Set itemone = arrayparam.CreateNewItem()

    itemone.Filename = "file.txt"

    itemone.Data = "Data"

    itemone.Size = 4

    Set itemtwo = arrayparam.CreateNewItem()

    itemtwo.Filename = "file2.txt"

    itemtwo.Data = "Data2"

    itemtwo.Size = 5

    arrayparam.AddItem(itemone)

    arrayparam.AddItem(itemtwo)

    taskitem.RunSync

Copyright © 2018 Quadrant Software B.V. All rights reserved.