Citect Pty Ltd

3 Fitzsimmons Lane
Gordon NSW 2072
Australia
www.citect.com

















Batch API




























Version

1.1.0



2
Document: CitectSCADA Batch API.doc
Author: J . Ewen


DISCLAIMER

Citect Pty. Limited makes no representations or warranties with respect to this manual and, to
the maximum extent permitted by law, expressly limits its liability for breach of any warranty
that may be implied to the replacement of this manual with another. Further, Citect Pty. Limited
reserves the right to revise this publication at any time without incurring an obligation to notify
any person of the revision.

COPYRIGHT

Copyright 2004 Citect Pty Limited. All rights reserved.

TRADEMARKS

Citect Pty Limited has made every effort to supply trademark information about company
names, products and services mentioned in this manual. Trademarks shown below were
derived from various sources.

CitectSCADA, CitectHMI/SCADA, CitectFacilities and CitectSCADA Batch are registered
trademarks of Citect Pty. Limited.

IBM, IBM PC and IBM PC AT are registered trademarks of International Business Machine
Corporation.

MS-DOS, Windows, Windows 98, Windows 2000, Windows XP and Excel are trademarks of
Microsoft Corporation.

dBase is a trademark of Borland Inc.

General Notice:
Some product names used in this manual are used for identification purposes only and may be
trademarks of their respective companies.




November 2004 Edition for CitectSCADA Batch
Manual Revision 1.0.0
3
Document: CitectSCADA Batch API.doc
Author: J . Ewen



TABLE OF CONTENTS

1 BATCH API ........................................................................................................................................................ 4
1.1 INCLUDE FILE BAPI.H FOR C++.................................................................................................................. 4
1.2 INCLUDE FILES FOR BASIC........................................................................................................................... 4
1.3 ERROR NO.................................................................................................................................................... 5
1.3.1 General Errors ........................................................................................................................................ 5
1.3.2 Connection Errors................................................................................................................................... 5
1.3.3 Invalid reference Errors.......................................................................................................................... 5
1.3.4 User Error ............................................................................................................................................... 5
1.3.5 Batch Error.............................................................................................................................................. 5
1.4 STATES OF BATCH........................................................................................................................................ 6
1.4.1 Batch State............................................................................................................................................... 6
1.4.2 Scheduler State........................................................................................................................................ 6
1.4.3 Batch Mode.............................................................................................................................................. 6
1.4.4 Batch Command...................................................................................................................................... 6
1.5 COMMON FUNCTIONS FOR SERVER AND CLIENT API:................................................................................. 7
1.5.1 short Open(void); .................................................................................................................................... 7
1.5.2 short Close(void);.................................................................................................................................... 7
1.5.3 short SetLogLevel(short loglevel );......................................................................................................... 7
1.5.4 short SetTimeOut(int time); .................................................................................................................... 8
1.6 BATCH SERVER API ..................................................................................................................................... 9
1.6.1 short BSOpen(LPCTSTR primary, LPCTSTR secondary, LPCTSTR catalog, short port ) .................. 9
1.6.2 short BSSetTankLot(LPCTSTR tank_uid, LPCTSTR lot, LPCTSTR user_uid)..................................... 9
1.6.3 short BSSetTankActive(LPCTSTR tank_uid, bool active, LPCTSTR user_uid) .................................. 10
1.6.4 short BSSetTankMat(LPCTSTR tank_uid, LPCTSTR rawmat_no, LPCTSTR user_uid).................... 10
1.6.5 short BSSetTankQty(LPCTSTR tank_uid, LPCTSTR rawmat_qty, LPCTSTR user_uid) ................... 11
1.6.6 short BSCreateNewOrder(LPCTSTR order_no, LPCTSTR prod_no, LPCTSTR prod_size, LPCTSTR
areauid, LPCTSTR celluid, LPCTSTR planstart, LPCTSTR user_uid) ............................................................ 11
1.6.7 short BSCreateNewMaterial(LPCTSTR mat_no, LPCTSTR mat_name, bool endprod, bool
hasingredients, LPCTSTR user_uid, LPCTSTR comment, LPCTSTR approvedby, LPCTSTR approveddate)12
1.6.8 short BSCreateNewIngredient(LPCTSTR mat_no, LPCTSTR prod_no, LPCTSTR mat_qty, short pos,
LPCTSTR user_uid)............................................................................................................................................ 13
1.6.9 short BSDeleteProdData(LPCTSTR order_no, LPCTSTR batch_no, LPCTSTR user_uid)............... 13
1.6.10 short BSSetMatQtyInMR(LPCTSTR mr_id, LPCTSTR rawmat_no, LPCTSTR rawmat_qty,
LPCTSTR user_uid)............................................................................................................................................ 14
1.7 BATCH CLIENT API .................................................................................................................................... 15
1.7.1 short BCOpen(LPCTSTR p_host, short p_port, LPCTSTR s_host, short s_port)............................... 15
1.7.2 short BCControlCR(LPCTSTR ControlRecipe_ID, short cmd, LPCTSTR user_uid)......................... 15
1.7.3 short BCGetCRStatus(LPCTSTR ControlRecipe_ID).......................................................................... 16
1.7.4 short BCChangeCRMode(LPCTSTR ControlRecipe_ID, short imode, LPCTSTR user_uid) ............ 16
1.7.5 short BCChangeCRStarttime(LPCTSTR ControlRecipe_ID, LPCTSTR Starttime, LPCTSTR
user_uid) ............................................................................................................................................................. 18
4
Document: CitectSCADA Batch API.doc
Author: J . Ewen



1 Batch API
The shipment of the Batch API includes the following files:
Batch Server API: CTBSAPI.dll
Batch Server API Library File: CTBSAPI.lib
Batch Client API: CTBCAPI.dll
Batch Client API Library File: CTBCAPI.lib
Include Header File: BAPI.h
Include Bas File Server: CTBSAPI.bas
Include Bas File Client: CTBCAPI.bas

1.1 Include File BAPI.h for C++
File name: BAPI.h
Version: 1.0.0
Date: 08.06.2004

The calling convention of the API Functions is __stdcall by dynamic loading of the DLL.
Example for the API Function short SetLogLevel(short loglevel );
typedef short (_stdcall * PFSetLogLevelDLL)(short);
1.2 Include Files for Basic
File name: CTBSAPI.bas
Version: 1.0.0
Date: 29.07.2004
Include File for Server API

File name: CTBCAPI.bas
Version: 1.0.0
Date: 25.08.2004
Include File for Client API

5
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.3 Error No
1.3.1 General Errors
CTB_NO_ERROR 0 no Error
CTB_ERROR_UNKNOWN -101 unknown Error
CTB_ERROR_COM_ERROR -102 Communication Error
CTB_ERROR_UNKNOWN_CMD -103 unknown commando
CTB_ERROR_SQL -104 SQL Error / General Database error
CTB_ERROR_XML -105 XML Error / General communication error
CTB_ERROR_TIME_OUT -106 Time out error
1.3.2 Connection Errors
CTB_ERROR_OPEN_FAILED -201 Can not open connection to Server
CTB_ERROR_CLOSE_FAILED -202 Can not close connection to Server
CTB_ERROR_NO_CONNECTION -203 Primary Host unknown / not found
CTB_ERROR_IS_OPEN -204 Connection is already opened
1.3.3 Invalid reference Errors
CTB_ERROR_TANK_UID -300 unknown Tank UID
CTB_ERROR_MAT_NO -301 unknown Material No
CTB_ERROR_PROD_NO -302 unknown Product No
CTB_ERROR_BATCH_PROD_NO -303 unknown Batch or Product No
CTB_ERROR_AREA_UID -304 unknown Area UID
CTB_ERROR_CELL_UID -305 unknown Cell UID
CTB_ERROR_MAT_NOT_APPROVED -306 Material is created, but not apporved
CTB_ERROR_WRONG_TIME_FORMAT -307 wrong time format (American Time format)
CTB_ERROR_GENERAL -111 General error, see the Logfile for more
information

CTB_ERROR_ORDER_NO -308 Order No already exist
CTB_ERROR_MATERIAL_NO -309 Material No already exist
CTB_ERROR_MR -310 unknown MR ID
1.3.4 User Error
CTB_ERROR_USER_UID -320 unknown User UID
CTB_ERROR_USER_BLOCKED -321 User Acount is blocked
CTB_ERROR_USER_NO_RIGHT -322 User has no rights for this action

1.3.5 Batch Error
ERROR_WRONG_BATCH_CMD -400 invalid Batch - Command
ERROR_WRONG_BATCH_STATE -401 invalid Batch - State for this action
ERROR_ANSWER_FROM_CTBE -402 error in Answer from CTBE, see the Logfile
for more information
6
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.4 States of Batch
1.4.1 Batch State
BATCH_COMPLETE 301
BATCH_RUNNING 302
BATCH_IDLE 303

BATCH_ABORTING 310
BATCH_ABORTED 311
BATCH_STOPPING 312
BATCH_STOPPED 313
BATCH_PAUSING 314
BATCH_PAUSED 315
BATCH_HOLDING 316
BATCH_HELD 317
BATCH_RESTARTING 318

BATCH_HOLDING_FOR_ERROR 326
BATCH_HELD_FOR_ERROR 327

1.4.2 Scheduler State
BATCH_COMPETE 201
BATCH_INPROGRESS 202
BATCH_SCHEDULED 203
BATCH_ASSIGNED 205

1.4.3 Batch Mode
BATCH_RECIPE_AUTO 0 Automatic
BATCH_RECIPE_SEMI 1 Semi automatic
BATCH_RECIPE_MANUAL 2 manual

1.4.4 Batch Command
BATCH_RECIPE_START 1 command to start a batch
BATCH_RECIPE_STOP 2 command to stop a batch
BATCH_RECIPE_HOLD 3 command to hold a batch
BATCH_RECIPE_ABORT 4 command to abord a batch
BATCH_RECIPE_RESTART 5 command to restart a batch
BATCH_RECIPE_PAUSE 6 command to hold a batch
BATCH_RECIPE_RESUME 7 command to resume a batch
BATCH_RECIPE_SCHEDULE 8 command to release a batch
BATCH_RECIPE_UNSCHEDULE 9 command to unschedule a batch
BATCH_RECIPE_UNLOAD 10 command to unload a batch
7
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.5 Common Functions for Server and Client API:
1.5.1 short Open(void);
Name: Open
Parameter: none

Description:
CTBSAPI:
Open the connection to the Database. The connection key of the BatchEngine is used.
When no BatchEngine is installed on the PC, use the Function BSOpen().

CTBCAPI:
Open the connection to the Batch Engine. The connection key of the CTBSCTRL.OCX is
used.
When no Batch Scheduler / Viewer is installed on the PC, use the Function BCOpen().


Return value:
0 if the connection is successfully open, otherwise an Error No (see 1.3.2).

1.5.2 short Close(void);
Name: Close
Parameter: none

Description:
CTBSAPI:
Close the connection to the Database.

CTBCAPI:
Close the connection to the Batch Engine.

Return value:
0 if the connection is successfully closed, otherwise an Error No (see 1.3.2).


1.5.3 short SetLogLevel(short loglevel );
Name: SetLogLevel
Parameter: short Loglevel

Description:
Set the Log level of the DLL.
Possible Values:
0 Debug
1 Low
2 Medium
3 High

Return value:
0 if successful, otherwise -999


8
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.5.4 short SetTimeOut(int time);
Only supported in the Batch Client API.

Name: SetTimeOut
Parameter: int Time

Description:
Set the Time out .

Return value:
0 if successful, otherwise -999


9
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.6 Batch Server API
File name: CTBSAPI.dll
Version 1.0.1.0
Date: 03.09.2004

1.6.1 short BSOpen(LPCTSTR primary, LPCTSTR secondary, LPCTSTR catalog,
short port )
Name: BSOpen
Parameter:
String PrimaryHost
String SecondaryHost
String CatalogName
Short Port No

Description:
Open the connection to the Database by using of the assigned parameter
PHost / SHost is the PC Name or IP Address +\Batch

Return value:
0 if the connection is successfully open, otherwise an Error No (see 1.3.2).

Example:
short iResult =BSOpen(PirmServer\Batch,StdbyServer\Batch,BatchProject,4300);

1.6.2 short BSSetTankLot(LPCTSTR tank_uid, LPCTSTR lot, LPCTSTR
user_uid)
Name: BSSetTankLot
Parameter:
String TankUID
String LotNo
String UserUID

Description:
Update the Lot No of the assigned Tank.

Return value:
0 if successful
-300 unknown Tank UID
-320 Unknow User UID
-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database

10
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.6.3 short BSSetTankActive(LPCTSTR tank_uid, bool active, LPCTSTR
user_uid)
Name: BSSetTankActive
Parameter:
String TankUID
Bool Flag
String UserUID

Description:
Set the assigned Tank to Active or Inactive.

Return value:
0 if successful
-300 unknown Tank UID
-320 Unknow User UID
-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database
1.6.4 short BSSetTankMat(LPCTSTR tank_uid, LPCTSTR rawmat_no, LPCTSTR
user_uid)
Name: BSSetTankMat
Parameter:
String TankUID
String MaterialNo
String UserUID

Description:
Update the Material in the assigned Tank.

Return value:
0 if successful
-300 unknown Tank UID
-301 unknown Material No
-320 Unknow User UID
-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database


11
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.6.5 short BSSetTankQty(LPCTSTR tank_uid, LPCTSTR rawmat_qty, LPCTSTR
user_uid)
Name: BSSetTankMat
Parameter:
String TankUID
String Material Quantity
String UserUID

Description:
Update the Material Quantity in the assigned Tank.

Return value:
0 if successful
-300 unknown Tank UID
-301 unknown Material No
-320 Unknow User UID
-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database


1.6.6 short BSCreateNewOrder(LPCTSTR order_no, LPCTSTR prod_no,
LPCTSTR prod_size, LPCTSTR areauid, LPCTSTR celluid, LPCTSTR
planstart, LPCTSTR user_uid)
Name: BSCreateNewOrder
Parameter:
String Order No
String Product No
String Product Size
String Area UID
String Cell UID
String Plant Start Time
String User UID

Description:
Create a new Order

The Order No has to unique
The Product No has to exist
The Product size is the complete Quantity of the order
The Area UID has to exist
The Cell UID has to exist
The Pant Start Time has to be in American time format or leave this filed blank
The User UID has to exist

Return value:
0 if successful
-301 unknown Product No
-304 unknown Area UID
-305 unknown Cell UID
-307 wrong time format
-308 Order No already exist
-320 Unknow User UID
12
Document: CitectSCADA Batch API.doc
Author: J . Ewen


-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database

1.6.7 short BSCreateNewMaterial(LPCTSTR mat_no, LPCTSTR mat_name, bool
endprod, bool hasingredients, LPCTSTR user_uid, LPCTSTR comment,
LPCTSTR approvedby, LPCTSTR approveddate)
Name: BSCreateNewMaterial
Parameter:
String Material No / Product No
String Material Name / Product Name
Bool Flag End product 1: true (for Product)
Bool Flag Has ingredients 1:true (for Product)
String User UID
String Comment
String UserUID of Approver
String Approved Date (American time format)

Description:
Create a new Product or Raw Material

The Material / Product No has to be unique
The User UID has to exist
If no UserUID for the Approver exist the Material / Product is created, but not approved
Is the UserUID for the Approver exist, but the Approved Date has wrong format, the Material /
Product will created, but not approved

The Flags End product and has ingredients has to be 0 if a Raw material should be
created.

If a Product should be created, call additional to this function the function
BSCreateNewIngredient() where Mat_No =Prod_No and the Mat_Qty is the absolute Product
Size.
BSCreateNewIngredient(Mat_No, Prod_No, Prod_Qty, Pos =0, User_UID)

Example:
BSCreateNewMaterial(Prod_1,Choco,1,1,999,no comment,999,07/14/2004);
BSCreateNewIngredient(Prod_1, Prod_1,50000,0, 999)


Return value:
0 if successful
-306 Material / Product created, but not approved
-307 wrong time format
-309 Material / Product No already exist
-320 Unknow User UID
-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database

13
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.6.8 short BSCreateNewIngredient(LPCTSTR mat_no, LPCTSTR prod_no,
LPCTSTR mat_qty, short pos, LPCTSTR user_uid)
Name: BSCreateNewIngredient
Parameter:
String Material No
String Product No
String Quantity
Short Position
String User UID

Description:
Add the Raw Material to the Material List of the Product

The Material No has to exist
The Product No has to exist
The Position is the Sort order of the Material List

Return value:
0 if successful
-301 unknown Material No
-302 unknown Product No
-320 Unknow User UID
-321 User Acount is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database


1.6.9 short BSDeleteProdData(LPCTSTR order_no, LPCTSTR batch_no,
LPCTSTR user_uid)
Name: BSDeleteProdData
Parameter:
String Order No
String Batch No
String User UID

Description:
Delete all production data of the Batch.
This function should be called, after the Batch Report is created to decrease the size of the
Database. Is the Batch Report is created, the data is not longer needed in the Database.

Return value:
0 if successful
-303 Unknown Order No or Batch No
-320 Unknown User UID
-321 User Account is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database


14
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.6.10 short BSSetMatQtyInMR(LPCTSTR mr_id, LPCTSTR rawmat_no,
LPCTSTR rawmat_qty, LPCTSTR user_uid)
Name: BSSetMatQtyInMR
Parameter:
String Master recipe ID
String Raw material No
String Raw material quantity
String User UID

Description:
The function will update in the selected Master recipe the quantity of the selected Raw
material.
In Addition the quantity of the selected Raw material in the Product List of the assigned Master
recipe Product will be updated.
The Product Size will recalculate automatically

The MR_ID has to exist
The Mat_No has to exist
The User_ID has to exist

The IDs for Master Recipe and Material are available in the public View: VW_Public_BOM

Return value:
0 if successful
-301 Unknown Material No
-310 Unknown Master Recipe ID
-320 Unknown User UID
-321 User Account is blocked
-322 User has no rights for this action
-203 Database not available
-104 Error by execute SQL in Database


15
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.7 Batch Client API
File name: CTBCAPI.dll
Version: 1.0.0
Date: 03.09.2004

1.7.1 short BCOpen(LPCTSTR p_host, short p_port, LPCTSTR s_host, short
s_port)
Name: BOpen
Parameter:
String Primary Host
Short Primary Port
String Standby Host
Short Standby Port

Description:
Open the connection to the batch Engine by using of the assigned parameter
P_Host / S_Host is the PC Name or IP Address
P_Poprt / S_port is the port of the connection

Return value:
0 if the connection is successfully open, otherwise an Error No (see 1.3).

Example:
short iResult =BCOpen(PirmServer,4002,StdbyServer,4002);

The Port 4002 is the default port for the BatchViewer / BatchScheduler.

1.7.2 short BCControlCR(LPCTSTR ControlRecipe_ID, short cmd, LPCTSTR
user_uid)
Name: BCControlCR
Parameter:
String Controlrecipe_ID
Short cmd
String User UID

Description:
Sent the CMD to the Batch Engine to control the Batch

Return value:
0 if the cmd is successfully executed
-101 Unknown error
-203 Database not available
-105 Error XML
-106 Time out
-111 General error, see the Logfile for more information
-400 Wrong Batch Command

Example:
short iResult =BCControlCR(204,1,999);

The control recipe will start.

Definition of cmd see 1.4.4
16
Document: CitectSCADA Batch API.doc
Author: J . Ewen



The Controlrecipe_ID will be available in the public View: VW_PUBLIC_CR
Also the Scheduler States and Batch States are available in this view
It is recommended using this data.

1.7.3 short BCGetCRStatus(LPCTSTR ControlRecipe_ID)
Name: BCGetCRStatus
Parameter:
String Controlrecipe_ID

Description:
Return state of the Batch

Return value:
otherwise an Error No (see 1.3).
Return value:
The State No of the Control Recipe (Values 301 - 327),
-101 Unknown error
-203 Database not available
-105 Error XML
-106 Time out
-111 General error, see the Logfile for more information
-400 Wrong Batch Command



Example:
short iResult =BCGetCRStatus (204);

The Controlrecipe_ID will be available in the public View: VW_PUBLIC_CR
Also the Scheduler States and Batch States are available in this view
It is recommended using this data.

1.7.4 short BCChangeCRMode(LPCTSTR ControlRecipe_ID, short imode,
LPCTSTR user_uid)
Name: BCChangeCRMode
Parameter:
String Controlrecipe_ID
Short mode
String User UID

Description:
Set a new Mode of the Batch

Return value:
0 if the cmd is successfully executed, otherwise an Error No (see 1.3).

Example:
short iResult =BCChangeCRMode (204,1,999);

The Mode will set to semi automatic

The Controlrecipe_ID will be available in the public View: VW_PUBLIC_CR
Also the Scheduler States and Batch States are available in this view
17
Document: CitectSCADA Batch API.doc
Author: J . Ewen


It is recommended using this data.

18
Document: CitectSCADA Batch API.doc
Author: J . Ewen


1.7.5 short BCChangeCRStarttime(LPCTSTR ControlRecipe_ID, LPCTSTR
Starttime, LPCTSTR user_uid)
Name: BCChangeCRStarttime
Parameter:
String Controlrecipe_ID
String Start time
String User UID

Description:
Set a new planned start time of the Batch

Return value:
0 if the cmd is successfully executed, otherwise an Error No (see 1.3).

Example:
short iResult =BCChangeCRMode (204,2004-08-25 15:25:00,999);

The start time will set to 2004-08-25 15:25:00

The time has to be in American time format

The Controlrecipe_ID will be available in the public View: VW_PUBLIC_CR
Also the Scheduler States and Batch States are available in this view
It is recommended using this data.