Micro Focus Solutions Business Manager API...2020/02/26 · 2 Dear Customer, This document...

Copyright © 1998 - 2020 Micro Focus or one of its affiliates.

Micro Focus Solutions Business Manager API

Reference Guide

Solutions Business Manager Version 11.7.1

Last updated: February 26, 2020

2

Dear Customer,

This document describes the SBM Application Programming Interface (API). Through

the API you can extend SBM functionality to meet your company needs.

Micro Focus recommends performing database modifications through the SBM System

Administrator or by creating an application that uses the API. Alterations that cannot be

done through the SBM System Administrator should be performed through the API.

Micro Focus makes best efforts to ensure upward compatibility should database changes

be performed in this manner. The API is available to all SBM customers.

The SBM API is written in C++. Applications can be written to this API, which import

and export data between SBM applications and other application programs. C++

programming experience is required to create an application using this class library.

Micro Focus does not support the API through its standard Customer Support contract.

API support is available in time-blocks through our Professional Services Group (PSG).

PSG staffs expert C++ developers who are available to support and/or develop these

applications to meet your needs. Should you need assistance in creating or understanding

API classes, please contact your sales executive.

For more information about securing services to support and/or develop API applications

to meet your needs, contact your account manager.

Thank you,

Micro Focus

3

Table of Contents

Micro Focus ................................................................................................................................................... 2

Table of Contents ........................................................................................................................................... 3

Revision History ............................................................................................................................................. 6

Introduction ................................................................................................................................................... 8

Overview.................................................................................................................................................... 8

Getting Started.......................................................................................................................................... 8

Building the API and Sample Programs ................................................................................................ 8

Preprocessor Symbols and Platform Dependencies ............................................................................... 9

Object Hierarchy ...................................................................................................................................... 9

Class Synopsis ..........................................................................................................................................10

Generic Classes .....................................................................................................................................11

Database Representation Classes ...........................................................................................................11

Browser-Mimicking Classes ..................................................................................................................11

Classes the API Programmer will most likely use on a regular basis ....................................................11

List of TSDynaColumn ...........................................................................................................................13

TSDynaColumnList .................................................................................................................................13

TSDynaRecord .........................................................................................................................................13

TSDynaRecordList ..................................................................................................................................13

TSDynaValue ...........................................................................................................................................13

TSDynaValueList ....................................................................................................................................13

Pointer to a position in a list, for iterating through a list of TSRecord, TSDynaColumn .................14


TSDynaRecord .........................................................................................................................................14


TSDynaValue ...........................................................................................................................................14


Additional classes the typical API Programmer should never need to use ............................................15

Table Dependencies and Schema Information ......................................................................................15

TS_LASTIDS ........................................................................................................................................15

Reading Data From Tables ....................................................................................................................15

Primary Tables Are Special ...................................................................................................................16

Hierarchical Items .................................................................................................................................16

Table Schemas .......................................................................................................................................16

Field Schema Notes ...............................................................................................................................16

Helpful Schema Information .................................................................................................................16

4

Journal Fields ..........................................................................................................................................17

Quick Overview of TSServer Methods ..................................................................................................18

Steps to Building a Simple API Application Program .........................................................................23

Trouble Shooting ..........................................................................................................................................25

TS_SOCKET_READ_ERROR .............................................................................................................25

TS_SERVER_ERROR ..........................................................................................................................25

TS_SOCKET_CONNECT_FAILED ....................................................................................................25

Sample Programs ..........................................................................................................................................26

ConsolidateFields .....................................................................................................................................26

DeletedItemsReport .................................................................................................................................26

GetTableId ...............................................................................................................................................26

ListGroupMembers .................................................................................................................................26

ListGroups ...............................................................................................................................................26

ListPrivs ...................................................................................................................................................26

ReadListWithWhere ...............................................................................................................................26

ReadRecord ..............................................................................................................................................26

ReadRecordMFC .....................................................................................................................................27

ReadRecordWininet ................................................................................................................................27

ReadRecordWininet_LIB .......................................................................................................................27

ReadUser ..................................................................................................................................................27

ReadWithWhere ......................................................................................................................................27

ShowAvailableTables ..............................................................................................................................27

Submit.......................................................................................................................................................27

Transition .................................................................................................................................................28

Update.......................................................................................................................................................28

TSAPI Object Definitions .............................................................................................................................29

TSAttachment ..........................................................................................................................................29

TSAuxiliaryItem ......................................................................................................................................32

TSChangeHistory ....................................................................................................................................33

TSDisplayField .........................................................................................................................................35

TSDynaColumn .......................................................................................................................................39


TSDynaRecord .........................................................................................................................................40


TSDynaValue ...........................................................................................................................................42


TSField .....................................................................................................................................................43

5

TSFieldList ...............................................................................................................................................46

TSIntList ..................................................................................................................................................47

TSIntObject .............................................................................................................................................48

TSItem ......................................................................................................................................................49

TSItemLink ..............................................................................................................................................55

TSList .......................................................................................................................................................57

TSObject...................................................................................................................................................59

TSPosition ................................................................................................................................................60

TSPrimaryItem ........................................................................................................................................61

TSProject ..................................................................................................................................................66

TSRecord ..................................................................................................................................................68

TSRecordRef ............................................................................................................................................72

TSRecordList ...........................................................................................................................................74

TSSchema .................................................................................................................................................76

TSServer ...................................................................................................................................................77

TSSocket ...................................................................................................................................................95

TSString ...................................................................................................................................................97

TSStringList .............................................................................................................................................99

TSTransAttr ...........................................................................................................................................100

TSTransition ..........................................................................................................................................102

TSTreeList .............................................................................................................................................104

TSUser ....................................................................................................................................................105

TSUserDefinedSchema ..........................................................................................................................112

Global Methods ......................................................................................................................................113

Appendix A, Revised Date Format .............................................................................................................114

Pre-Version 7.1 date field behavior ......................................................................................................114

Version 7.1 date field behavior .............................................................................................................114

SQL Statements and Date Fields ..........................................................................................................115

6

Revision History

(Click on a highlighted link to jump to the revision details.)

Date

Author

Initials DB VER Description

05/14/02 PN 56004 Added a check for user privilege error messages in

TSServer::ReadAvailableTransitionList.

05/14/02 PN 56004 Added error checking in TSField::SetCharValue for fields whose

char values are a comma-separated integer string value.

05/17/02 PN 56004 Added a global error status method

TSAppendLastErrorMessage that takes a TSString.

05/21/02 PN 56004 Any method in TSServer receiving a TSRecord or TSRecordlist

would clear the previous error message, if any, from the SBM

server. Changes were made in all the appropriate TSServer

methods to first save off the initial error message and include it in

the final error message.

06/03/02 PN 56004 Changed an error message outputted from

TSSocket::ReceiveString.

05/14/02 PN 56004 Added TSIntList::Find method.

07/02/02 LF 56004 Added TS_FLDTYPE KEYWORDLIST to the types of fields not

supported through a TSServer::AddField call.

07/02/02 SL 57000 Added int nAccessType = TS_ATTACHACCESS_DEFAULT

default parameter to TSItem::AddAttachment, AddItemLink, and

UpdateAttachment.

07/03/02 SL 57000 Added 2 methods to TSAttachment:

TSAttachment::GetSequence() and

TSAttachment::GetAccessType().

12/03/02 RS 57006 Added methods to TSDisplayField: GetMaxLength(),

GetDbName(), GetRelationId(), GetSubFieldId(),

GetInternalValue(), and SetInternalValue().

12/05/02 RS 57006 Added methods to TSTransition: GetNewStateName(),

GetOldStateName(), Error! Reference source not found.(),

GetWorkflowName()

12/13/02 RS 57008 Added bPopulateItem optional parameter to the Finish* functions.

01/14/03 SL 58001 Added optional parameter, tableId, to

TSServer::GetPrivilegeName that allows retrieval of label

overrides associated with the privilege.

01/27/03 SL 58001 Some methods were erroneously returning 0 for an error condition

(e.g. TSServer::ReadRecordListwithWhere). These now return

TS_OK for success or one of the error codes defined in TSDef.h,

as intended.

3/7/03 LF 60005 Added the TSServer::Disconnect method.

08/12/03 RS 61017 Documented methods changed by TSIgnorePreferences.

7

Date

Author

Initials DB VER Description

08/13/03 SL 61017 Documented TSTransAttr class and new list accessor,

TSTransition::GetTransAttrList.

10/17/03 LM 61022 Added the TSServer::AddTablesFromXML method..

10/17/03 PJD 62005 Added the TSServer::PutFiles method. Added TSString::Replace

methods

9/30/04 RES 63001 Added TS_SECTMASK_HIDDEN for TSItem

m_nSectionMask.

7/22/05 DI 65001 Added classes and methods to provide a way to read a custom

SQL statement from the SBM server. Classes include

TSDynaRecordList, TSDynaRecord, TSDynaColumnList,

TSDynaColumn, TSDynaValueList, TSStringList. Methods

include TSServer::ReadDynaListWithWhere.

Added the TSServer::ReadIntListWithWhere method.

1/12/06 SD 66001 Added electronic signature member accessors to TSTransition.

1/12/06 LF 66001 Added support for NT Challenge/Response.

3/8/07 JWS 71009 Add support for 7.1 date format

6/15/07 DB 66112 Added TSServer::TSGetFullSelectionListForROFields method.

7/26/07

11/28/07

JWS 71011 Add appendix for dates

11/28/07 PJD

71018 Modified TSServer::SetAlternateUser() and

TSServer::ClearAlternateUser()

12/03/07 PG 71018 Updated with product name change.

12/10/07 DI 71018 Modified TSServer::TSServer constructor to have a connection

options parameter. See the class for details.

1/27/09 KG 901000702 Noted that Private Folders are always created for Users added

through a call to TSUserAdd.

3/24/10 KG 903000609 Added the TSServer::ReadBlob method.

5/30/12 IK 10120101

02 Modified TSRecord::SetInt, TSRecord::SetDouble, and

TSRecord::SetString to accept datetime values

8

Introduction

Overview

The SBM Application Programming Interface, hereafter API, is a collection of C++ source files that can be

used to build a Windows DLL or a Linux library file. This library allows a client program to connect to the

SBM server via a socket to query or update data in the database with the same priority as all other user

requests. The client program can run on the same computer as the SBM server or on any computer that has

network access to the server.

The API can be used as an alternative means of manipulating data found in the SBM database. It can be

used to import or export data between SBM and other application API programs: to add issues, incidents,

users, groups, companies, contacts, projects, folders, and fields; or simply to move folders and projects

around in the hierarchy. It can also be used to verify and establish privileges, mass transition primary table

items, to verify data or develop custom reporting. This document outlines all available classes, member

functions and variables.

The API is a C++ class library. C++ programming knowledge is required to create an application using this

library. Note: Micro Focus does not support the API through the standard Technical Support contract.

Should assistance be required in creating or understanding API classes, please contact your sales

representative.

Getting Started

Using the SBM API consists of the following steps.

With the API source code and a C++ compiler, build a library: TSApiWin32.dll, TSApi.lib,

TSApiWininet.dll or TSApiWinInet_LIB.lib.

Build the Sample API programs to test the API and verify its operation.

Using the API’s C++ header files and classes described in the remainder of this document, build a C++

program that connects to the SBM Application Engine to query or update the database according to your

needs.

The API and sample programs should compile on Windows 95, 98, NT, 2000 and Linux. For Windows

platforms, we supply workspace and project files for MS Developers Studio. For Linux, we supply a basic

make file.

Building the API and Sample Programs

Windows: The easiest way to build the API and the sample programs is to load the solution file samples.sln

and rebuild all. Select Build→Batch Build from the main menu, then Select All and Rebuild. This will

build the debug and release versions of the sample programs and the API DLLs. These binaries will all be

put in the directories …\Build\Debug and …\Build\Release.

Now you can run each of the samples and get a feeling for how they operate. It is a good idea to run against

a sample database rather than your production system until you are accustomed to how the API operates.

You can choose which server the sample programs connect to when you run them.

Note Concerning Developer Studio 97: In order to build the sample programs under Dev Studio 97, the

preprocessor definition _DEV_STUDIO_5 will need to be added to each sample program's project settings.

In addition, you should expect compiler warnings in Debug mode using Dev Studio 97.

Note Concerning User Privileges: The ability to connect to the server via the API is controlled on a per-

user basis. By default, users do not have the privilege “Connect Using the API”. You will need to use SBM

System Administrator to grant this privilege to the appropriate users.

9

Preprocessor Symbols and Platform Dependencies

If using Microsoft Dev Studio 97, Visual C++ 5.0, add the preprocessor definition, _DEV_STUDIO_5, to

your project.

The API assumes no dependencies on the MFC CSocket class. In order to use MFC, define the

preprocessor directive in the project settings called TS_USE_MFC. This definition directs the API to use

the MFC CSocket class. If there is no definition, a generic CSocket class will be used.

If developing on Windows but not using MFC, it is not necessary to define any preprocessor directives. In

this case, TS_USE_WINSOCK is defined and Windows Sockets is used. Refer to TSSocket.h for the

source code.

In order to make the API work with a Secured Server, https, link the API with TSApiWinInet or

TSApiWininet_LIB. As of TeamTrack 5.5, TSApiWinInet is available in both DLL and static library

formats. Once the API is built using TSApiWinInet, it should work for both secured and non-secured

servers.

NT Challenge/Response authentication is supported. To use NT Challenge/Response you must using the

TSApiWinInet libraries and is supported only on Windows. In order to connect to SBM using NT

Challenge/Response you must use the ConnectNTCR function rather than the Connect function.

Object Hierarchy

TSObject

|_____ TSField

|_____ TSIntObject

|_____ TSRecord

|_____ TSSchema

|_____ TSString

|_____ TSUserDefinedSchema

TSList

|_____ TSFieldList

|_____ TSIntList

|_____ TSRecordList

|_____ TSTreeList

TSPosition

10

TSRecordRef

|_____ TSProject

|_____ TSTransition

|_____ TSItem

|_____ TSAuxiliaryItem

|_____ TSPrimaryItem

|_____ TSAttachment

|_____ TSChangeHistory

|_____ TSDisplayField

|_____ TSItemLink

TSServer

CSocket ( MFC )

|_____ TSSocket

Class Synopsis

There are three groups of classes available:

Generic Classes,

Database Representation Classes, and

Browser-mimicking Classes.

The first group of classes is used by both of the other groups to send and receive data across the TCP/IP

connection. TSServer is the main interface used to communicate with a web server hosting an SBM

database. It is the primary entry class to SBM. Methods called in TSServer build a string with the name of

the method and any parameters needed for that method. This string is then sent across the socket to the web

server. The API application then issues a “receive” and waits for data to come back. The Web server parses

the string and calls the appropriate method in the SBM source code. Once the request has been processed,

data is sent back across the socket. The data is received and processed on the API side. When using the

database manipulation classes, the user will need to specifically call TSServer methods to perform

operations on the objects that are created. In most instances, when using the browser-mimicking classes,

users will not need to call a TSServer method directly, other than to establish the initial connection, as the

methods within these classes call the appropriate TSServer method themselves.

The second group contains classes that can represent any table in the database. These classes are used for

more direct database manipulation where strict user privilege checking is not needed. Many of the methods

available through these classes directly manipulate the database. Therefore, complete knowledge of the

database schema is required to insure database integrity. For example, an additional row can be added to an

existing SBM database by creating a TSRecord object representing the row, then calling the AddRecord

method found in TSServer. Prior to calling this method, however, the user must understand the full

implications of adding that row. Many tables in the SBM database have values dependent on data in other

tables. See the SBM Schema documentation for a complete listing of dependencies. It is quite possible to

break SBM functionality through direct manipulation of the database.

The third group of classes mimics the functionality found in the browser, with complete user-privilege

checking and more robust error handling prior to changing the data in the database. Users can safely

develop programs using the methods found in these classes to create a command line interface to SBM. In

most instances, users will not need to call a TSServer method directly, when using these classes.

11

Generic Classes

TSServer

CSocket

TSSocket

Database Representation Classes

TSField

TSFieldList

TSIntList

TSIntObject

TSList

TSObject

TSPosition

TSRecord

TSRecordList

TSSchema

TSString

TSTreeList

TSUserDefinedSchema

Browser-Mimicking Classes

TSAttachment

TSAuxiliaryItem

TSChangeHistory

TSDisplayField

TSItem

TSItemLink

TSPrimaryItem

TSProject

TSRecordRef

TSString

TSTransition

The following listing breaks the classes into ones the user will typically use on a regular basis versus those

the user will most likely never use.

Classes the API Programmer will most likely use on a regular basis

Classes for Sending and Receiving Data TSServer Representation of the SBM server in the API program

Generic Database Representation Classes TSRecord Generic representation of a single record from any table in the SBM database

TSRecordList List of TSRecord objects

TSTreeList List of TSRecord objects in hierarchical order

12

TSField Generic field object representing a single field of a record containing either a

text string, an integer, a double, a TSRecordList, or a TSIntList depending on

the data type of the field

13

TSFieldList

List of TSDynaColumn

This class is derived from TSObject. Refer to its section for documentation of

inherited methods. It allows a user to specify the table Id and column name

that they wish to read from the database in a dynamic query. The type is

populated by SBM and can be referred to when a user wishes to know the

type of data stored in the corresponding TSDynaValue.

Public Methods

TSDynaColumn()

- Constructor method.

TSDynaColumn( LPCTSTR sName, int nTableId, int nType =

TS_DATATYPE_UNKNOWN )

- Constructor method allowing the user to specify the name and table Id

for the column they wish to read from the database.

~TSDynaColumn()

- Destructor method.

const TSString& GetName() const

- Accessor method for the specified column name.

int GetTableId() const

- Accessor method for the specified table id.

int GetType() const

- Accessor method to retrieve what type of data SBM returned for this

column.

TSDynaColumn& operator=( const TSDynaColumn& sourceRecord )

- Sets this TSDynaColumn equal to the one passed in.

TSDynaColumnList

This class is derived from TSList. Refer to its section for documentation of

inherited methods. It represents a list of TSColumns one wishes to read from

SBM to define a list of TSDynaRecords. (No class specific functions).

TSDynaRecord


inherited methods. It holds a TSDynaValueList of values read from the SBM

server using a TSColumnList to specify the data to retrieve. As this is a read-

only approach to gathering data from the server, it is not useful to create a

TSDynaRecord oneself but rather to use a method to read these from the

server.

Public Methods

TSDynaRecord()


TSDynaRecord( const TSDynaRecord& other )

- Copy Constructor method.

virtual ~TSDynaRecord()


const TSDynaValueList& GetValues() const

- Accessor method to get the TSDynaValueList that makes up the data for

this TSDynaRecord. A read method in TSServer is invoked providing the

14

TSPosition

Pointer to a position in a list, for iterating through a

list of TSRecord, TSDynaColumn


inherited methods. It allows a user to specify the table Id and column name

that they wish to read from the database in a dynamic query. The type is

populated by SBM and can be referred to when a user wishes to know the

type of data stored in the corresponding TSDynaValue.

Public Methods

TSDynaColumn()


TSDynaColumn( LPCTSTR sName, int nTableId, int nType =

TS_DATATYPE_UNKNOWN )

- Constructor method allowing the user to specify the name and table Id

for the column they wish to read from the database.

~TSDynaColumn()






int GetType() const

- Accessor method to retrieve what type of data SBM returned for this

column.



TSDynaColumnList

This class is derived from TSList. Refer to its section for documentation of

inherited methods. It represents a list of TSColumns one wishes to read from

SBM to define a list of TSDynaRecords. (No class specific functions).

TSDynaRecord


inherited methods. It holds a TSDynaValueList of values read from the SBM

server using a TSColumnList to specify the data to retrieve. As this is a read-

only approach to gathering data from the server, it is not useful to create a

TSDynaRecord oneself but rather to use a method to read these from the

server.

Public Methods

TSDynaRecord()







- Accessor method to get the TSDynaValueList that makes up the data for

15

TSString Class to manage a text string which can perform comparisons,

concatenations, etc.

Classes Mimicking the Browser Functionality TSRecordRef Base class instantiated directly or through derived classes in order to retrieve

the name of an item

TSProject Class describing an SBM Project, providing sFullProjectName which

contains a tab-delimited ( ^i ) string representing the full project hierarchy

TSTransition Class describing a transition

TSItem Class defining the base interface for both primary and auxiliary items

TSAuxiliaryItem Class defining the interface for an item that has variable fields and is not a

primary item

TSPrimaryItem Class defining a primary item, i.e. one following a workflow

TSDisplayField Class describing fields as they are displayed in the browser

TSAttachment Class describing attachments of type file, URL, or note

TSItemLink Class describing item links

TSChangeHistory Class describing the change history for a primary item

TSString Class to manage a text string which can perform comparisons, concatenations

etc.

Additional classes the typical API Programmer should never need to use

TSSocket Object to send and receive data on a TCP/IP socket.

CSocket Base class for the TSSocket class.

TSObject Abstract base class for objects to be put on a TSList.

TSList Base class for all list classes.

TSIntObject Class to manage comma-separated integer strings.

TSIntList List of TSIntObjects.

TSSchema Schema for a record.

TSUserDefinedSchema User-defined fields schema for a record.

Table Dependencies and Schema Information

To enforce the referential integrity between tables in the database, it is helpful to understand the database

schema and table relationships.

TS_LASTIDS

This table holds the last id value that was used for every table in the database. Anytime a record is added to

a table, the TS_LASTID column corresponding to that table must be incremented. The id values for every

table delivered with SBM are defined as constants in TSDef.h.

Reading Data From Tables

The majority of tables can be read using a generic read function, such as ReadAllRecords. This function

has the added overhead of carrying any supporting lists of data that relate to the record being read. For

16

example, if reading the list of TS_USERS, the supporting membership and privilege information is also

read and added to the returning TSRecordList.

Primary Tables Are Special

Primary tables, e.g. TTT_ISSUES or TTS_INCIDENTS, have only one commonly defined field, the id.

Reading data from these tables requires thought. Fields are defined for a workflow and the workflow is

associated with a project. In addition, each project can override the field definition of the workflow.

Reading or writing primary table items requires determining to which project that item belongs; then

determining which fields are valid for that project, by which workflow is associated to it. Then determining

how fields have been affected by overrides.

Hierarchical Items

The TSTreeList class is provided to facilitate reading data from tables that are recursive: TS_PROJECTS,

TS_WORKFLOWS, and TS_FOLDERS. This class inherits from TSRecordList. It should be used instead

of TSRecordList when reading from these tables. To know which field is the sublist of a tree item, use the

schema type called TS_SCHEMATYPE_TREELIST. This list type is like a TS_SCHEMATYPE_LIST in

every way except the field that has this schema type is the field that contains the sublist.

Table Schemas

There are many tables that contain non-database data members in addition to their physical database

columns. These non-database data members are provided along with the physical database columns to

prevent the user from having to perform a separate read for the information. They are helpful for coding

purposes, because they contain information related to the records in the table. The data members can be of

type TS_SCHEMATYPE_NONDB, TS_SCHEMATYPE_LIST, or TS_SCHEMATYPE_TREELIST. For

example, the schema for the TS_GROUPS table contains database columns TS_ID, TS_NAME,

TS_STATUS, TS_ACCESSTYPE, TS_TYPE, and TS_MEMO. The schema also contains non-database

data members that appear in the field list of a TSRecord as MEMBERLIST, PRIVILEGES,

ADMINGROUPLIST, and ADMINTABLELIST. The MEMBERLIST field is a list of the members

belonging to the group; the PRIVILEGES field is a list of the privileges attributed to the group. The

ADMINGROUPLIST and ADMINTABLELIST fields are lists of the groups and the tables a Managed

Administrator controls, respectively.

Field Schema Notes

The TS_ATTRIBUTES column in the TS_FIELDS table displays the default weight. The default weight

for a system field is 0. The default weight for the following field types is set to 100. If the user has

specifically set a default weight, then the TS_ATTRIBUTES column contains that weight.

Folder Fields: TS_FLDTYPE_FOLDER

Multiple Group Fields: TS_FLDTYPE_MULTIPLE_GROUP

Multiple Selection Fields: TS_FLDTYPE_MULTIPLE_SELECTION

Multiple User Fields: TS_FLDTYPE_MULTIPLE_USER

Selection Fields: TS_FLDTYPE_SELECTION

Single Relational Fields: TS_FLDTYPE_RELATIONAL

User Fields: TS_FLDTYPE_USER

Helpful Schema Information

TABLENAME

(FIELDNAME, list type, TS_SCHEMATYPE)

17

TS_FOLDERS table

SUBFOLDERS, TSRecordList, TS_SCHEMATYPE_TREELIST

TS_GROUPS table

MEMBERLIST, TSRecordList, TS_SCHEMATYPE_LIST

PRIVILEGES, TSRecordList, TS_SCHEMATYPE_LIST

ADMINGROUPLIST, TSRecordList, TS_SCHEMATYPE_LIST

ADMINTABLELIST, TSRecordList, TS_SCHEMATYPE_LIST

TS_NOTIFICATIONS table

SUBSCRIBERLIST, TSRecordList, TS_SCHEMATYPE_LIST

PERMISSIONLIST, TSRecordList, TS_SCHEMATYPE_LIST

TS_PROJECTS table

SUBPROJECTS, TSTreeList, TS_SCHEMATYPE_ TREELIST

TS_SELECTIONS table

PROJSELECTIONS, TSRecordList, TS_SCHEMATYPE_LIST

TS_STATES table

TRANSTRIGGERSTATES, TSRecordList, TS_SCHEMATYPE_LIST

TS_TRANSITIONS table

PROPERTYLIST, TSRecordList, TS_SCHEMATYPE_LIST

TRANSISSUETYPELIST, TSRecordList, TS_SCHEMATYPE_LIST

PROJECTTRANSITIONLIST, TSRecordList, TS_SCHEMATYPE_LIST

TRANSTRIGGERTRANSITIONLIST, TSRecordList, TS_SCHEMATYPE_LIST

TRANSGROUPLIST, TSRecordList, TS_SCHEMATYPE_LIST

TS_USERS table

MEMBERLIST, TSRecordList, TS_SCHEMATYPE_LIST

PRIVILEGES, TSRecordList, TS_SCHEMATYPE_LIST

ADMINGROUPLIST, TSRecordList, TS_SCHEMATYPE_LIST

ADMINTABLELIST, TSRecordList, TS_SCHEMATYPE_LIST

TS_WORKFLOWS table

SUBWORKFLOWS, TSTreeList, TS_SCHEMATYPE_TREELIST

Journal Fields

A journal field is a text field with special formatting and encoded datetime values. It is important to note

special behavior and client responsibilities when updating a journal field. Journal fields are designed to

contain a running dialog of text, all stored in a single field value. If done through the browser, each section

of appended text is automatically preceded by the date and time the update occurred and the user name of

the person making the addition. If this field type is updated through the API, it is the client application’s

responsibility to maintain this behavior. This can be accomplished as follows:

1. The user must first determine if the field is a journal field. This is done differently depending on

whether the program is using the Generic Database Representation Class, TSField, or the

Browser-Mimicking Class, TSDisplayField. TSField does not directly supply that information.

18

The user will have to query the field list in a separate step, or make fixed assumptions based on

inherent knowledge of the schema. When using a TSDisplayField, the member variable

m_nAttribute will be equal to either TS_FLDATTRIB_JOURNAL or

TS_FLDATTRIB_JOURNAL_RO.

2. Retain any existing contents by calling TSDisplayField::GetDisplayValue() or referencing the

TSField member variable charValue.

3. Append the datetime and user name associated with the additional text, then the text itself. The

format is critical if the internal encoding and decoding of datetimes is to continue working. The

format is: two carriage return-linefeed pairs, the date and time in the exact format and time zone

specified by the current client’s user preferences, space, dash, space, client’s user name, colon, one

carriage return-linefeed pair, followed by the body of your text addition. For example:

“\r\n\r\n12/03/2001 8:51:23 AM – Joe Manager:\r\nThis is an added comment.”

Quick Overview of TSServer Methods

The SBM API can be used for a variety of tasks. The following list of tasks corresponds directly to the

individual methods defined in the TSServer class. Any of the methods can be used in combination to

accomplish larger tasks. For a complete listing of TSServer methods see the TSServer class description.

For Use With Database Representation Classes

All of the methods listed in this table are invoked from a TSServer object.

Method Description

AddField

Use to add a custom field to the following tables: TS_COMPANIES,

TS_CONTACTS, TTS_INCIDENTS, TTT_ISSUES,

TS_PROBLEMS, and TS_RESOLUTIONS.

AddRecord

Adds a new record to any table, e.g. TS_USERS, TS_GROUPS,

TS_PROJECTS, TS_FOLDERS, TS_PRIVILEGES, etc. Not

recommended for primary tables, e.g. TTT_ISSUES, or auxiliary

tables, e.g. TS_COMPANIES. Use Submit.

AddTable Adds a new table, primary or auxiliary, to the database.

BuildFieldList Obtains a list of fields defined for any given table.

GetSchema Obtains the table schema for any table.

GetSubmitTransition Obtains the id value for the default submit transition.

GetSubmitTransitions Returns a list of all valid submit transtions for a project.

ReadAllRecords Obtains all the records from any table.

ReadAttachmentList Obtains a list of the attachments to a given item.

ReadAvailableTransitionList Obtains a list of available transitions for a given record.

ReadChangeList Deprecated. Use ReadChangeList2.

ReadChangeList2 Obtains a list of changes made to any primary or auxiliary table item,

ordered either from oldest to newest (default) or newest to oldest.

ReadFieldsByProject Obtains a list of default fields for a specified project.

ReadFieldsByWorkflow Obtains a list of default fields for a specified workflow.

ReadFolderItems Obtains a list of the items currently in a given folder.

19


ReadFolderList Obtains a list of folders defined for a given user.

ReadProjectSelectionList Obtains a list of selections for a given project.

ReadProjectTransitionList Obtains a list of transitions available for a given project.

ReadPropertyList Obtains a list of each field’s properties during a given transition.

ReadRecord Obtains one record from any table.

ReadRecordByItemNumber Obtains a record based on a given item number and project id.

ReadRecordForId Obtains a record based on a given id value.

ReadRecordListWithWhere Obtains a list of records from a given table based on a “where”

condition.

ReadRecordListWithWhere Obtains a specified list of user-defined fields for a list of records from

a given table based on a “where” condition.

ReadRecordListWithWhere Obtains a list of a specified maximum number of records from a given

table based on a “where” condition and beginning with a specified id.

ReadRecordListWithWhere

Obtains a specified list of user-defined fields for a list of a specified

maximum number of records from a given table based on a “where”

condition and beginning with a specified id.

ReadRecordWithWhere Obtains one record from a given table based on a “where” condition.

ReadRecordWithWhere Obtains a specified list of user-defined fields for one record from a

given table based on a “where” condition.

ReadReport Obtains a report based on the name.

ReadReportList Obtains a list of reports available to a given user based on the user’s

privileges.

ReadSelectionList Obtains a list of selection values defined for a given field that are

available to a given project.

ReadStateList Obtains a list of states that are available to a given project.

ReadTransitionList Obtains a list of transitions and the fields the transitions use.

ReadUserDefinedFields Obtains a list of the user-defined fields for a given table.

ReadUserSelectionList Obtains a list of selections defined for a given USER/MULTI-USER

field.

ReadVCActions Obtains a list of Version Control activity for a given issue.

ReadVCActionsForModule Obtains a list of Version Control activity for a given user for a

specified file and specific action.

Submit

Submit a new item into a primary or auxiliary table in the database and

into the workflow, returning only the nIssueId; i.e., item id shown in

the browser.

Submit

Submit a new item into a primary or auxiliary table in the database and

into the workflow, returning both the nIssueId, item id shown in the

browser, and the nId, ts_id in the database.

20


Transition Transitions an existing primary or auxiliary item.

UpdateList

Updates a list of records for a given table. Could be used to mass

transition primary items, or for importing a list of users instead of

individually creating them.

UpdateRecord Updates a single record in a table.

For Use With Browser-Mimicking Classes

All of the methods listed in this table, except GetProjectList, TSGetFullSelectionListForROFields, and TSIgnorePreferences, are called from member methods of their respective classes in an object-oriented design.

Method Description

GetProjectList Obtains a list of projects to which the user has privileges.

TSAuxiliaryItemCancelUpdate Called from TSAuxiliaryItem::CancelUpdate. Cancels the update on

the auxiliary item and clears the lock. Use after a call to StartUpdate.

TSAuxiliaryItemFinishUpdate

Called from TSAuxiliaryItem::FinishUpdate. Completes the update

of an auxiliary item and clears the lock. Use after a call to

StartUpdate.

TSAuxiliaryItemRead Called from TSAuxiliaryItem::Read. Obtains a specified auxiliary

item.

TSAuxiliaryItemStartUpdate

Called from TSAuxiliaryItem::StartUpdate. Obtains an auxiliary item

with fields populated and ordered as shown in the browser at the

beginning of an update transition.

TSGetFullSelectionListForROFields

Set or clear the client-side state variable that determines whether or

not to read the full list of selections for all selection-type fields, even

if the field is read-only. By default, this is true, to preserve the

behavior of older API revisions. If it is set to false, read-only fields

will only list the selection values that are actually selected. Setting

this to false can improve performance if unselected values in read-

only selection fields are not used by the client program. This applies

to selection fields and all similar fields, such as user fields, relational

fields, multi-selection fields, etc. The setting can be changed at any

time and will remain in effect for any subsequent calls to

TSAuxiliaryItemStartUpdate, TSPrimaryItemStartTransition,

TSItemStartSubmit, and TSPrimaryItemStartSubmit on this TSServer

object.

TSIgnorePreferences Set or clear the client-side state variable that determines whether or

not user preferences should or should not be ignored.

TSItemAddAttachment Called from TSItem::AddAttachment. Adds a note, URL or file to a

primary or auxiliary item.

TSItemAddItemLink Called from TSItem::AddItemLink. Adds an item link to a primary or

auxiliary item.

TSItemDeleteAttachment Called from TSItem::DeleteAttachment. Deletes an existing note,

URL or file attached to a primary or auxiliary item.

21

For Use With Browser-Mimicking Classes

TSItemFinishSubmit Called from TSItem::FinishSubmit. Adds a primary or auxiliary item

to the database after field values have been set.

TSItemStartSubmit

Called from TSItem::StartSubmit. Obtains a primary or auxiliary item


beginning of a submit transition.

TSItemUpdateAttachment Called from TSItem::UpdateAttachment. Updates an existing note,

URL or file attached to a primary or auxiliary item.

TSPrimaryItemCancelTransition

Called from TSPrimaryItem::CancelTransition. Cancels the specified

transition on the primary item and clears the lock. Use after a call to

StartTransition.

TSPrimaryItemFinishTransition

Called from TSPrimaryItem::FinishTransition. Completes the

specified transition on a primary item and clears the lock. Use after a

call to StartTransition.

TSPrimaryItemGetSubmitTransitio

ns

Called from TS PrimaryItem::GetSubmitTransitions. Obtains a list of

valid submit transitions for the primary item.

TSPrimaryItemGetTransitionList Called from TSPrimaryItem::GetTransitionList. Obtains a list of valid

transitions for the primary item.

TSPrimaryItemRead Called from TSPrimaryItem::Read. Obtains a specified primary item.

TSPrimaryItemStartTransition

Called from TSPrimaryItem::StartTransition. Obtains a primary item


beginning of a specified transition.

TSProjectRead Called from TSProject::Read. Obtains a specified project record.

TSRecordRefRead Called from TSRecordRef::Read. Obtains a specified record.

Generic Methods

All the methods in this table are invoked from a TSServer object.

Method Description

AddGroupsFromXML Adds one or more SBM groups from an XML definition.

AddTablesFromXML Adds one or more SBM tables from an XML definition.

AddWorkflowFromXML Adds an SBM workflow (and projects) from an XML definition.

ClearAlternateUser Clears the alternate user, reverting to the logged in API user.

Connect Connects the user to a web server running SBM.

CreateIndex Creates an index on a table in the SBM database.

DeleteIndex Deletes an index created with CreateIndex.

DeleteRecord Deletes any record from any table.

Disconnect Disconnect from the SBM Web server.

ExecuteSQL Executes a SQL statement that has no returning result set.

22

Generic Methods

GetConnectionInfo Obtains information about the database connection.

GetConnectionInfo Obtains information about the database connection using a char*.

GetConnectionInfo Obtains information about the database connection using a char**.

GetDbInfo Obtains information about the database, e.g. version number.

GetDllWebAddress Obtains the server name/directory name/dll name for the server.

GetIdentity Obtains a single numeric result from a SQL query.

GetIdentityString Obtains a single string result from a SQL query.

GetInt Obtains the numeric value of a column in any table.

GetLastErrorMessage Use TSGetLastErrorMessage for more complete error information.

GetPrivilegeName Obtains the display name of a privilege.

GetPrivilegeName Obtains the display name of a privilege using a char**.

GetString Obtains the string value of any column in any table.

GetString Obtains the string value of any column in any table using a char**.

GetTableIdByDatabaseNameEx Obtains the id value of a primary or auxiliary table by its database

name.

HasAccess Determines if access is available to a specific product or integration

(and available for a given user when applicable).

HasGroupPrivilege Verifies a group’s privilege.

HasPrivilege Deprecated. Use HasUserPrivilege. or HasGroupPrivilege.

HasRecordPrivilege Verifies a user has the specified privilege for the specified record.

HasUserPrivilege Verifies a user’s privilege.

HasValidLicense Verifies the database has a license for a solution.

MoveFolder Moves a folder to a new place in the hierarchy.

MoveProject Moves a project to a new place in the hierarchy.

PutFile Creates new TS_RESOURCE and TS_BLOB for a file.

ReadBlob Reads the data stored in a record in the TS_BLOBS table.

RefreshCache Refreshes the server cache for the specified table.

ReleaseRecordLockById Releases a record lock based on a table id and record id.

ReleaseRecordLockByNumber Releases a record lock based on a project id and item number.

SetAlternateUser Allows the API user to act as another user.

SetExitUrl Sets the exit URL string stored in the TS_SYSTEMINFO table.

SetGroupPrivilege Grants or revokes a group privilege.

SetRecordLockById Locks a record based on a table id and record id.

23

Generic Methods

SetRecordLockByNumber Locks a record based on a project id and item number.

SetUserPrivilege Grants or revokes a user privilege.

TSAppendLastErrorMessage Appends the specified string to the existing value of the TSServer

static variable TSErrorMessage.

TSClearLastError Clears the TSServer static variable TSErrorCode.

TSGetLastError Obtains the value of the TSServer static variable TSErrorCode.

TSGetLastErrorMessage Obtains the value of the TSServer static variable TSErrorMessage.

TSSetLastError Sets the TSServer static variable, TSErrorCode, to the specified

value.

TSSetLastErrorMessage Sets the value of the TSServer static variable, TSErrorMessage, to

the specified string.

ValidateUser Validates the login id for a given user.

ValidateVersion Validates the version of API against the version of SBM installed on

the web server for compatibility.

Steps to Building a Simple API Application Program

This is an example of a simple API program for changing a record in the TS_MEMBERS table using the

Generic Database Representation Classes.

1. An SBM login id and password are required to establish a connection with the SBM database

across a socket. Grant the SBM user that will be used to connect to the SBM database the privilege

“Connect Using the API” via the SBM System Administrator.

2. Instantiate a TSServer object.

TSServer teamtrack;

3. If the program is not using UNIX, use the convenience function to initialize Winsock.

TSInitializeWinsock();

4. Create a connection to the SBM Web server using the TSServer object, checking the method’s

return value to determine success or failure of the operation. All of the methods of the TSServer

class return TS_OK when successful, or an error code. Refer to TSDef.h for a complete listing of

the error status codes.

if( teamtrack.Connect(“admin”,”password”,”teamtrack_host”) != TS_OK );

5. Use the global error-messaging methods of the TSServer class to print out failure reasons.

{

TSString error = TSGetLastErrorMessage();

printf( "Error connecting to the server:\n%s\n", error.GetBuffer() );

return 1;

}

6. Instantiate a TSRecord object from the TS_MEMBERS table.

TSRecord memberRecord( TS_TBLID_MEMBERS, &teamtrack );

24

7. Read the specific record to be changed by calling the ReadRecord method of the TSServer class.

See the TSServer documentation for a listing of the various read methods.

teamtrack.ReadRecord( &memberRecord, 5 );

8. Set the value for the appropriate fields using the SetString(), SetInt(), SetDouble(), or

SetIntPairList() methods of the TSRecord class. Refer to the SBM database schema document for

more clarification as to the data type of various fields.

memberRecord.SetInt( “groupid”, 2 );

9. Call the UpdateRecord() method of the TSServer class to perform the desired action., checking the

method’s return value to determine success or failure of the operation.

if ( teamtrack.UpdateRecord( &memberRecord ) != TS_OK )

10. Use the global error-messaging methods of the TSServer class to print out failure reasons.

{

TSString error = TSGetLastErrorMessage();

printf( "Error updating member record:\n%s\n", error.GetBuffer() );

return 1;

}

else

{

return 0;

}

25

Trouble Shooting

TS_SOCKET_READ_ERROR

ErrorCode = -6.

Authentication Failed. No user information. Resolution: SBM is not accepting authentication information from the HTTP header because you have

turned off this feature. Set up SBM to accept authentication information from the HTTP header.

In the SBM System Administrator, from the Options menu, choose Settings.

Select the Server tab.

Select the ‘Accept Info From Browser/header’ checkbox.

If the checkbox ‘Accept Info From Form/URL/Cookie’ is also selected, SBM tries to get the

authentication information from a cookie first, and the HTTP header second.

TS_SERVER_ERROR

ErrorCode = -13.

Access Denied. You do not have API connect privileges. Resolution: The SBM user does not have the ‘Connect using the API’ privilege. The SBM administrator

can grant this privilege to the user.

Authentication Failed. Invalid user id or password. Resolution: Make sure the user is a valid user and that the user is using the correct password.

TS_SOCKET_CONNECT_FAILED

ErrorCode = -8.

Socket Connect failed. Resolution: The user cannot connect to the SBM server. Verify that the server running.

26

Sample Programs

Sample programs are provided in the tsapi.zip file. All or individual sample applications can be built using

the Samples.sln solution file. The sample programs are:

ConsolidateFields

Syntax: ConsolidateFields

This Sample program has been deleted. It is no longer valid.

DeletedItemsReport

Syntax: DeletedItemsReport

Lists all primary items marked as deleted, when each item was deleted, and by which user. Demonstrates

the use of command prompts to obtain authentication for running the program.

GetTableId

Syntax: GetTableId

Prompts the user to enter the database name of a table and returns the numeric id of the table.

ListGroupMembers

Syntax: ListGroupMembers

Lists the names of all the members of a specified group. Demonstrates use of command prompts to obtain

the parameters for the program.

ListGroups

Syntax: ListGroups

Lists all group names defined in the TS_GROUPS table of the database. Demonstrates using command

prompts to obtain authentication for running the program.

ListPrivs

Syntax: ListPrivs

Lists the privileges for either a user or a group. Privileges are not broken down by project. Demonstrates

using command prompts to obtain the parameters for the program.

ReadListWithWhere

Syntax: ReadListWithWhere <server_name><login_id> <password> <table_id> <where clause>

(without the word ‘where’)

Reads all the records from a specified table based on the where clause passed. The user does not need to

type the word ‘WHERE’. The where clause must use prefixed field names, e.g. TS_STATUS versus

STATUS.

ReadRecord

Syntax: ReadRecord <server_name> <login_id> <password> <table_id> <record_id>

<optional_field_type>

27

Reads a particular record from a table for a specified id and displays the data on the screen.

ReadRecordMFC

Syntax: ReadRecordMFC /h | <server_name> <login_id> <password> <table_id> <record_id>

Reads a particular record from a table for a specified id and displays the data on the screen. Demonstrates

how to use the MFC CSocket class to connect to the web server. Note: this method will not return the

TS_SCHEMATYPE_NONDB values for a record read from the TS_FIELDS table because no field type

parameter is passed as in ReadRecord above.

ReadRecordWininet

Syntax: ReadRecordWininet /h | <server_name> <login_id> <password> <table_id> <record_id>


linking with TSApiWininet. Note: this method will not return the TS_SCHEMATYPE_NONDB values for

a record read from the TS_FIELDS table because no field type parameter is passed as in ReadRecord

above.

ReadRecordWininet_LIB

Syntax: ReadRecordWininet_LIB /h | <server_name> <login_id> <password> <table_id> <record_id>


linking with TSApiWininet_LIB. Note: this method will not return the TS_SCHEMATYPE_NONDB

values for a record read from the TS_FIELDS table because no field type parameter is passed as in

ReadRecord above.

ReadUser

Syntax: ReadUser <server_name> <login_id> <password> <user_name>

Reads a record from the TS_USERS table and displays the data to the screen. This program requires the

user to type all parameters after the program name.

ReadWithWhere

Syntax: ReadWithWhere

Reads a record from the specified table based on the where clause passed. The user does not need to type

the word ‘WHERE’. This sample demonstrates the use of command prompts to obtain the parameters for

the program. This method of reading a record will not populate the sub tree lists.

ShowAvailableTables

Syntax: ShowAvailableTables

A windows program that lists the names of the tables defined in the database. All table ids are defined in

TSDef.h using the naming convention: TS_TBLID_TABLENAME. For example, to reference the tableid

for the TS_CONTACTS table, use TS_TBLID_CONTACTS. This sample demonstrates the use of dialog

to obtain authentication for running the program and displaying information.

Submit

Syntax: Submit

Submits an item, e.g. issue or incident, into its primary table based on the project specified. This sample

demonstrates the use of command prompts to obtain the parameters for the program. It is important to note

28

that any fields can be skipped if the user does not wish to enter a value. If the field is required, the user will

be re-prompted for the value. Multiple selection fields are listed as TS_DATATYPE_STRING and need to

be entered with the appropriate corresponding selection ids strung together. For example: ‘,98,99,101,’. If a

value is supplied for a read-only field, it is ignored and a warning message to that effect is written to the

server event log. The API client can optionally check to see if a server message contains one of these

warnings even after a successful Submit.

Transition

Syntax: Transition

Transitions an item, e.g. issue or incident, within any of the database’s primary tables. This sample

demonstrates retrieving a list of primary tables and the use of command prompts to obtain the parameters

for the program. The transition name parameter is case-sensitive. If you choose to perform a Post Item,

Publish Problem, or Subtask transition, then you can override the table (and project, if primary) and data

that is submitted as the destination item. If a value is supplied for a read-only field, it is ignored and a

warning message to that effect is written to the server event log.

Update

Syntax: Update

Updates an item in the database. Demonstrates the use of command prompts to obtain authentication for

running the program, for indicating which table record to update, and the record’s new field values. Also,

demonstrates the use of the TS_AUTO_X values defined in TSDef.h to have SBM automatically set the

field’s value. This program employs the UpdateRecord method, a low-level method whose function is not

governed by user privileges and should therefore be used with discretion. To perform an update with

privilege checking, use the Transition sample program and specify ‘Update’ when prompted for the

transition name.

29

TSAPI Object Definitions

Methods and member variables inherited from parent classes are not necessarily documented again with the

derived classes. If a derived class overrides a virtual method and significantly alters behavior or adds

funcionality that warrants mentioning, then the method will be restated in that case only. Refer the the

documentation for parent classes to obtain a full picture of all methods that can be called on an object.

TIP: The parent class name is a quick link to that class. Point to the class name and click.

TSAttachment

This class is derived from TSRecordRef. Refer to its section for documentation of inherited methods. It

describes a file, URL, or note attachment to a TSPrimaryItem or TSAuxiliaryItem object.

Public Methods

TSAttachment( TSServer& server, int nItemId = 0 )

- Constructor method; initializes the TSAttachment object and automatically sets m_nTable id.

TSAttachment( const TSAttachment& that )

- Copy constructor method.

TSAttachment& operator = ( const TSAttachment& that )

- Assignment operator method.

virtual ~TSAttachment()


int GetAccessType() const

- Accessor method returning member variable m_nAccessType.

const TSString& GetAuthor() const

- Accessor method returning member variable m_sAuthor.

const TSString& GetDateTimeCreated() const

- Accessor method returning member variable m_sDateTimeCreated.

const char* GetFileData() const

- Accessor method returning member variable m_pFileData.

int GetFileLength() const

- Accessor method returning member variable m_nFileLength.

const TSString& GetFilename() const

- Accessor method returning member variable m_sFilename.

int GetSequence() const

- Accessor method returning member variable m_nSequence.

const TSString& GetText() const

- Accessor method returning member variable m_sText.

int GetType() const

- Accessor method returning member variable m_nType.

30

Protected Member Variables

int m_nAccessType

- Determines the restricted or unrestricted status of the attachment; defined as:

TS_ATTACHACCESS_DEFAULT = -1. The attachment is restricted or unrestricted as defined

by system settings set through the Administrator. Please refer to the Administrator Manual and on-

line help for a detailed explanation of the settings, their possible values, and the logic applied

based on these settings.

TS_ATTACHACCESS_RESTRICTED = 0. Apply all note and attachment privileges. Also

preserves the behavior of TeamTrack versions 5.51 and earlier.

TS_ATTACHACCESS_UNRESTRICTED = 1. Permits anyone with privilege to view the item, to

also view this unrestricted attachment. The API user must have the "Set Unrestricted Status of

Notes/Attachments" privilege in order to specify this argument to methods that add and update

attachments, notes, and item links.

int m_nFileLength

- Specifies the length of the file if the attachment is of type TS_ATTACHATTRIB_FILE, and the file

contents were requested when reading the primary or auxiliary item.

int m_nSequence

- Attachment sequence number. If used, this is the unique sequence number for each attachment,

whether a file, URL, item link or note, to a given item. The first attachment to any unique primary or

auxiliary item will be given the sequence number of 1. Each successive attachment to the same item

will be numbered sequentially. If an attachment to a given item is deleted, its sequence number is

permanently retired. The next attachment will be given the next sequence number as if no attachments

had been deleted.

- This feature is disabled by default. It is enabled through the Display tab of the Settings dialog in the

Administrator.

int m_nType

- Type of the attachment, defined as a bit flag argument with bit values:

File attachment: TS_ATTACHATTRIB_FILE = 0x0010.

Note attachment: TS_ATTACHATTRIB_NOTE = 0x0080.

URL attachment: TS_ATTACHATTRIB_URL = 0x0020.

char* m_pFileData

- Pointer to the contents of the file if the attachment is of type TS_ATTACHATTRIB_FILE, and the file

contents were requested when reading the primary or auxiliary item.

TSString m_sAuthor

- User name of the author of the attachment.

TSString m_sDateTimeCreated

- Date and time the attachment was created.

TSString m_sFilename

- File name if the attachment is of type TS_ATTACHATTRIB_FILE.

TSString m_sText

- Contents of the attachment defined as follows:

File attachment: the full path to the server's copy of the file.

31

Note attachment : the text content of the note, if requested when reading the primary or auxiliary

item.

URL attachment: the URL string of the URL.

32

TSAuxiliaryItem

This class is derived from TSItem. Refer to its section for documentation of inherited methods. It defines

the interface for an object that has variable fields, i.e. user defined fields, and is not a primary item.

Contacts and Companies are examples of items that will use this class.

Public Methods

TSAuxiliaryItem( TSServer& server, int nTableId = 0, int nItemId = 0 )

- Constructor method; initializes the auxiliary item.

TSAuxiliaryItem( const TSAuxiliaryItem& that )


TSAuxiliaryItem& operator = ( const TSAuxiliaryItem& that )


virtual ~TSAuxiliaryItem()


virtual int CancelUpdate()

- Used after a call to StartUpdate, but when FinishUpdate will not be called.

- Clears the lock on the record on the server.

- Requires a roundtrip to the server.

virtual int FinishUpdate( bool bStealLockFlag = false, bool bPopulateItem = false )

- Used after a call to StartUpdate.

- Updates the calling TSAuxiliaryItem in the database after the field values in m_fieldList have been set.

- Only sends fields that have been modified back to the server.

- Repopulates the item, to get default or automatic values, when bPopulateItem is true.

- After a successful database update, clears the lock on the record on the server.

- Will return TS_LOCK_UNAVAILABLE if the lock has expired and another user has taken the lock.


virtual int Read()

- Populates the TSAuxiliaryItem as specified by m_nSectionMask, taking into consideration the

privileges of the user, or alternate user if set, and orders the fields as they would be when viewed in the

browser.

- m_nTableId and m_nItemId must be preset.


- Overridden from TSRecordRef.

virtual int StartUpdate( bool bLockFlag = true )

- Populates the calling TSAuxiliaryItem’s m_fieldList and orders the fields as they would be for an

update when viewed in the browser, including filling out field selection lists.

- m_attachmentList, m_changeList and m_linkList member list will not be updated.

- The bLockFlag is defaulted to lock the record on the server. While the record is locked, any other user,

via API or browser interface, will receive an error if they attempt to update the same record. The SBM

administrator sets the time a lock is held.

- m_nTableId and m_nItemId must be preset.


33

TSChangeHistory


describes the change history for a TSPrimaryItem or a TSAuxiliaryItem object.

Public Methods

TSChangeHistory( TSServer& server, int nItemId = 0 )

- Constructor method; initializes the change history object and automatically sets m_nTableId.

TSChangeHistory( const TSChangeHistory& that )


TSChangeHistory& operator = ( const TSChangeHistory& that )


virtual ~TSChangeHistory()


int GetActionType() const

- Accessor method returning member variable m_nActionType.

const TSString& GetAuthor() const

- Accessor method returning member variable m_sAuthor.

const TSString& GetDateTime() const

- Accessor method returning member variable m_sDateTime.

int GetFieldAttribute() const

- Accessor method returning member variable m_nFieldAttribute.

int GetFieldId() const

- Accessor method returning member variable m_nFieldId.

const TSString& GetFieldName() const

- Accessor method returning member variable m_sFieldName.

int GetFieldType() const

- Accessor method returning member variable m_nFieldType.

const TSString& GetNewDisplayValue() const

- Accessor method returning member variable m_sNewDisplayValue.

int GetNewInt() const

- Accessor method returning member variable m_nNewInt.

int GetNewReal () const

- Accessor method returning member variable m_nNewReal.

const TSString& GetPriorDisplayValue() const

- Accessor method returning member variable m_sPriorDisplayValue.

int GetPriorInt() const

- Accessor method returning member variable m_nPriorInt.

34

int GetPriorReal () const

- Accessor method returning member variable m_nPriorReal.

int GetType() const

- Accessor method returning member variable m_nType.


int m_nActionType

- Indicated the action being performed when the change record was created. See TS_CHGACTION_ in

TSDef.h.

int m_nFieldAttribute

- Attribute of the modified field, depending on the field type. See TS_FLDATTRIB_ in TSDef.h.

int m_nFieldId

- Field id this change record refers to or 0 for attachment and vc action changes.

int m_nFieldType

- Type of the modified field. See TS_FLDTYPE_ in TSDef.h.

int m_nNewInt

- New integer value in the modified field. Only set when the m_nFieldType is not text, memo or

floating-point type.

int m_nPriorInt

- Previous integer value in the modified field. Only set when the m_nFieldType is not text, memo or

floating-point type.

int m_nType

- Raw storage type of the modified field. See TS_CHGTYPE_ in TSDef.h.

TSString m_sAuthor

- User name of the person who modified the field.

TSString m_sDateTime

- Date and time the change record was created.

TSString m_sFieldName

- Name of the modified field.

TSString m_sItemName

- Blank for a TSChangeHistory object.

- Declared by TSRecordRef.

TSString m_sNewDisplayValue

- New value for the modified field when the m_nFieldType is of type text, memo or floating-point.

TSString m_sPriorDisplayValue

- Previous value for the modified field when the m_nFieldType is of type text, memo or floating-point.

35

TSDisplayField


describes the fields for a TSPrimaryItem or a TSAuxiliaryItem as they would appear in a browser.

Public Methods

TSDisplayField( TSServer& server, int nItemId = 0 )

- Constructor method; initializes the display field object and automatically sets the table id.

TSDisplayField( const TSDisplayField& that )


TSDisplayField& operator = ( const TSDisplayField& that )


virtual ~TSDisplayField()


int AddToDisplayValueForMultiSelect( const TSString& sAdditionalDisplayValue )

- Appends the additional display value passed in to the existing display value for the field, if the field

can be updated, if the field returns true to IsMultiSelect, and the passed value is a valid selection in

m_selections.

- Also updates m_sInternalValue.

int AddToDisplayValueForMultiSelect( const TSRecordRef* pAdditionalSelection )

- Appends the additional passed in selection from m_selections to the to the existing display value for

the field, if the field can be updated and the field returns true to IsMultiSelect.

- Also updates m_sInternalValue.

int AddToInternalValueForMultiSelect( const TSString& sValue )

- Appends the additional internal value passed in to the existing internal value for the field, if the field

can be updated, if the field returns true to IsMultiSelect, and the passed value is a valid selection in

m_selections.

- Also updates m_sDisplayValue.

int ClearDisplayValue()

- Clears the display value of the field if the field can be updates.

- Also clears m_sInternalValue.

int GetAttribute() const

- Accessor method returning member variable m_nAttribute, indicating the attribute of the field.

int GetInternalValue( TSString& sValue ) const

- Sets sValue to the internal (database) value of the field.

- Return TS_OK when successful, TS_INVALID_DATATYPE when field type is incorrect.

int GetInternalValue( int& nValue ) const

- Sets nValue to the internal (database) value of the field converted to integer.

- Return TS_OK when successful, TS_INVALID_DATATYPE when field type is incorrect or

TS_OUTOFRANGE_ERROR when a time field value is too big to fit into an integer without data loss.

36

int GetInternalValue( double& dValue ) const

- Sets dValue to the internal (database) value of the field converted to double.

- Return TS_OK when successful, TS_ INVALID_DATATYPE when field type is incorrect.

int GetInternalValue( struct tm& stValue ) const

- For date-only and date-time fields, sets stValue to the internal (database) value of the field converted to

a time structure.

- Return TS_OK when successful, TS_ INVALID_DATATYPE when field type is incorrect.

int GetMaxLength() const

- Accessor method returning member variable m_nLength, indicating the maximum length for the field.

const TSString& GetDbName() const

- Accessor method returning member variable m_sDbName, indicating the database name of the field.

const TSString& GetDisplayValue() const

- Accessor method returning member variable m_sDisplayValue, the display value of the field.

const TSString& GetPrefix() const

- Accessor method returning member variable m_sPrefix, the prefix for the field.

int GetProperty() const

- Accessor method returning member variable m_nProperty, the properties of the field.

int GetRelationId() const

- Accessor method returning member variable m_nRelationId, the related field or table.

int GetRequired() const

- Accessor method returning member variable m_nRequired, 1 if the field is required to have a value, or

0 if not.

int GetSection() const

- Accessor method returning member variable m_nSection, the section the field is within.

const TSRecordRefList& GetSelections() const

- Accessor method returning member variable m_selections, a list of TSRecordRefs representing all

valid selections if the field returns true to IsSingleSelect or IsMultiSelect or the field is of type binary.

int GetSubFieldId() const

- Accessor method returning member variable m_nSubFieldId, the related field when type is

subrelational.

const TSString& GetSuffix() const

- Accessor method returning member variable m_sSuffix, the suffix for the field.

int GetSystemCode() const

- Accessor method returning member variable m_nSystemCode, the TS_SYSFLD_? value if this is a

system field, otherwise 0.

int GetType() const

- Accessor method returning member variable m_nType, the type of the field.

37

bool IsModified() const

- Determines whether or not the field has been modified.

bool IsMultiSelect() const

- Determines whether or not the field is a multiple selection, multiple relational, multiple group or

multiple user field.

bool IsSingleSelect() const

- Returns true if the field is a single selection or single relational field. Binary field type must be

determined via GetType.

bool IsUpdateable() const

- Determines whether or not the field can be updated.

int SetDisplayValue( const TSString& sNewDisplayValue )

- Sets the display value of the field if the field can be updated.

- Then sets bModifiedFlag to true.

- See the special notes pertaining to journal fields in the introduction, if applicable.

int SetDisplayValue( const TSRecordRef* sNewSelection )

- Sets the display value of the field if the field can be updated.

- Then sets the bModifiedFlag to true.

int SetInternalValue( const TSString& sValue ) const

- Sets the internal (database) value of the field to sValue.

- Return TS_OK when successful, TS_INVALID_DATATYPE when field type is incorrect,

TS_NOT_UPDATEABLE when the field is not updateable.

int SetInternalValue( int nValue ) const

- Sets the internal (database) value of the field to nValue converted to string.



int SetInternalValue( double fValue ) const

- Sets the internal (database) value of the field to fValue converted to string.



int SetInternalValue(struct tm& stValue ) const

- Sets the internal (database) value of the field to stValue converted to string.




bool m_bCanUpdate

- Set to true if the field value can be modified.

bool m_bModifiedFlag

- Set to true if the field value was modified.

38

bool m_bUseInternal

- Set to true if the field returns true to IsSingleSelect or IsMultiSelect or the field is of type binary.

int m_nAttribute

- Attributes of the field. See TS_FLDATTRIB_ in TSDef.h.

int m_nLength

- Maximum length for the field.

int m_nProperty

- Properties of the field. See TS_FLDPROP_ in TSDef.h.

int m_nRequired

- Whether or not the field is required. See TS_FLDREQ_ in TSDef.h.

int m_nSection

- Within which section the field is to shown on the browser. See TS_FLDSECT_ in TSDef.h.

int m_nSubFieldId

- The related field when type is subrelational.

int m_nSystemCode

- The system code if a system field, else 0.

int m_nType

- The type of the field. See TS_FLDTYPE_ in TSDef.h.

TSRecordRefList m_selections

- A list of TSRecordRefs representing all the valid selections for fields that have selections, i.e. fields

returning true to either IsSingleSelect or IsMultiSelect or of type binary.

TSString m_sDisplayValue

- Displayable form for this field’s value, i.e. the value of the field as seen in a browser.

TSString m_sInternalValue

- Non-displayable value for fields returning true to either IsSingleSelect, IsMultiSelect, or fields of type

binary.

TSString m_sPrefix

- Prefix for the field, if any, as set in the Administrator.

TSString m_sSuffix

- Suffix for the field, if any, as set in the Administrator.

39

TSDynaColumn

This class is derived from TSObject. Refer to its section for documentation of inherited methods. It allows

a user to specify the table Id and column name that they wish to read from the database in a dynamic query.

The type is populated by SBM and can be referred to when a user wishes to know the type of data stored in

the corresponding TSDynaValue.

Public Methods

TSDynaColumn()


TSDynaColumn( LPCTSTR sName, int nTableId, int nType = TS_DATATYPE_UNKNOWN )

- Constructor method allowing the user to specify the name and table Id for the column they wish to read

from the database.

~TSDynaColumn()






int GetType() const

- Accessor method to retrieve what type of data SBM returned for this column.



TSDynaColumnList

This class is derived from TSList. Refer to its section for documentation of inherited methods. It represents

a list of TSColumns one wishes to read from SBM to define a list of TSDynaRecords. (No class specific

functions).

40

TSDynaRecord

This class is derived from TSObject. Refer to its section for documentation of inherited methods. It holds a

TSDynaValueList of values read from the SBM server using a TSColumnList to specify the data to

retrieve. As this is a read-only approach to gathering data from the server, it is not useful to create a

TSDynaRecord oneself but rather to use a method to read these from the server.

Public Methods

TSDynaRecord()







- Accessor method to get the TSDynaValueList that makes up the data for this TSDynaRecord. A read

method in TSServer is invoked providing the columns one wishes to read. A list of TSDynaRecords is

created, each one having a list of values whose indexes match those of the columns requested.

41

TSDynaRecordList


a list of TSDynaRecords read from the SBM server. It holds a TSDynaColumnList of read columns. If

SBM does not recognize a requested column, it is not included in the results returned. Thus, after

requesting a read of a Dyna list, be sure to verify that all columns requested are in the result list.

Public Methods

TSDynaRecordList()


virtual ~TSDynaRecordList()


const TSDynaColumnList& GetColumns() const

- Accessor method to retrieve the TSDynaColumnList member. This can be used to determine the type

of data each TSDynaValue is storing for each TSDynaRecord in this list.

42

TSDynaValue

This class is derived from TSObject. Refer to its section for documentation of inherited methods. It

represents a value for a column of data in a TSDynaRecord. The field object will contain one of the

following: a text string, an integer, or a double, depending on the data type of the column.

Public Methods

TSDynaValue()


TSDynaValue( int n )


TSDynaValue( double n )


TSDynaValue( LPCTSTR s )


TSDynaValue( const TSDynaValue& other )


~TSDynaValue()


void GetValue( int& nOut ) const

- Accessor method to integer member data.

void GetValue( double& nOut ) const

- Accessor method to double member data.

void GetValue( TSString& sOut ) const

- Accessor method to string member data.

void SetValue( const int& n )

- Sets the integer member data and sets the value type to integer.

void SetValue( const double& n )

- Sets the double member data and sets the value type to double.

void SetValue( const TSString& s )

- Sets the string member data and sets the value type to string.

TSDynaValue& operator=( const TSDynaValue& sourceRecord );

- Sets this object equal to the one passed in.

TSDynaValueList


a list of TSDynaValues representing the data in a TSDynaRecord. (No class specific functions).

43

TSField


represents a single field of a record. The field object will contain one of the following: a text string, an

integer, a double, a TSRecordList, or a TSIntList, depending on the data type of the field.

Public Methods

TSField()


TSField( const TSField& field )


virtual ~ TSField()


virtual void Copy( TSObject* sourceField )

- Copies the contents of the sourceField into the calling field.

- Overridden from TSObject.

virtual TSObject* Duplicate( int type = 0 )

- Creates a new instance of a TSField object, calls the copy method, then returns a pointer to the new

instance.


virtual TSObject* NewObject()

- Creates a new instance of a TSField object, then returns a pointer to the new instance.


TSString DumpSchema( TSString indentation )

- For debugging purposes. Strings together the field name, data type, schema type, and field type values.

static TSString FieldTypeToName( int fieldType )

- Obtains the string equivalent of the integer value for field type.

void SetCharValue( const char* value )

- Used to set a new value for string values prior to update. If the charValue is to be set in preparation for

updating, call this method to set the new value. Do not perform any memory allocation operations

directly on this pointer, especially if using TSApiWinInet.

int SocketString( TSString& out )

- Used internally. Converts the calling TSField’s data to a string for sending across the socket.


virtual TSString StringDump( int recursive, TSString indentation )

- For debugging purposes. Outputs the TSField object to a string.


44

Public Member Variables

int dataType

- Populated if record was read from any table other than TS_FIELDS. The values indicate the type of

data the field contains, otherwise 0, and fieldType will be populated. Possible value are as follows:

TS_DATATYPE_INTEGER = 1

TS_DATATYPE_DOUBLE = 2

TS_DATATYPE_BOOL = 3

TS_DATATYPE_STRING = 4

TS_DATATYPE_RECORDLIST = 5

TS_DATATYPE_INTLIST = 6

TS_DATATYPE_UNKNOWN = 7

char fieldName[64]

- Display name of the field.

int fieldType

- Populated with the TS_FLDTYPE_X values defined in TSDef.h, if reading from the TS_FIELDS

table, otherwise null and dataType will be populated.

int schemaType

- Schema type for the field with values defined as:

TS_SCHEMATYPE_DBCOL = 1

TS_SCHEMATYPE_NONDB = 3

TS_SCHEMATYPE_LIST = 4

TS_SCHEMATYPE_TREELIST = 5

char* charValue

- Current values for field type:

TS_FLDTYPE_TEXT.

int charValueMax

- Buffer size for charValue.

double doubleValue

- Current values for field types:

TS_FLDTYPE_NUMERIC (if float), TS_FLDTYPE_SUMMATION (if float sums),

TS_FLDTYPE_DATETIME.

int intValue


TS_FLDTYPE_BINARY, TS_FLDTYPE_NUMERIC (if integer), TS_FLDTYPE_PROJECT,

TS_FLDTYPE_FOLDER, TS_FLDTYPE_SELECTION, TS_FLDTYPE_STATE,

TS_FLDTYPE_SUMMATION (if integer sums), TS_FLDTYPE_USER, TS_FLDTYPE_CONTACT,

TS_FLDTYPE_INCIDENT, TS_FLDTYPE_RELATIONAL.

TSIntList* intList


TS_FLDTYPE_MULTIPLE_SELECTION, TS_FLDTYPE_MULTIPLE_RELATIONAL,

TS_FLDTYPE_MULTIPLE_USER, TS_FLDTYPE_MULTIPLE_GROUP.

45

TSRecordList* recordList

- List of all selections for field types:

TS_FLDTYPE_SELECTION, TS_FLDTYPE_MULTIPLE_SELECTION, TS_FLDTYPE_ USER,

TS_FLDTYPE_MULTIPLE_USER, TS_FLDTYPE_MULTIPLE_GROUP.

46

TSFieldList

This class is derived from TSList. Refer to its section for documentation of inherited methods. It is used to

maintain a list of TSField objects. The class can be found in the TSList files.

Public Methods

TSFieldList()


~ TSFieldList()


int CopyUserDefSchemaToFieldList( TSFieldList& fieldList )

- Used internally to copy the user-defined fields from the user-defined schema to the calling record’s

fieldList.

int DeepCopy( const TSFieldList* sourceList, int type = 0 )

- Performs a deep copy of the sourceList onto the calling list by type if non-zero.

TSString DumpSchema( TSString indentation )

- Method used for debugging. Outputs the contents of the list’s schema to a string.

TSField* FindFieldByName( const char* fieldName, int fieldType = 0 )

- Returns a pointer to a field in the list whose name equals the passed in fieldName and whose field type

equals the passed in fieldType if non-zero.

TSField* GetAt( TSPosition* pos )

- Returns a pointer to the field in the list at the position passed.

- Overridden from TSList.

const TSField* GetAt( TSPosition* pos ) const

- Returns a const pointer to the field in the list at the position passed.

- Overridden from TSList.

47

TSIntList

This class is derived from of TSList. It is used to maintain a list of TSIntObjects for use with multiple

selection and multiple relational fields.

Public Methods

TSIntList()


virtual ~TSIntList()


TSString CommaSeparatedList() const

- Creates a comma separated string of the TSIntObjects on the TSIntList.

bool Find( int searchValue ) const

- Obtains the TSIntObject from the TSIntList whose member intValue matches the passed in

searchValue.

TSIntObject* GetAt( TSPosition* pos )

- Obtains a pointer to a TSIntObject from the list at the position passed.

const TSIntObject* GetAt( TSPosition* pos ) const

- Obtains a const pointer to a TSIntObject from the list at the position passed.

void PopulateByCommaSeparatedList( TSString sList )

- Populates the calling TSIntList from a string of comma separated values.

48

TSIntObject


provides the means to make a TSIntList of integers for use with multiple selection and multiple relational

fields.

Public Methods

TSIntObject()

- Default constructor method.

TSIntObject( int newIntValue )

- Primary constructor method.

TSIntObject( const TSIntObject& intObject )


virtual ~TSIntObject()


virtual void Copy( TSObject* sourceIntObject )

- Copies the sourceIntObject to the calling TSIntObject.


virtual TSObject* Duplicate( int type = 0 )

- Creates a new instance of a TSIntObject and calls the copy method.


virtual TSObject* NewObject()

- Creates a new instance of a TSIntObject object, returning a pointer to the new instance.


int SocketString( TSString& out )

- Used internally. Converts the calling TSIntObject’s data to a string for sending across the socket.

virtual TSString StringDump( int recursive, TSString indentation )

- For debugging purposes. Outputs the TSIntObject to a string.



int intValue

- The integer value associated with this object.

49

TSItem


defines the base interface for both primary and auxiliary items, and which have several shared

characteristics. This class should not be instantiated directly. The constructors are protected. See the

TSAuxiliaryItem and TSPrimaryItem derived classes.

Public Methods

virtual ~TSItem()


int AddAttachment( int nType, const TSString& sLabel, const TSString& sText, int nAccessType =

TS_ATTACHACCESS_DEFAULT )

- Adds an attachment to the calling item.

- Either the table and item id, or the project id and item number for the calling item must be preset.

- nType argument is a bit flag with values defined as:

File attachment: TS_ATTACHATTRIB_FILE = 0x0010

Note attachment: TS_ATTACHATTRIB_NOTE = 0x0080

URL attachment: TS_ATTACHATTRIB_URL = 0x0020

- sText argument should be:

File attachment: the full path to the file that will be read,

Note attachment: the note content, or

URL attachment: the complete URL.

- nAccessType argument determines the restricted or unrestricted status of the attachment with values

defined as:

TS_ATTACHACCESS_DEFAULT = -1; directs SBM to set the access type according to logic

dictated by the system setting: "Unrestricted Attachment Default". This is set via the settings

dialog display tab in the Administrator.

TS_ATTACHACCESS_RESTRICTED = 0; means to apply all note and attachment privileges

and preserves the behavior of TeamTrack versions 5.51 and earlier.

TS_ATTACHACCESS_UNRESTRICTED = 1; permits anyone with privilege to view the item to

also view this unrestricted note or attachment.


int AddAttachment( int nType, const TSString& sLabel, const TSString& sText, int& nAttachmentId, int

nAccessType = TS_ATTACHACCESS_DEFAULT )

- Adds an attachment to the calling item.


- Uses the same argument definitions as previous AddAttachment method, except for the addition of an

output argument, nAttachmentId, which will be populated with the record id of the attachment record

that was added.


int AddItemLinkById( int nDestTableId, int nDestItemId, int nLinkType, int nAccessType =


- Adds a link to the calling item.


50

- Item linked to is identified using its table id and item id.

- nLinkType argument is a bit flag with bit values defined as:

TS_STORE_ACTION_TWOWAYLINK = 0x0100.

TS_STORE_ACTION_SOURCETRIGGER = 0x0200.

TS_STORE_ACTION_DESTTRIGGER = 0x0400.

- Bitwise OR operation must be performed on the above bit flags to obtain certain types of links:

One way, no triggers = 0.

One way, current item triggers linked item = 0x0200.

Two way, no triggers = 0x0100.

Two way, current item triggers linked item = 0x0100 | 0x0200.

Two way, linked item triggers current item = 0x0100 | 0x0400.

Two way, both items trigger each other = 0x0100 | 0x0200 | 0x0400.


defined as:









int AddItemLinkByNumber( int nDestProjectId, int nDestItemNumber, int nLinkType, int nAccessType

= TS_ATTACHACCESS_DEFAULT )

- Adds an item link to the calling item.


- Item linked to is identified using its project id and item number.

- Uses the same argument definitions for nLinkType and nAccessType as previous AddItemLinkById

method.


bool AreAnyAttachmentsReq() const

- Determines whether any type of attachment is required for the transition.

void ClearSectionMaskBits( int nBitsToClear )

- Accessor method clearing specified nBitsToClear argument from member variable m_nSectionMask.

int DeleteAttachment( TSAttachmentList::iterator it )

- Deletes the attachment from the calling item and the calling item’s attachment list.


int DeleteItemLink( TSItemLinkList::iterator it, bool bDeleteBothSides = true )

- Deletes the item link from the calling item and the calling item’s item link list.

- bDeleteBothSides argument specifies whether to also delete the link back to this item if it exists.


51

virtual int FinishSubmit( bool bPopulateItem = false )

- Used after a call to StartSubmit.

- Adds the calling item to the database after the field values in the display field list have been set.




const TSAttachmentList& GetAttachmentList() const

- Accessor method returning a constant version of the member variable m_attachmentList, the item’s list

of file, note and URL attachments.

TSAttachmentList& GetAttachmentList()

- Accessor method returning a non-constant version of the member variable m_attachmentList, the

item’s list of file, note and URL attachments.

const TSChangeList& GetChangeList() const

- Accessor method returning a constant version of the member variable m_changeList, the item’s change

history list, ordered by user preference.

const TSDisplayFieldList& GetFieldList() const

- Accessor method returning a constant version of the member variable m_fieldList, the item’s list of

fields.

TSDisplayFieldList& GetFieldList()

- Accessor method returning a non-constant version of the member variable m_fieldList, the item’s list

of fields.

const TSItemLinkList& GetLinkList() const

- Accessor method returning a constant version of the member variable m_linkList, the item’s list of

item link attachments.

TSItemLinkList& GetLinkList()

- Accessor method returning a non-constant version of the member variable m_linkList, the item’s list of

item link attachments.

int GetSectionMask() const

- Accessor method returning member variable m_nSectionMask, a bit mask describing the sections that

will be obtained when a read method is called.

int GetTransitionFlags() const

- Accessor method returning member variable m_nTransitionFlags.

bool IsFileAttachmentReq() const

- Determines whether a file attachment is required for the transition.

bool IsItemAttachmentReq() const

- Determines whether an item link attachment is required for the transition.

bool IsNoteAttachmentReq() const

- Determines whether a note attachment is required for the transition.

bool IsUrlAttachmentReq() const

- Determines whether an URL attachment is required for the transition.

52

virtual int SetItemId( int nNewItemId )

- Accessor method setting member variable m_nItemId, the item id or record id.

- Only allowed when m_nMode is not equal to TS_TRANSITION_STARTED.


void SetSectionMask( int nNewSectionMask )

- Accessor method setting member variable m_nSectionMask, a bit mask describing the sections that

will be obtained when a read method is called, to the specified nNewSectionMask.

void SetSectionMaskBits( int nBitsToSet )

- Accessor method setting member variable m_nSectionMask, a bit mask describing the sections that

will be obtained when a read method is called, to the also include the specified nBitsToSet.

virtual int SetTableId( int nNewTableId )

- Accessor method setting member variable m_nTableId, the table id of the record.



virtual int StartSubmit()

- Populates the item’s m_fieldList with default values and orders fields as they would be for a submit,

including filling out field selection lists.

- m_attachmentList, m_changeList and m_linkList are emptied.

- Table id must be preset.


int UpdateAttachment( TSAttachmentList::iterator it, const TSString& sLabel, const TSString& sText, int

nAccessType = TS_ATTACHACCESS_DEFAULT )

- Updates an existing attachment of the calling item.

- Either the table and item id, or the project id and item number must be preset.

- sText argument should be:

File attachment: the full path to the file that will be read,

Note attachment: the note content, or

URL attachment: the complete URL.


defined as:









Protected Methods

TSItem( TSServer& server, int nTableId = 0, int nItemId = 0 )

- Constructor method; not to be accessed directly.

- Will set all bit masks except TS_SECTMASK_FILE_CONTENTS and TS_SECTMASK_HIDDEN in

m_nSectionMask.

53

TSItem( const TSItem& that )

- Copy constructor method; not to be accessed directly.

- Will set all bit masks except TS_SECTMASK_FILE_CONTENTS and TS_SECTMASK_HIDDEN in

m_nSectionMask.

TSItem& operator = ( const TSItem& that )

- Assignment operator method; not to be accessed directly.

virtual bool IsValid() const

- Called from TSServer and internally to verify m_nTableId and m_nItemId have been preset.

- Inherited from TSRecordRef.


TSAttachmentList m_attachmentList

- List of TSAttachment objects, the note, file and URL attachments to the item.

TSChangeList m_changeList

- List of TSChangeHistory objects, the change history for the item.

TSDisplayFieldList m_fieldList

- List of TSDisplayField objects, the field list for the item.

TSItemLinkList m_linkList

- List of TSItemLink objects, the item links attached the item.

int m_nMode

- Internal variable to keep track of status of item.

int m_nSectionMask

- Bit mask describing the sections that will be obtained when a read method is called. The values are

defined as follows:

TS_SECTMASK_STANDARD Standard Fields

TS_SECTMASK_USER User Fields

TS_SECTMASK_ADVANCED Advanced Fields

TS_SECTMASK_MANAGER Manager Fields

TS_SECTMASK_SYSTEM System Fields

TS_SECTMASK_NOTES Notes

TS_SECTMASK_FILES File Attachments

TS_SECTMASK_URLS URL Attachments

TS_SECTMASK_LINKS Item Links

TS_SECTMASK_CHANGES Change History

TS_SECTMASK_NOTE_CONTENTS Contents of notes with notes

TS_SECTMASK_FILE_CONTENTS Contents of files with files

TS_SECTMASK_HIDDEN Hidden Fields

TS_SECTMASK_ALL_EXCEPT_FILE_CONTENTS Everything but file contents, hidden fields

54

int m_nTransitionFlags

- Contains the flags for the transition, such as attachments are required, after calling StartSubmit,

StartTransition or StartUpdate methods.

int m_nTransitionId

- Used to keep track of the transition.

int m_nRecordLockId

- Used to keep track of the lock established for the transition.

55

TSItemLink


describes an item link attachment to a TSPrimaryItem or TSAuxiliaryItem object.

Public Methods

TSItemLink( TSServer& server, int nItemId = 0 )

- Constructor method; initializes object and automatically sets the table id member.

TSItemLink( const TSItemLink& that )


TSItemLink& operator = ( const TSItemLink& that )


virtual ~TSItemLink()



- Accessor method returning member variable m_nAccessType, the type of access assigned to the item

link.

const TSString& GetCreator() const

- Accessor method returning member variable m_sCreator, the user who created the link.

const TSString& GetDateTimeCreated() const

- Accessor method returning member variable m_sDateTimeCreated, the date and time the link was

created.

int GetDestItemId() const

- Accessor method returning member variable m_nDestItemId, the id of the linked item.

int GetDestItemNumber() const

- Accessor method returning member variable m_nDestItemNumber, the item number of the linked

item.

int GetDestProjectId() const

- Accessor method returning member variable m_nDestProjectId, the project id of the linked item.

int GetDestTableId() const

- Accessor method returning member variable m_nTableId, the table id of the linked item.

int GetLinkType() const

- Accessor method returning member variable m_nLinkType, the type of the link.

int GetSequence() const

- Accessor method returning member variable m_nSequence, the sequence number of the attachment, if

used.


int m_nAccessType

- Determines the restricted or unrestricted status of the item link attachment; defined as:

56

TS_ATTACHACCESS_RESTRICTED = 0. Apply all attachment privileges. Also preserves the

behavior of TeamTrack versions 5.51 and earlier.

TS_ATTACHACCESS_UNRESTRICTED = 1. Permits anyone with privilege to view the item, to

also view this unrestricted attachment.

int m_nDestItemId

- Item id of the linked item.

int m_nDestItemNumber

- Item number, as shown in a browser, of the linked item.

int m_nDestProjectId

- Project id of the linked item.

int m_nDestTableId

- Table id of the linked item.

int m_nLinkType

- Type of link defined as a bit flag with bit values:

TS_STORE_ACTION_TWOWAYLINK = 0x0100.

TS_STORE_ACTION_SOURCETRIGGER = 0x0200.

TS_STORE_ACTION_DESTTRIGGER = 0x0400.

- Bitwise OR operation must be performed on the above bit flags to obtain certain types of links:

One way, no triggers = 0.

One way, current item triggers linked item = 0x0200.

Two way, no triggers = 0x0100.

Two way, current item triggers linked item = 0x0100 | 0x0200.

Two way, linked item triggers current item = 0x0100 | 0x0400.

Two way, both items trigger each other = 0x0100 | 0x0200 | 0x0400.

int m_nSequence

- Attachment sequence number. If used, this is the unique sequence number for each attachment,

whether a file, URL, item link or note, to a given item. The first attachment to any unique primary or

auxiliary item will be given the sequence number of 1. Each successive attachment to the same item

will be numbered sequentially. If an attachment to a given item is deleted, its sequence number is

permanently retired. The next attachment will be given the next sequence number as if no attachments

had been deleted.

- This feature is disabled by default. It is enabled through the Display tab of the Settings dialog in the

Administrator.

TSString m_sCreator

- User that created the link.

TSString m_sDateTimeCreated

- Date and time the link was created.

57

TSList

This class is the base class for various types of list classes.

Public Methods

TSList()

- Constructor method; initializes the list object.

TSList( const TSList& sourceList )


TSList& operator = ( const TSList& sourceList )


~TSList()


int AddHead( TSObject* object )

- Adds an element to the beginning of the list.

int AddTail( TSObject* object )

- Adds an element to the end of the list.

int Copy( const TSList* sourceList )

- Copies the contents of the sourceList into the calling list.

- Use the EmptyList method rather than EmptyAndDestroyList method on the sourceList after a copy to

avoid memory leaks.

int Duplicate( TSList* newList, int type = 0 ) const

- For each object on the calling list, creates a new instance of the object, copies the calling list object

onto the new instance, then adds the new instance to the newList argument passed.

void EmptyAndDestroyList()

- Empties the list and deletes each object.

void EmptyList()

- Empties the list but does not delete the objects.

TSPosition* Get( int index ) const

- Obtains the position (iterator) of the object in the list at the index passed.

TSObject* GetAt( TSPosition* pos ) const

- Obtains a pointer to the object in the list at the position passed.

TSPosition* GetFirst() const

- Obtains the position (iterator) of the first object in the list.

TSPosition* GetLast() const

- Obtains the position (iterator) of the last object in the list.

TSPosition* GetNext( TSPosition* pos ) const

- Obtains the position (iterator) of the next object in the list from the position passed.

58

TSPosition* GetPrev( TSPosition* pos ) const

- Obtains the position (iterator) of the previous object in the list from the position passed.

int InsertAfter( TSPosition* pos, TSObject* object )

- Adds the object to the list after the position passed.

int InsertBefore( TSPosition* pos, TSObject* object )

- Adds the object to the list before the position passed.

int Length() const

- Accessor method returning member variable length, the number of objects in the list.

TSObject* RemoveObject( TSObject* pObject )

- Removes the object from the list.

- Returns a pointer to the object or NULL if not found.

TSObject* RemoveObject( TSPosition* pos )

- Removes an object from the list at the position passed.


TSObject* RemoveObject( int index )

- Removes an object from the list at the index passed.


virtual int SocketString( TSString& out )

- Used internally to convert the objects on the calling list to a string for sending across the socket.

TSString StringDump( int recursive, TSString indentation )

- Method used for debugging. Outputs the objects on the calling list to a string.

59

TSObject

This class is an abstract base class for objects to be put on a TSList. Many API classes inherit from this

class.

Public Methods

TSObject()

- Constructor method; initializes the object.

virtual ~TSObject()


virtual void Copy( TSObject* sourceObject ) = 0

- Pure virtual function at this level.

virtual TSObject* Duplicate( int type = 0 ) = 0

- Allocates a new instance of this and then calls Copy.


virtual TSObject* NewObject() = 0


virtual int SocketString( TSString& str ) = 0


virtual TSString StringDump( int recursive, TSString indentation ) = 0



int fieldType

- Used if the object is a field from the TS_FIELDS table.

60

TSPosition

This class is used to iterate through a list of TSRecords, TSFields, or TSIntObjects. It is a pointer to a

position in a list. The class can be found in the TSList files.

Public Methods

TSPosition()

- Constructor method; initializes the position object.

TSPosition( TSPosition* nextPos, TSPosition* prevPos, TSObject* thisObj )

- Constructor method; initializes the position object.


TSPosition* next

- Pointer to the next position in the list.

TSObject* object

- Pointer to the object in the list.

TSPosition* prev

- Pointer to the previous position in the list.

61

TSPrimaryItem

This class is derived from TSItem. Refer to its section for documentation of inherited methods. It defines

the interface for an object that has variable fields and is a primary item.

Public Methods

TSPrimaryItem( TSServer& server, int nTableId = 0, int nItemId = 0 )


TSPrimaryItem( TSServer& server, const TSProject& project, int nItemNumber = 0 )


TSPrimaryItem( const TSPrimaryItem& that )


TSPrimaryItem& operator = ( const TSPrimaryItem& that )


virtual ~TSPrimaryItem()


virtual int CancelTransition()

- Used after a call to StartTransition, but when FinishTransition will not be called.

- Clears the lock on the record.


virtual int FinishSubmit( bool bPopulateItem = false )

- Used after a call to StartSubmit.

- Adds the calling item to the database after the field values in the display field list have been set.


- Populates m_nItemNumber.



- Overridden from TSItem.

virtual int FinishTransition( bool bStealLockFlag = false, bool bPopulateItem = false )

- Used after a call to StartTransition.

- Transitions the calling item in the database after the field values in the display field list have been set.



- After a successful database transition, the lock will be removed.

- Will return TS_LOCK_UNAVAILABLE if the lock has expired and another user has taken the lock.


virtual int FinishTransition( bool bStealLockFlag = false, bool bPopulateItem = false,

TSItem& submitItem, bool bPopulateSubmitItem = false )

- Used after a call to StartTransition for a Copy, Post Item, Publish Problem or Subtask type transition,

and then only if you need to specify an alternate submit transition or if you want to fill in field values

different from default values for the submitted item.

62

- Similar to above but intended for use with a Copy, Post Item, Publish Problem or Subtask type

transition only. If used with any other transition type, the additional arguments are ignored unless they

are invalid.

- submitItem must be either a TSPrimaryItem or a TSAuxiliaryItem object and StartTransition must have

already been called on that object or an error will be returned. You may call StartTransition with an

alternate, hidden submit transition if you wish. You must initialize submitItem with the table and

project into which you wish to submit the post item because these values override the table and project

ids defined for the originating transition.

- The post submit will fail if there are required fields that have not be explicitly filled in after

StartTransition or that do not have default values.

- It is possible for the originating transition to succeed and for the subsequent submit to fail due to

invalid fields or insuficcient submit privileges. This mimics browser behavior.

- Repopulates the submitItem, to get default or automatic values, when bPopulateSubmitItem is true.


int GetItemNumber() const

- Accessor method returning member variable m_nItemNumber, the item number, as displayed in a

browser, for the primary item.

const TSString& GetItemType() const

- Accessor method returning member variable m_sItemType, the item type prefix string.

int GetProjectId() const

- Accessor method returning member variable m_nProjectId, the project id for the primary item.

int GetStateId() const

- Accessor method returning member variable m_nStateId, the id of the state in which the primary item

is located.

virtual int GetSubmitTransitions( TSTransitionList& results, bool bIncludeHidden = true )

- results list is an allocated TSTransitionList&. The list may or may not already be populated. If the list

is already populated, this method empties the list and destroys the list elements before populating with

the new items. The project id member of this must already be set.

- If bIncludeHidden is true, then the list will contain submit transitions with the

TS_TRANS_FLG_TRIGGER flag set ('No Button On Form'). If false, then only the default browser-

enabled submit transition is returned. Returns TS_OK on success, even if there are no valid, enabled

submit transitions for the project, in which case the list will be empty. However, the caller must have

submit privileges in the project.

virtual int GetSubmitTransitions( int nProjectId, TSTransitionList& results, bool bIncludeHidden = true )

- Similar to above, except the nProjectId argument overrides the project id member of this.

virtual int GetSubmitTransitions( TSProject& project, TSTransitionList& results, bool bIncludeHidden =

true )

- Similar to above, except the project's item ID overrides the project id member of this.

virtual int GetTransitionList( TSTransitionList& results )

- Returns a list of TSTransition records indicating which transitions are currently valid for this item.

- The order of the objects on the returned list is that of the transition order specified for the item in its

current state.

- Either the table id and item id, or the project id and item number must be preset.


63

virtual int Read()

- Populates the item as specified by m_nSectionMask, taking into consideration the privileges of the

user, or alternate user if set, and orders the fields as they would be when viewed in a browser.

- Either the table and item id, or the project id and item number must be preset.



int ReadByNumber( int nProjectId, int nItemNumber )

- Sets m_nProjectId and m_nItemNumber members, clears m_nItemId, then calls Read.


int SetItemNumber( int nNewItemNumber )

- Accessor method setting member variable m_nItemNumber, the item number, as displayed in a

browser, for the primary item.


int SetProjectId( int nNewProjectId )

- Accessor method setting member variable m_nProjectId, the project id for the primary item.






virtual int StartSubmit( int nTransitionId = 0 )

- Populates the item’s m_fieldList with default values and orders fields as they would be for a submit,

including filling out field selection lists.

- m_attachmentList, m_changeList and m_linkList are emptied.

- Project id must be preset.

- Only allowed when m_nMode is equal to NOT_IN_TRANSITION.

- If nTransitionId is 0 or not supplied, then the browser-enabled default submit is used. Alternately, you

can supply a valid hidden submit transition defined for the project.


virtual int StartSubmit( const TSString& sTransitionName )

- Similar to above except that the desired submit transition is specified by its display name (case-

sensitive).

virtual int StartSubmit( const TSTransition& transitionItem )

- Similar to above except that the desired submit transition is specified by the item ID of transitionItem.

int StartSubmitIntoProject( int nProjectId, int nTransitionId = 0 )

- Sets m_nProjectId, clears m_nTableId and m_nItemId, then calls StartSubmit.


- If nTransitionId is 0 or not supplied, then the browser-enabled default submit is used. Alternately, you

can supply a valid hidden submit transition defined for the project.


64

int StartSubmitIntoProject( const TSString& sTransitionName )

- Similar to above except that the desired submit transition is specified by its display name (case-

sensitive).

int StartSubmitIntoProject( const TSTransition& transitionItem )

- Similar to above except that the desired submit transition is specified by the item ID of transitionItem.

int StartSubmitIntoProject( TSProject& project, int nTransitionId = 0 )

- Similar to overload 1 except that m_nProjectId is set to the item id of the project argument.

int StartSubmitIntoProject( const TSString& sTransitionName )


int StartSubmitIntoProject( const TSTransition& transitionItem )


virtual int StartTransition( int nTransitionId )

- Populates the item’s m_fieldList with default values and orders fields as they would be for the

transition specified by nTransitionId, including filling out field selection lists.

- m_attachmentList, m_changeList and m_linkList member lists will not be updated.

- Locks the record. While the record is locked, any other user, via API or browser interface, will receive

an error if they attempt to update the same record. The SBM administrator sets the time a lock is held.




virtual int StartTransition( TSString sTransitionName )


transition specified by sTransitionName, including filling out field selection lists.



an error if they attempt to update the same record. The SBM administrator sets the time a lock is held.




virtual int StartTransition( const TSTransition& transitionItem )


transition specified by transitionItem, including filling out field selection lists.



an error if they attempt to update the same record. The SBM Administrator sets the time a lock is held.





int m_nItemNumber

- Integer version of the item number, as shown in a browser.

65

int m_nProjectId

- Project id for the primary item.

int m_nStateId

- Id of the state in which the primary item is located.

TSString m_sItemType

- Prefix of the item indicating its type, e.g. BUG.

66

TSProject

This class is derived from TSRecordRef. Refer to its section for documentation of inherited methods. It is

used to provide the sFullProjectName in a tab-delimited ( î ) string representing the full project hierarchy,

e.g., SBM ProjectsîEngineeringîProductsîtSupportiIncidents.

Public Methods

TSProject( TSServer& server, TSString sFullProjectName )

- Constructor method; initializes the project object and automatically sets the table id member.

TSProject( TSServer& server, int nProjectId = 0 )

- Constructor method; initializes the project object and automatically sets the table id member.

TSProject( const TSProject& that )


TSProject& operator = ( const TSProject& that )


virtual ~TSProject()


const TSString& GetFullProjectName() const

- Accessor method returning member variable m_sFullProjectName, the complete tab-delimited project

name.

const TSString& GetItemName() const

- Accessor method returning member variable m_sItemName, the non-hierarchical name of the project.


int GetPrimaryTableId() const

- Accessor method returning member variable m_nPrimaryTableId, the primary table id for the project.

int GetProjectId() const

- Accessor method returning member variable m_nItemId, the id of the project, by calling GetItemId.

int ReadByFullProjectName( TSString sFullProjectName )

- Sets m_sFullProjectName, clears m_nItemId, then calls Read.


void SetFullProjectName( const TSString& sNewFullProjectName )

- Accessor method setting member variable m_sFullProjectName, the complete tab-delimited project

name, and clearing m_nItemId.


- Accessor method setting member variable m_nItemId, the id of the project, and clearing

m_sFullProjectName.


void SetProjectId( int nNewProjectId )

- Accessor method setting member variable m_nItemId, the id of the project, by calling SetItemId.

67


int m_nPrimaryTableId

- Id of the primary table associated with the project.

TSString m_sFullProjectName

- Tab-delimited string containing the full project hierarchical name.

68

TSRecord

This class is derived from TSObject. Refer to its section for documentation of inherited methods. The

TSRecord class contains the data for a particular record in the database. The constructor asks for the list of

fields for a record of its type from the server. The API programmer can fill in fields for performing an

AddRecord or use it to perform a ReadRecord or any other method that returns a record.

Public Methods

TSRecord()

- Default constructor method. Initializes the TSRecord object with tableid = 0, NULL server value,

fieldType = 0, and getExtendedData = true.

TSRecord( int tableId, TSServer* server, int fieldType = 0, bool getExtendedData = true )

- Primary constructor method. Initializes the TSRecord object with the tableid and server object passed

in order to create a record object for the appropriate table. FieldType defaults to 0; pass in the correct

fieldType when creating a record from the TS_FIELDS table. GetExtendedData defaults to true; pass

in false to get a record with only the fieldList populated and no member lists or sublists. If hierarchical

data is needed, use the default of true for getExtendedData.

~TSRecord()

- Destructor method; also empties and destroys the fieldList.

void ClearDeletedRecord()

- Reverses the value of the RecordDeleted variable and assigns it to recordState.

void ClearNewRecord()

- Reverses the value of the RecordNew variable and assigns it to recordState.

void ClearNewRecordWithID()

- Deprecated. Do not use. Reverses the value of the RecordNewWithID variable and assigns it to

recordState.

void ClearUpdatedRecord()

- Reverses the value of the RecordUpdated variable and assigns it to recordState.

void Copy( TSObject* sourceRecord )

- Copies the member variables of sourceRecord into the calling TSRecord object.


void DeepCopy( TSRecord* sourceRecord )

- Performs a deep copy of the sourceRecord onto the record calling the method.

TSObject* Duplicate( int type = 0 )

- Allocates a new instance of this TSRecord object and then calls Copy.


double GetDouble( const char* fieldName )

- Finds the field of type double, by fieldName, in the fieldList, returning the field’s doubleValue

variable. Note: column name must be the same case as found in the fieldList.

int GetDouble( const char* fieldName, double* value )

- Finds the field of type double, by fieldName, in the fieldList, assigning the field’s doubleValue

variable to the parameter ‘value’. Note: column name must be the same case as found in the fieldList.

69

int GetInt( const char* fieldName )

- Finds the field of type int, by fieldname, in the fieldList, returning the field’s intValue variable. Note:

column name must be the same case as found in the fieldList.

int GetInt( const char* fieldName, int* value )

- Finds the field of type int, by fieldname, in the fieldList, assigning the field’s intValue variable to the

parameter ‘value’ . Note: column name must be the same case as found in the fieldList.

int GetRecordList( const char* fieldName, TSRecordList** value )

- Finds the field of type TSRecordList, by fieldname, in the fieldList , assigning the field’s recordList

variable to the parameter ‘value’. This method allocates a buffer for the parameter ‘value’ using a call

to new, then copies the field’s recordList to ‘value’. The caller is responsible for destroying ‘value’

using a call to delete. Note: column name must be the same case as found in the fieldList.

- Warning: Do not use if your API program is to be linked with WinInet.lib.

TSRecordList* GetRecordList( const char* fieldName )

- Finds the field of type TSRecordList, by fieldname, in the fieldList , returning the field’s recordList

variable. Note: column name must be the same case as found in the fieldList.

int GetString( const char* fieldName, char** value )

- Deprecated—this overload will fail if the API is linked with WinInet.lib.

- Finds the field of type char*, by fieldName, in the fieldList, assigning the field’s charValue variable to

the parameter ‘value’. This method allocates a buffer for the parameter ‘value’ using a call to new. The

caller is responsible for destroying ‘value’ using a call to delete. Note: column name must be the same

case as found in the fieldList.

char* GetString( const char* fieldName )

- Finds the field of type of char*, by fieldName, in the fieldList, returning a pointer to the field’s

charValue variable, which is internally allocated data and should NOT be freed by the caller. Do not

modify or realloc the pointer or its contents in any way. Treat it as const. Note: column name must be

the same case as found in the fieldList.

int GetString( const char* fieldName, char* value, int bufferSize )

- Finds the field of type of char*, by fieldName, in the fieldList, assigning the field’s charValue variable

to the parameter ‘value’ of length ‘bufferSize’. If the length of the field’s charValue is of size

‘bufferSize’ or greater, ‘value’ will NOT be NULL terminated. Note: column name must be the same

case as found in the fieldList.

int GetString( const char* fieldName, TSString* value )

- Finds the field of type of char*, by fieldName, in the fieldList, assigning the field’s charValue variable

to the parameter ‘value’. Note: column name must be the same case as found in the fieldList.

TSTreeList* GetSubTreeList()

- Returns a pointer to the sub-tree (hierarchical child records) if this is a project, workflow, or folder,

otherwise returns NULL.

int GetUserDefinedFieldsLength()

- Returns the length of the userDefinedFields list; that is the number of user-defined fields defined for

this record's table.

- Used only for debugging.

70

bool IsDeletedRecord()

- Checks the recordState and returns true if this record is marked as deleted. NOTE that a record is

considered deleted if the recordState flag is Deleted and not New. To check just the Deleted

recordState flag, call IsDeletedFlagSet.

bool IsDeletedFlagSet()

- Checks the recordState and returns true if the deleted flag is set. NOTE that this is slightly different

from IsDeletedRecord because IsDeletedFlagSet does not check to see if the recordState flag is also

marked as new.

bool IsInitialized( int tblid = 0 )

- Verifies the record is fully initialized, i.e. has a non-null server pointer and any valid table id. If a table

id is passed, the record’s tableId must be the same as the passed parameter.

bool IsNewRecord()

- Checks the recordState and returns true if this record is marked as new. NOTE that a record is

considered new if the recordState flag is marked as New and not Deleted.

bool IsUpdatedRecord()

- Checks the recordState and returns true if the record has been updated. NOTE that a record is

considered updated only if the recordState flag is not marked as Deleted or New.

TSObject* NewObject()

- Creates a new instance of a TSRecord object, returning a pointer to the new instance.

int Receive( TSSocket* socket, bool bIgnoreNonDbMembers = false )

- Receives a TSRecord off the socket.

- Though public, this method is for internal only use and called from TSServer.

int ReceiveSpecifiedFields( TSSocket* socket )

- Receives fields specified by the caller off the socket.

- Though public, this method is for internal only use and called from TSServer.

void SetDeletedRecord()

- Assigns the RecordDeleted value to recordState.

int SetDouble( const char* fieldName, double value )

- Finds the field of type double, by fieldName, in the fieldList, assigning the parameter ‘value’ to the

field’s doubleValue, then sets the recordState to RecordUpdated and returns a status value.

- If fieldName corresponds to datetime field ( i.e.TS_DATATYPE_DATETIME ), the value parameter

is assumed to be the number of days passed since December 30th 1899. The fractional part of this

double number defines the time part of this value. The value might be negative or positive without

restrictions.

int SetInt( const char* fieldName, int value )

- Finds the field of type int, by fieldName, in the fieldList, assigning the parameter ‘value’ to the field’s

intValue, then sets the recordState to RecordUpdated and returns a status value.


is assumed to be the number of seconds passed since January 1st 1970. Both negative and positive

values are accepted. For positive numbers, the valueshould be more than the number of seconds per

day ( i.e. 86400 ).

void SetNewRecord()

- Assigns the RecordNew value to recordState.

71

void SetNewRecordWithID()

- Deprecated. Do not use.

- Assigns the RecordNewWithID value to recordState.

int SetString( const char* fieldName, const char* value )

- Finds the field of type char*, by fieldName, in the fieldList, assigning the parameter ‘value’ to the

field’s charValue, then sets the recordState to RecordUpdated and returns a status value.


should be in ISO8601 format ( e.g. “2012-05-30T09:00:00+00:00” ).

void SetUpdatedRecord()

- Assigns the RecordUpdated value to recordState.


TSFieldList fieldList

- List of all fields defined for the table in which this record belongs.

int fieldType

- If this is a TSRecord representing a record from the TS_FIELDS table, then this is the field type.

TSServer* serverRef

- Back pointer to the server object.

int sqlDataType

- If this is a TSRecord representing a record from the TS_FIELDS table, then this is the SQL data type.

int tableId

- The ID of the table this record is associated with.

TSString tableName

- The display name of the table this record is associated with.

Important Notes:

When instantiating a record from any table, you always get the full schema. If creating a record from the

Fields table, you will additionally receive the sqlDataType.

There are certain tables that contain a few non-database columns of type TSList. Please refer the section on

“Steps to Building a Simple API Application Program” for more information. When you instantiate a

TSRecord object from one of these tables, make sure you clear the member lists by calling EmptyList() or

EmptyAndDestroyList() from the TSList class before re-using the TSRecord object.

72

TSRecordRef

This class is the base class for several other class objects. It can also be instantiated stand-alone, when only

the name of an item needs retrieving.

Public Methods

TSRecordRef( TSServer& server, int nTableId = 0, int nItemId = 0 )

- Constructor method; initializes the TSRecordRef object.

TSRecordRef( const TSRecordRef& that )


TSRecordRef& operator = ( const TSRecordRef& that )

- Assignment method.

virtual ~TSRecordRef()


int GetItemId() const

- Accessor method returning member variable m_nItemId, the item id or record id.

const TSString& GetItemName() const

- Accessor method returning member variable m_sItemName, the name of the record.


- Accessor method returning member variable m_nTableId, the table id of the record.

virtual bool IsValid() const

- Verifies m_nTableId and m_nItemId have been preset.

virtual int Read()

- All data members will be populated.

- Table id and item id must be preset.


int ReadById( int nItemId )

- Sets the m_nItemId variable, then calls the virtual read method.

- Table id must be preset.


virtual int Receive( TSSocket* socket )

- Only intended to be called by member methods of TSServer or TSDisplayField.


- Accessor method setting member variable m_nItemId, the item id or record id.



TSString StringDump( TSString sIndentation )

- Method used for debugging. Outputs the TSRecordRef object to a string.

73

Protected Methods

virtual void GetRequest( TSString & sRequest ) const

- Only intended to be called by member methods of TSServer.


int m_nItemId

- Item id or record id of the item.

int m_nTableId

- Table id of the item. See TSDef.h for a complete listing of possible TS_TBLID_ values.

TSServer& m_server

- Reference to the server connection.

TSString m_sItemName

- Name of the item.

74

TSRecordList


maintain a list of TSRecord objects. The class can be found in the TSList files.

Public Methods

TSRecordList( bool getExtendedData = true )

- Constructor method. Passing in false shortens the number of socket runs and the size of each TSRecord

object in the list by limiting the data sent across the socket for each record to simply each record’s field

list, i.e., no member lists, sublists, or extended user-defined fields. Each TSRecord’s fieldList member

will contain the full list of fields minus only the extra lists of data. However, if hierarchical data is

needed, e.g. reading projects, workflows, or folders, use the default of true for getExtendedData.

virtual int ~TSRecordList()


int DeepCopy( const TSRecordList* sourceList, int type = 0 )

- Performs a deep copy of the sourceList onto the calling list by type if non-zero.

virtual TSRecord* FindRecord( int recId )

- Returns a pointer to a record in the list whose id equals passed in recId.

virtual TSRecord* FindRecord( const char* fieldName, const char* searchValue )

- Returns a pointer to a record in the list that has a field named the passed in fieldName and charValue

equal to the passed in searchValue.

virtual TSRecord* FindRecord( const char* fieldName, double searchValue )

- Returns a pointer to a record in the list that has a field named the passed in fieldName and doubleValue


virtual TSRecord* FindRecord( const char* fieldName, int searchValue )

- Returns a pointer to a record in the list that has a field named the passed in fieldName and intValue


virtual TSRecord* FindRecord( const char* fieldName, int nTableId, int nFieldType, int nSqlDataType )

- Returns a pointer to a record in the list that has a field named the passed in fieldName and also whose

table id, field type and SQL data type equal the passed in values. This is a search based on structure,

not data.

virtual TSRecord* FindRecordByDbName( const char* fieldDbName, int nTableId, int nFieldType, int

nSqlDataType )

- Returns a pointer to a record in the list that has a field database name equal the passed in fieldDbName

and also whose table id, field type and sql data type equal the passed in values. This is a search based

on structure, not data.

int Receive( TSServer* server, TSSocket* socket )

- Used internally to receive the incoming list off the socket.

void SetIsFieldList( BOOL bIsFields )

- Accessor method setting the member variable m_bIsFieldList, whether or not this is a list of fields.

75


bool bGetExtendedData

- Flag determining whether or not to send the extended user-defined field list, member lists and sublists.

76

TSSchema

This class is derived from TSObject. Refer to its section for documentation of inherited methods. This class

provides a means for obtaining a given table’s static field list. The class can be found in the TSServer files.

Public Methods

TSSchema()

- Constructor.

~TSSchema()

- Destructor. Also empties and destroys the field list.

void Copy( TSObject* sourceSchema )

- Copy the contents of sourceSchema into the current TSSchema object.


TSObject* Duplicate()

- Creates a new instance of a TSSchema object and duplicates the calling TSSchema’s members onto the

new instance.



- Returns a new instance of a TSSchema object, returning a pointer to the new instance.


int SocketString( TSString& /*str*/ )

- This function is not needed for a schema object since it’s a client side only object.


TSString StringDump( int /*recursive*/, TSString indentation )

- Builds a string of tableid and name; used mainly for debugging purposes.




- List of all fields defined for the table this schema represents.

TSString name

- The display name of the table this schema represents.

int tableId

- The ID of the table this schema represents.

int userDefinedFields

- Non-zero if this schema represents a table having user-defined fields.

77

TSServer

TSServer is the main class used to communicate with SBM systems. TSServer will encode data in a string

to be sent through the Web server to SBM. TSServer knows how to connect to the web server, check

permissions for the actions being performed and maintain lists of fields for each record type.

The first time a TSRecord is instantiated for a particular record type, the TSServer will retrieve a list of the

fields for that record type from SBM and cache that list of fields. Each subsequent time a TSRecord of that

type is created, its field information will be filled in from the cache.

TSServer will connect to the Web server using either the server name (machine name) or the server’s IP

address. If it fails to connect, the constructor will throw an exception. If the username doesn’t exist or the

password is invalid, the constructor will also throw an exception.

The Send method of the TSServer class is what the other methods use to talk to the server. It sends the

string across the socket to the server, receives the resulting string, and loads it into a TSRecord object for

the API programmer to use.

Privilege Checking

The primary privilege, "Connect Using the API", is required of all users wishing to execute API methods.

In most cases, this is the only privilege that determines whether or not an API user is permitted to execute a

particular API method. On the other hand, some methods require the API user to have additional privileges

in order to execute them. Where this is the case, information indicating which privileges are required is

included in the method description. Note that most of the methods beginning with “TS” are actually

execution conduits for methods typically invoked through objects of type TSItem and derived classes. For

example, TSServer::TSPrimaryItemRead is typically invoked through the TSPrimaryItem::Read method.

Therefore, it follows that the execution of TSPRimaryItem::Read requires the same privileges as

TSServer::TSPrimaryItemRead.

Public Methods

TSServer( unsigned int nConnectionSettings = 0 )

- Constructor method; creates a TSServer object. The nConnectionSettings parameter is used to define

various behaviors of the API at runtime. Possible values for nConnectionSettings:

- TS_COMPAT_ALLOWMULTIUSERGROUPFULLGROUPS For backward compatibility,

Multi-User-Group fields unroll any whole groups that are selected into lists of users before

sending the values to the API. This maintains old behavior, where the values always were lists of

users. If you wish to force the API to send the whole groups without unrolling, pass this argument

(bit) into the contstructor of the TSServer object. The Multi-User-Group values will continue to be

sent as comma separated lists of integers that represent users, but for group values, the integer is

preceeded with a “G”. The value might look something like: “,G12,G27,74,1065,”.

- TS_COMPAT_USEUTF8FORALLSTRINGDATA SBM Server needs to know what character

set the API client wishes to receive data in (and what character set the data is in that the API client

sends to the server). For backward compatability within TeamTrack API applications, the default

behavior is for the SBM server to read the “Pre-Unicode Charset” setting from

TS_SYSTEMSETTINGS. This setting documents what the TeamTrack character set was before

the upgrade to SBM. If this setting exists, SBM will send and receive data with the API client

application using this character set. Otherwise, the server will default to UTF-8. If the client

wishes to force the server to interact using UTF-8, pass this argument (bit) in when creating a

TSServer object.

- Please note, most character sets other than the UTF character sets are designed to support a

single language. Therefore, it is possible to lose data when using non-Unicode character sets.

For instance, Shift-JIS is designed to support ASCII plus Japanese. If an API application

requested to read an issue from the server using the backward compatibility mode (no bit sent

78

in to force UTF-8), and the “Pre-Unicode Charset” was set to “Shift-JIS”, the server would

convert all string data being sent to the API client into Shift-JIS. What if the issue contained

Russian characters? These get replaced during code-page conversion with a place-holder,

usually “?”, because the character set Shift-JIS simply has no way to represent Russian data.

If the API client then updated the issue to change a field value, it will write back to the server

the data it has, which is a set of “?” replacement characters, and the Russian data is lost from

the server. Using the UTF-8 bit avoids this issue, but your API application must be designed

to send and receive UTF-8.

- Please note, character set conversion can slow down an application. Using this bit may give

your API application a (slight) performance improvement.

~TSServer()

- Destructor method; destroys the schema cache.

int AddField( TSRecord* field, int tableid, int fieldType )

- Use to add a field to a given table. Calling this function will perform the AddRecord() on the Fields

table and then uses that information to add the field to the appropriate table. Fields can be added to any

primary or auxiliary table as specified by the tableId parameter. There is no need to set field’s tableId

before passing the field record into this function. A return of TS_OK indicates success and fieldId is

set to the TS_ID of the newly added field record. Any other return code indicates that the field was not

added and fieldId is set to 0. Extended error information can be obtained by calling

GetLastErrorMessage().

int AddGroupsFromXML(const char* sXML, bool bOverwriteExisting = false, bool bParseOnly = false)

- Add one or more SBM groups from an XML definition. Passing true for bOverwriteExisting means

that if the group already exists, it will be overwritten with data in the XML file. Passing true for

bParseOnly will send the XML through the parser/validator, but no changes to the database will be

made. Requires the "Remote Administration" system privilege, "Add Groups" and "Edit Groups"

administration privileges, and the "Assign Privileges" administration privilege for the base project.

int AddRecord( TSRecord* rec, TSRecord* newRecord /*=NULL*/ )

- Use for adding a singular record (row) to a table. This is not recommended for adding a record to a

Primary, e.g. ISSUES, or Auxiliary, e.g. COMPANIES, table. Use Submit.

int AddTable( TSRecord* table, TSRecord* solution /*=NULL*/, int optionalFields /*=0*/, int reserved

/*=0*/ )

- Add a new table, primary or auxiliary to the database.

table.id Ignored

table.name Plural display name. Required, no more than 25 characters.

table.lastid Ignored

table.cachestatus Ignored for primary tables. For auxiliary tables, 0 = do not cache, 1 = enable

caching.

table.cachecounter Ignored

table.lockuserid Ignored

table.locktime Ignored

table.reclock Record locking timeout value. Must be between 1 and 1440. A value outside this

range is not an error, but will be forced within this range.

table.dbname Internal, unchangeable database name. Required, no more than 25 characters of the

set [A-Z, 0-9, _]. Do not include the prefix—it will be prepended from the

solution.prefix, if supplied, or the default ‘U’ if not.

79

table.sname Singular display name. Required, no more than 25 characters.

table.description Optional, up to 80 characters.

table.format Optional value display format string of the form

“{[literals]<fieldname>[literals]}…”. For example “<Title>: <Description>”. If not

supplied the default is “<Title>”.

table.solutionid Ignored. See solution.id.

table.type Must be either TS_TBLTYPE_PRI, in which case the solution record argument

must be supplied, or TS_TBLTYPE_AUX in which case solution is optional. If

solution is NULL when creating an auxiliary table, the table prefix is set to the

default of “U”.

table.flags Bitwise OR of optional TS_TBLFLG_ definitions.

table.archive Ignored. Not applicable.

table.imagea Ignored. Set to internal default.

table.imageb Ignored. Set to internal default.

table.lookup1 Ignored. Not applicable.

table.lookup2 Ignored. Not applicable.

solution.id Ignored for primary tables. For auxiliary tables, 0 indicates that this new auxiliary

table is not to be associated with any solution. If not 0, it must be a valid solution

of type TS_SOLTYPE_USR.

solution.name Required. Internal, unchangeable solution name. Required, no more than 25

characters.

solution.description Optional, up to 80 characters.

solution.prefix 0-2 alphanumeric characters. The required first prefix character, ‘U’, is prepended

for you; do not include it.

solution.imagea Ignored. Set to internal default.

solution.type Ignored. Set internally to TS_SOLTYPE_USR.

solution.displayname Display name. Required, no more than 25 characters.

optionalFields 0 indicates that you do not want any of the optional system fields created initially.

Set argument to INT_MAX to have all optional system fields created initially.

Optional system fields can still be added subsequently.

reserved Ignored. Reserved for future use.

int AddTablesFromXML(const char* sXML, const char* sIconDir, bool bParseOnly = false)

- Add one or more SBMtables from an XML definition. Currently, the sIconDir only specifies the

directory to find the workflow.ico file for an added solution. Passing true for bParseOnly will send the

XML through the parser/validator, but no changes to the database will be made. Requires the "Remote

Administration" system privilege and the "Add Tables” and “Add Fields” administration privileges.

int AddWorkflowFromXML( const char* sXML, int nTable, int nParentWorkflow = 0, int nParentProject

= 0, bool bParseOnly = false )

- Add an SBM workflow (and projects) from an XML definition. Pass in the XML definition, table id,

parent workflow id, and parent project id. If 0 is passed for the workflow, it is assumed that the parent

workflow is the base workflow. Likewise, if 0 is passed for the project, it is assumed that the parent

project is the base project. Passed XML must comply with published XML schema. Passing true for

bParseOnly will send the XML through the parser/validator, but no changes to the database will be

80

made. Requires at least the "Remote Administration" system privilege and the "Add Workfow"

administration privilege. Additionally, you will need all the administration privileges necessary to

effect the changes specified in the XML. For example, if you are adding one or more projects, you will

need the "Add Project" administration privilege. If you are adding fields, you will need the “Add

Fields” administration privilege, and so on.

int BuildFieldList( int tableId, TSFieldList& fieldList )

- Builds the list of fields from GetSchema for the table passed into the method. Deprecated method--use

the GetSchema method instead.

int ClearAlternateUser()

- Clears the alternate user, reverting to the logged in API user. Called to undo SetAlternateUser. This

call will also check back in a license if SetAlternateUser checks one out.

int Connect( const char* userName, const char* password, const char* serverAddress )

- Connects the application to a Web server running SBM and logs you in.

int ConnectNTCR( const char* serverAddress )

- Connects the application to an SBM server using NT Challenge/Response as your authentication

mechanism. NOTE: This function is only available with the WinInet versions of the API.

int ConnectSSO( const char* ssoToken, const char* serverAddress )

- Connects the application to a web server running SBM and logs you in using the provided unencoded

SSO token.

int CreateIndex( int tableId, TSList* columnNames, const char* indexName )

- Use to create an index on the specified table in the SBM database.

int DeleteIndex( int tableId, const char* indexName )

- Use for deleting a named index on the specified table in the SBM database.

int DeleteRecord( int tableId, int id )

- Use for deleting a singular record (row) from a table.

int Disconnect()

- Use for disconnecting from SBM. If you are a concurrent user, this logs you out from your concurrent

license use.

int ExecuteSQL( TSString& sql )

- Execute a SQL statement directly against the database. The SQL must be that which does not return a

result set such as UPDATE.

int GetConnectionInfo( char** dsn, char** databaseName, char** serverName )

- [Deprecated and will not work if linked with WinInet. Use second alternate signature below.]

int GetConnectionInfo( char* dsn, char* databaseName, char* serverName )

- [Not recommended because caller must ensure that their char* arguments point to buffers of sufficient

size to receive whatever string that have been defined in their organization. Use signature below.]

int GetConnectionInfo( TSString& dsn, TSString& databaseName, TSString& serverName )

- The results from a call to GetConnectionInfo will vary greatly depending on your DBMS. The output

of this method is determined by ODBC calls to the DBMS. Specifically, the database name is a result

of the call SQLGetInfo() with the fInfoType parameter set to SQL_DATABASE_NAME. The server

name is a result of the call SQLGetPrivateProfileString() with the lpszEntry parameter set to "Server".

For more information on how your DBMS treats these calls, see Microsoft's ODBC documentation.

81

int GetDbInfo( int infoType, void* out )

- Use to obtain database information, some from SBM and some directly from the DBMS via ODBC

calls. In the latter case, refer to your ODBC documentation for further details.

- If out is a int*, the possible values for infoType and the results are as follows.

- TS_DBINFO_VERSION: Returns TS_SYSTEMINFO.TS_DBVER. This is the upgrade version of the

SBM database and might be less than the build number. The first two digits represent the SBM release

number and must match the first two digits of the build number. The three least significant digits

represent the most recent build where upgrade logic was added. For example, if you are running build

57018, you have TeamTrack 5.7, build 18. If the DBVER is 57009, then build 9 was the last build to

which Micro Focus added upgrade logic. Later internal builds prior to release did not require any

structural changes or data transformations and so the number was not incremented.

- TS_DBINFO_ROOTPROJECTID: Returns the TS_ID of the root project.

- TS_DBINFO_ROOTFOLDERID: Returns the TS_ID of the root folder.

- TS_DBINFO_OBJECTVERSION: Returns the last build number at which schema changes were

made. This is the mechanism by which the API client and the SBM server negotiate the internal

structure of database objects as sent between the client and the server; and so that it is not necessary to

recompile API client programs whenever database structure changes are made.

- TS_DBINFO_DBMSVER: Invokes ODBC SQLGetInfo( SQL_DBMS_VER ) function, parses off the

major version number, and returns that as an integer.

- TS_DBINFO_VARCHARLENGTH: Invokes ODBC SQLGetTypeInfo( SQL_VARCHAR ) function.

- TS_DBINFO_LONGVARCHARLENGTH: Returns the maximum length of a memo field in the SBM

database, a limit imposed by the DBMS. If you are using Oracle with the Microsoft ODBC driver, the

value returned by ODBC is incorrect (will tell you 4000 even if the client software only handles 2000).

In this case we rely upon the "OracleVARCHAR4000" value in the TS_SYSTEMSETTINGS table to

be correctly set. If using Oracle with the Oracle ODBC driver then you will get correct results in any

case.

- TS_DBINFO_ALLOWANONYMOUS: Returns 1 if the database is configured to allow anonymous

access.

- TS_DBINFO_LITECOMPATIBLE: (Deprecated.) Returns 1 if the database is compatible with

TeamTrack Workgroup.

- If out is a TSString*, the possible values for infoType and the results are as follows.

- TS_DBINFO_EXITURL: Returns TS_SYSTEMINFO.TS_EXITURL.

- TS_DBINFO_ROOTPROJECTNAME: Returns the TS_NAME of the root project.

- TS_DBINFO_DBMSNAME: Invokes ODBC SQLGetInfo( SQL_DBMS_NAME ) function.

- TS_DBINFO_DBMSVER_FULL: Invokes ODBC SQLGetInfo( SQL_DBMS_VER ) function.

- TS_DBINFO_HARDWAREID: Returns the 10 character SBM hardware identifier for the machine

that the server is running on. This is the same 10 character identifier that is displayed on the License

Options dialog box in the SBM System Administrator.

int GetDllWebAddress()

- Obtains the server name/directory name/dll name for the server.

int GetIdentity( const TSString& sql, int& out )

- Use to obtain the value of a SQL_INTEGER column from a table. The sql must be that which returns a

result set consisting of a single integer value. For example: “select TS_FIELDSMASK from

TS_USERS where TS_ID = 4”.

int GetIdentityString( const TSString& sql, TSString& out )

- Use to obtain the value of a SQL_CHAR, SQL_VARCHAR, or SQL_LONGVARCHAR column from

a table. The sql must be that which returns a result set consisting of a single character value. For

example: “select TS_LOGINID from TS_USERS where TS_ID = 4”.

82

int GetInt( int tableId, const char* columnName, int recId, int* result )

- Use to obtain the value of a numeric column from a table. Note: column name must be lower case

without the TS_. The only columns available are the ones not found in the FIELDS table, unless

calling the method against the FIELDS table.

const char* GetLastErrorMessage()

- Displays the error message for the last operation that failed.

int GetPrivilegeName( enum privId_e privId, char** privName )

- Deprecated. Will fail if the API is linked with WinInet. Use alternate signature below.

int GetPrivilegeName( enum privId_e privId, TSString& privName, int tableId = 0 )

- Use to obtain the name of a privilege as displayed in ttAdmin using the privilege id enumeration

defined in TSDef.h. If tableId is supplied and override section labels or report levels have been defined

for that table, then the privilege name will include the override text.

int GetProjectList( int nTableId, int nProjectsMask, TSProjectList& projectList )

- Gets a list of objects of type TSProject to which the logged-in user has privileges. nProjectsMask

determines on which privileges to filter, e.g. return only the projects the user can view. Possible values

for nProjectsMask are: TS_PROJMASK_VIEW = 0x0001, TS_PROJMASK_UPDATE = 0x0002,

TS_PROJMASK_SUBMIT = 0x0004, TS_PROJMASK_TRANSITION = 0x0008, and

TS_PROJMASK_ALL = 0x000F. Requires a round trip to the server. Complete results require that the

API user have all necessary project submit, view, update or transition privileges; depending on the

value of the nProjectsMask parameter.

TSSchema* GetSchema( int tableId )

- Use to get the fields for a given table.

int GetString( int tableId, const char* columnName, int recId, char** result )

- Deprecated. Will fail if the API is linked with WinInet. Use alternate signature below.

int GetString( int tableId, const char* columnName, int recId, char* result, int size )

- Use to obtain the value of a char/string column from a table. Note: column name must be lower case

without the TS_. The only columns available are the ones not found in the TS_FIELDS table, unless

calling the method against the TS_FIELDS table.

int GetSubmitTransition( int projectId, int* id )

- Use to obtain the id value for the default submit transition. If a browser-visible submit exists, it is

given preference. If not, then the first hidden submit transition found is returned.

int GetSubmitTransitions(( int nProjectId, TSRecordList* list, bool bIncludeHidden = true )

- The TSRecordList will be filled in with a TSRecord for each enabled submit transitions for the project.

If the TSRecordList already had elements, they will be emptied and destroyed before the list is filled

with new elements. If bIncludeHidden is true, then the list will contain submit transitions with the

TS_TRANS_FLG_TRIGGER flag set ('No Button On Form'). If false, then only the default browser-

enabled submit transition is returned. Returns TS_OK on success.

- If there are no valid, enabled submit transitions for the project, return an empty list and TS_OK

int GetTableIdByDatabaseNameEx( const char* tableDbName, int* tableId )

- Use to obtain the id value of the table. TS_TBLID_<dbname> int definitions are not reliable for

primary and auxiliary tables.

int HasAccess( const char* szPrefix, const char* szLogin, bool& bHasAccess )

- Determines if access is available to the enabler of the specified prefix. For enabled product licenses

where the number of seats is always 0, e.g., Issues (TTT) and Incidents (TTS), the user (szLogin) is

83

ignored, meaning simply the product is enabled. For enabled product licenses where the number of

seats is a set amount, i.e. other than 0, the user (szLogin) is used to determine if the particular user has

access to the specific integration, e.g. Test Bridge (TTB) or Project Bridge (TPB).

int HasGroupPrivilege( int groupId, int itemId, enum privId_e privId )

- Determines if the Group has the specified privilege.

int HasPrivilege( int userId, int projectId, int maskNumber, int mask )

- Determine a user’s privileges within a Project. The userid parameter is the TS_ID value for the user

record from the TS_USERS table. Note: method is only supported for backward compatibility. Use

HasGroupPrivilege or HasProjectPrivilege methods.

int HasRecordPrivilege( enum recPriv_e recPriv, int userId, int tableId, int recId )

- Determines if the User has the specified privilege for the requested record.

int HasUserPrivilege( int userId, int itemId, enum privId_e privId )

- Determines if the User has the specified privilege.

int HasValidLicense( const char* solutionIdent )

- Determines if the database has a license for the solution as identified by its prefix.

int MoveFolder( int folderId, int newParentId, int position )

- Use to move a folder to a different place in the hierarchy. Valid values for the position parameter are:

TS_CHILD, TS_PRIOR_SIBLING and TS_NEXT_SIBLING.

int MoveProject( int projectId, int newParentId, int position )

- Use to move a project to a different place in the hierarchy. Valid values for the position parameter are:

TS_CHILD, TS_PRIOR_SIBLING and TS_NEXT_SIBLING.

int PutFile( TSString sFileName, TSString sSourcePath, TSString sDestinationPath, int nType, bool

bUpdateBlob, int& nResourceId )

- Use it so to create TS_RESOURCE and TS_BLOB records or update existing TS_BLOB records. The

sFileName is the name of the file you wish to comvert to a TS_RESOURCE and TS_BLOB, ie.

Myicon.ico. The sSourcePath is the location of the file, ie. D:\SBM Files\Icons. The sDestinationPath

kind of tricky. This consists of the subdirectory structure where you store the files on the SBM Server

machine. Some resource types are all stored in subdirectories and some are not. The nType is a

numeric value that represents the different resources. The bUpdateBlob is used when

TS_RESOURCES and TS_BLOBS already exist. If set to true the existing TS_BLOB record will be

updated with the contents of the new file. The nResourceId is the value of the newly created or current

TS_RESOURCE record.

TYPE nType Value Base Destination Path

Templates TS_RESTYPE_TEMPLATE(1)

CSS Styles TS_RESTYPE_STYLE(2)

Images TS_RESTYPE_IMAGE(3) images

Attachments TS_RESTYPE_ATTACHMENT(4)

Java TS_RESTYPE_JAVA(5) java

Help TS_RESTYPE_HELP(6) help

E-mail Notification TS_RESTYPE_NOTIFICATION_TEMPLATE(7)

E-mail MailClient TS_RESTYPE_MAIL_CLIENT_TEMPLATE(8)

E-mail

SelfRegistration

TS_RESTYPE_SELF_REG_TEMPLATE(9)

SpellCheck Dictionary TS_RESTYPE_DICTIONARY(10)

84

E-mail Browser TS_RESTYPE_USER_EMAIL_TEMPLATE(11)

int ReadBlob(int nBlobId, int* nBlobLength, char** pBlobData )

- Reads and returns the data and data length of the data associated with a record in the TS_BLOBS table.

int ReadAllRecords( TSRecordList* list, int tableId )

- Read all the records for the requested table into a list object. For tables that are recursive the returned

list is a TSTreeList.

int ReadAttachmentList( TSRecordList* list, int tableId, int recId )

- Use to obtain a list of attachments for a specified primary or auxiliary table record, such as an Issue,

Incident, Company, etc.

int ReadAvailableTransitionList( TSRecordList* list, int tableId, int recId )

- Use to obtain a list of available transitions for a given record of the specified primary or auxiliary

table. Will check one or more of the following privileges: "Transition All Items", "Transition Item if

Owner", "Transition Item if Submitter" and "Submit New Items".

int ReadChangeList( TSRecordList* list, int caseId, BOOL newFirst /*=FALSE*/ )

- Returns all the change history for an issue in the Cases table. Note: method is only supported for

backward compatibility. Use ReadChangeList2.

int ReadChangeList2( TSRecordList* list, int tableId, int itemId, BOOL newFirst /*=FALSE*/ )

- Use to read all the change history for a record of the specified primary or auxiliary table.

int ReadDynaListWithWhere( TSDynaRecordList* list, int tableId, const TSStringList& columns,

LPCTSTR whereclause = “” )

- Reads a dynamic SQL query from the database. All columns are associated with the tableId passed in,

and are specified in a TSStringList. The where clause is optional and is used to filter the query results.

Note that the the where clause does not need the word “WHERE”.

int ReadDynaListWithWhere( TSDynaRecordList* list, TSDynaColumnList& columns, LPCTSTR

whereclause = “” )

- Reads a dynamic SQL query from the database. Each TSDynaColumn in the list provided will be read

from the database. If any two columns are from different tables, a where clause is required to join the

data. Also, any table used in the join will need to have a column of data requested in the results or the

table will be neglected when SBM creates the “FROM” clause. If all columns are table homogenous,

the where clause is optional. Note that the the where clause does not need the word “WHERE”.

int ReadFieldsByProject( TSRecordList* list, int projectId )

- Obtain a list of default fields for a specified project, excluding those that are deleted or not used.

int ReadFieldsByProjectTransition( TSRecordList* list, int projectId, int transitionId )

- Obtain a list of default fields for a specified transition based on a specified project, excluding those that

are deleted or not used.

int ReadFieldsByWorkflow( TSRecordList* list, int workflowId )

- Obtain a list of default fields for a specified workflow, excluding those that are deleted or not used.

int ReadFieldsByWorkflowTransition ( TSRecordList* list, int workflowId, int transitionId )

- Obtain a list of default fields for a specified transition based on a specified workflow, excluding those

that are deleted or not used.

85

int ReadFolderItems( TSRecordList* list, int folderId )

- Use to obtain a list of links in a given folder.

int ReadFolderList( TSRecordList* list, int owner, int parentId )

- Use to obtain a list of folders given the owner’s user id and the parent folder id. The returned list is a

TSTreeList of folders which are children, grandchildren, etc. of the specified parent.

int ReadProjectSelectionList( TSRecordList* list, int selectId )

- Use to obtain a list of which projects use a given selection. Obtains records from the

TS_ProjectSelections table for the passed selectid value.

int ReadProjectTransitionList( TSRecordList* list, int transId )

- Use to obtain a list of which projects use a given transition. Obtains records from the

TS_ProjectTransitions table for the passed transId value. The transId parameter is the TS_ID value for

the transition record from the TS_TRANSITIONS table.

int ReadPropertyList( TSRecordList* list, int transId )

- Use to obtain a list of field properties that have been defined for a given transition. Obtains records

from the TS_Properties table for the passed transId value.

int ReadRecord( TSRecord* rec, int id )

- Use to obtain a specific record from a table. The record object should be instantiated using the

constructor method which initializes the object for a specific table, in order to build the TSRecord with

the appropriate fields for that table. For example, TSRecord::TSRecord( int tableId, TSServer* server,

int fieldtype /*=0*/ ).

int ReadRecord( TSRecord* rec, int id, const std::vector< TSString >& fieldNames )

- As above, but returns only the schema fields and the specified (by database name) user-defined fields.

int ReadRecordByItemNumber( TSRecord* pRec, TSString sItemNumber, int nProjectId )

- Use to search for a given record by its item id value within the project specified. The TSRecord object

argument should be instantiated using the TSRecord constructor method which initializes the object for

a specific table, in order to build the TSRecord with the appropriate fields for that table, i.e.

TSRecord::TSRecord( int tableId, TSServer* server, int fieldtype /*=0*/ )

int ReadRecordForId( TSRecord* record, const char* searchId )

- Use to search for a given record by its id value. The TSRecord object argument should be instantiated

using the TSRecord constructor method which initializes the object for a specific table, in order to

build the TSRecord with the appropriate fields for that table: TSRecord::TSRecord( int tableId,

TSServer* server, int fieldtype /*=0*/ ). Note: This method will always return the single record in the

TS_SYSTEMINFO table regardless of searchId passed.

int ReadRecordListWithWhere( TSRecordList* list, int tableId, const char* whereClause )

- Use to filter a list of records based on the conditions passed; note that the whereClause does not need

the word ‘WHERE’. For example: ‘TS_COMPANYID = 5’. The table and column names are case-

sensitive and must match exactly what is in the database. SBM tables and columns are always

UPPERCASE. CAUTION, this version should only be used to return a small number of records.

Otherwise, use the iterator version below with maxRecords set to a small number (<50).

int ReadRecordListWithWhere( TSRecordList* recordList, int tableId, const char* whereClause, const

std::vector< int >& fields )

- Similar to ReadRecordListWithWhere [1]. The vector is populated with the TS_ID numbers of the

desired user defined fields, i.e. the fields in the TS_FIELDS table (if any), for the record type passed.

This method returns a record list, filtering by the where clause, returning the schema fields, i.e. fields

86

that will always be in the database for the record type passed, and the desired fields listed in the vector

from the TS_FIELDS table.

int ReadRecordListWithWhere( TSRecordList* list, int tableId, int firstId, int maxRecords, const char*

whereClause )

- Similar to ReadRecordListWithWhere [1]. Can be used iteratively to read a list, limiting the number of

records returned by each call. This can be used to read very large lists while conserving memory

resources. The list will always be ordered by TS_ID (order by clause is appended internally to this

method and should not be included by the caller). Typically in the first call, firstId is set to 0 and

maxRecords is set to the maximum number of records you want to receive at one time. After receiving

the results, you would obtain the id of the last item on the list and pass this value + 1 as the firstId

argument in subsequent calls. When the list count is less than maxRecords, you have obtained the last

set of records in the query.

int ReadRecordListWithWhere( TSRecordList* recordList, int tableId, int firstId, int maxRecords, const

char* whereClause, const std::vector< int >& fields )

- Combines the behavior of ReadRecordListWithWhere [3] with the field limiting capabilities of

ReadRecordListWithWhere [2].

int ReadRecordWithWhere( TSRecord* record, const char* whereClause )

- Reads a record, filtering by the where clause and returning only the desired fields; note that the

whereClause does not need the word ‘WHERE’. For example: ‘TS_ID = 5’. The table and column

names are case-sensitive and must match exactly what is in the database. SBM tables and columns are

always UPPERCASE.

int ReadRecordWithWhere( TSRecord* record, const char* whereClause, const std::vector<int>& fields)

- Similar to the other ReadRecordWithWhere. The vector is populated with the TS_ID numbers of the

desired user defined fields, i.e. the fields in the TS_FIELDS table (if any), for the record type passed.

This method returns a record, filtering by the where clause, returning the schema fields, i.e. fields that

will always be in the database for the record type passed, and the desired fields listed in the vector

from the TS_FIELDS table.

int ReadReport( TSRecord* report, const char* name )

- Use to find a report by name.

int ReadReportList( TSRecordList* list, long userId, int perm )

- Use to obtain a list of reports available to a given user based on general permissions. The userid

parameter is the TS_ID value for the user record from the TS_USERS table. The perm parameter is

one of the four values found in TSDef.h: TS_RPTPERM_CREATE, TS_RPTPERM_EXEC,

TS_RPTPERM_EDIT, and TS_RPTPERM_DEL. Depending on the value of the perm parameter, the

“<perm> User-Level Reports”, “<perm> Guest-Level Reports”, “<perm> Manager-Level Reports”,

and “Manage Private Reports” privileges will be required.

int ReadSelectionList( TSRecordList* list, int fieldId, int projectId )

- Use to obtain a list of selections defined for a given field and available for a given project. Note that

the list includes both enabled and disabled selections. Disabled selections will have the disabled

member set to 1.

int ReadStateList( TSRecordList* list, int projectId, BOOL incParent /*=FALSE*/ )

- Use to obtain a list of states defined for a given project. If incParent is FALSE, then only the states

defined at the state’s immediate workflow are returned. If TRUE, then states inherited from parent

workflows are also included.

87

int ReadTransitionList( TSRecordList* list, int projectId )

- Use to obtain a list of transitions that are available for a given project. Note that project ids apply only

to primary items. Use ReadAvailableTransitionList for transitions of auxiliary items.

int ReadUserDefinedFields( TSRecordList* list, int tableId )

- Use to obtain a list of the user-defined fields in a given table.

int ReadUserSelectionList( TSRecordList* list, int fieldId, int projectId, BOOL incDeleted = FALSE )

- Use to obtain a list of selections defined for a given USER/MULTI-USER field and available for a

given project. Note that the list does not include the deleted selections by default. To include the

deleted selections, call the method with 'incDeleted' as TRUE.

int ReadVCActions( TSRecordList* list, int caseId )

- Use to obtain a list of the version control activity for a given issue. The caseId parameter is the TS_ID

value for the issue record from the TS_CASES table.

int ReadVCActionsForModule( TSRecordList* list, const char* filename, int userid, int action2 )

- Use to obtain a list of Version Control activity for a given user. The filename parameter must include

the path of the file. For example: “D:\Program Files\SBM\API\Samples\Submit\Submit.cpp”

- In addition, the userid parameter is the TS_ID value for the user record from the TS_USERS table, not

the loginid for the user. Action2 defaults to 0. This will return a record from the TS_VCACTIONS

table if the file in question is still checked out. If subsequent action has been take, i.e. the file has been

either checked in or the checkout undone, you will need to pass either 2 or 3, respectively. In order to

view file history for multiple users, it would be more effectively to use the ReadAllRecords function

call.

int ReceiveTSItem ( TSSocket* socket, TSItem& item )

- Receives a TSItem off of the socket.

int RefreshCache( const int tableId )

- Refresh the server cache for the specified table. Requires a round trip to the server.

int ReleaseRecordLockById( int nTableId, int nItemId )

- Unlocks the previously locked record. Use this either after the item has been updated or to cancel out

of a change. Requires a round trip to the server.

int ReleaseRecordLockByNumber( int nProjectId, int nItemNumber )

- Unlocks the previously locked record. Use this either after the item has been updated or to cancel out

of a change. Requires a round trip to the server.

int SetAlternateUser( TSString sLoginId, TSString sPassword, bool bValidatePwd )

- This method sets sLoginId as the alternate user. If bValidatePwd is true, sPassword must contain the

password for the alternate user and validation will occur. Requires a round trip to the server. Requires

the "Logon as Another User" privilege. Starting with 7.1 this call will checkout a license against the

alternate user. A license will only be checked out if the alternate user does not currently have a license

checked out. The license will be checked back in with the call to ClearAlternateUser. This only

happens if the license was originally checked out with the SetAlternateUser call.

int SetExitUrl( const char* exiturl )

- Use to modify the Exit URL. The complete URL must be passed in, e.g. http://www.microfocus.com.

int SetGroupPrivilege( int groupId, int itemId, privId_e privid, bool bGrant = true )

- Grant or revoke a privilege. The itemId argument is ignored for system privileges. Otherwise is the id

of the project, workflow, or table to which the privilege applies.

88

int SetUserPrivilege( int userId, int itemId, privId_e privid, bool bGrant = true )

- Grant or revoke a privilege. The itemId argument is ignored for system privileges. Otherwise is the id

of the project, workflow, or table to which the privilege applies.

int SetRecordLockById( int nTableId, int nItemId, bool bStealLockFlag = false )

- Locks the specified record (ts_id) for the time period set by the administrator.

- If bStealLockFlag is true, then if the record is locked by another user, that lock will be broken so that

this method calls will always succeed.

int SetRecordLockById( int nTableId, int nItemId, int& nLockId, bool bStealLockFlag = false )

- Identical to above with the addition of the output variable, nLockId, which will be set to the ts_id of the

record in the TS_RECORDSLOCKS table comprising the lock.

int SetRecordLockByNumber( int nProjectId, int nItemNumber, bool bStealLockFlag = false )

- Locks the specified record (e.g. Issue ID) for the time period set by the administrator.

- If bStealLockFlag is true, then if the record is locked by another user, that lock will be broken so that

this method calls will always succeed.

int SetRecordLockByNumber( int nProjectId, int nItemNumber, bool bStealLockFlag = false )

- Identical to above with the addition of the output variable, nLockId, which will be set to the ts_id of the

record in the TS_RECORDSLOCKS table comprising the lock.

int Submit( int* nIssueId, TSString& sLoginid, TSRecord* pRec, int nTableId, int nProjectId, int

nFolderId, int nType )

- This method is deprecated. Uses one of the last two submit methods.

int Submit( int* nIssueId, TSString& sLoginid, TSRecord* pRec, int nTableId, int nProjectId, int

nFolderId = 0 )

- This method is deprecated. Uses one of the following two submit methods.

int Submit( int* nId, int* nIssueId, TSString& sLoginid, TSRecord* pRec, int nTableId, int nProjectId, int

nFolderId = 0, int nTransitionId = 0 )

- Used to submit a primary or auxiliary item into the database. For adding other records: Fields, Projects,

etc., use AddRecord. Requires the "Submit New Items" privilege, and depending on how the workflow

and project fields are defined, could require any or all of the “View <section_name> Fields on Submit”

and “Update <section_name> Fields” privileges. It is also required that the owner of the submitted

item have the "Own Items" privilege and one of the applicable “View Item” privileges.

- This version of submit returns both the nIssueId (item id shown in the browser) and the nId (ts_id in

the database). The item will be added to all folders referenced by existing folder fields. If nFolderId

references a unique folder, it will be added to that folder as well.

- By default, the browser-enabled submit transition will be used. If only hidden submit(s) exist, then the

first hidden submit transition is used. Otherwise. you can specify precisely which submit transition to

use by pass a value for nTransitionId. It must be a valid submit transition for the project.

int Submit( int* nId, TSString& sLoginid, TSRecord* pRec, int nProjectId, const std::vector< TSString

>& fieldNames, int nFolderId = 0, int nTransitionId = 0 )

- Used to submit a primary item into the database using only the fields specified (by database name).

This version of submit returns the nId (ts_id in the database). Refer to the previos Submit overload for

privilege requirements and explanation of the remaining parameters.

89

int Transition( TSString &sLoginid, TSRecord *pRec, int nProjectId, int nTableId, int nRecordId, int

nTransition, int nSubmitProjectId = 0, int nSubmitTableId = 0, int nSubmitTransitionId = 0, TSRecord*

pSubmitRec = NULL )

- Used to transition a record of the specified primary table to another state in the workflow, or to update

an auxiliary table record. When an auxiliary table is specified, nProjectId should be zero. Requires an

appropriate “Transition” privilege. If this is a Copy, Subtask, or Post type transition then the "Submit

New Items" privilege is required. Depending on how the workflow and project fields are defined, as

well as the transition type, it could require any or all of the “View <section_name> Fields on

Transition” and “Update <section_name> Fields” privileges. It is also required that the owner of the

transitioned item have the "Own Items" privilege and one of the applicable “View Item” privileges.

- If this is a Post Item, Publish Problem or Subtask type transition and the last four parameters are not

supplied, then a posted item is submitted using the standard submit transition. The post submit will fail

if there are required fields that do not have default values. If the transition specifies a destination table

(and project, if a primary table), then that destination is used. If the posted item is a primary item and

the transition's post item project is defined as 'Query At Runtime', then the project of the initiating item

is used since query at runtime cannot work through the API. You can specify an alternate submit

transition in nSubmitTransitionId that could have default values set for any required fields.

- If this is a Post Item, Publish Problem or Subtask type transition and the last four parameters are

supplied, then these values override the transition definition. This allows the API to choose a different

table (primary or auxiliary), project (if primary table), and submit transition (optional) to submit the

post item or subtask into. You can also override default values and/or supply values for required

submit fields by populating pSubmitRec. If nSubmitTableId is non-zero then pSubmitRec must not be

NULL and vice versa. If nSubmitTableId refers to a primary table, then nSubmitProjectId must be

supplied and be a valid project in that table.

int Transition( TSString& sLoginid, TSRecord* pRec, int nRecordId, int nProjectId, int nTransitionId,

const std::vector< TSString >& fieldNames, int nSubmitProjectId = 0, int nSubmitTableId = 0, TSRecord*

pSubmitRec = NULL )

- Similar to above, but using only the fields specified. If a field is required and is not sent, the transition

will fail unless there is a default or auto value.

- The table id is obtained from pRec. TSRecord's bGetExtendedData is ignored.

int TSAuxiliaryItemCancelUpdate( TSAuxiliaryItem& auxItem )

- The TSAuxiliaryItemCancelUpdate method clears the lock on this record. It is for use after a call to

TSAuxiliaryItemStartUpdate, but when TSAuxiliaryItemFinishUpdate will not be called. This method

is called from the CancelUpdate method of TSAuxiliaryItem.

int TSAuxiliaryItemFinishUpdate( TSAuxiliaryItem& auxItem, bool bStealLockFlag = false, bool

bPopulateItem = false )

- The TSAuxiliaryItemFinishUpdate method is used to update the item in the database after field values

in the field list (obtained from TSAuxiliaryItemStartUpdate) have been set. This method will only send

fields that have been modified back to the server. After a successful database update, the lock (if it

exists) will be removed. This method can return TS_LOCK_UNAVAILABLE if the lock has expired

and another user has taken the lock. This method is called from the FinishUpdate method of

TSAuxiliaryItem. Required privileges are "View" and “Update” for the table in which the auxiliary

item resides.

int TSAuxiliaryItemRead( TSAuxiliaryItem& auxItem )

- The TSAuxiliaryItemRead method will populate the item as specified by the section mask, taking into

consideration the privileges of user (or alternate user if set) and ordering fields as they would be when

viewed in the browser. The table and item ids must already be set (or TS_INVALID_PARAMETERS

will be returned), such as by constructing this class with the nTableId parameter and then calling the

ReadById method of the base class. This method is called from the Read method of TSAuxiliaryItem.

Requires the "View" privilege plus any attachments or notes privileges for the table in which the

auxiliary item resides.

90

int TSAuxiliaryItemStartUpdate( TSAuxiliaryItem& auxItem, bool bLockFlag = true )

- The TSAuxiliaryItemStartUpdate method should be used to fill in this item as appropriate for an

update. Populates the item and orders fields, as they would be for an update, including filling out field

selection lists. The three other member lists of a TSItem, changeList, attachmentList and linkList, will

not be updated. The bLockFlag is defaulted to lock this record. Note that while the record is locked,

any other user (via API or browser interface) will receive an error (TS_LOCK_UNAVAILABLE for

API) if they attempt to update the same record. The SBM administrator sets the time a lock is held.

The table id and item id must be preset. This method is called from the StartUpdate method of

TSAuxiliaryItem. Required privileges are "View" and “Update” for the table in which the auxiliary

item resides.

void TSGetFullSelectionListForROFields( bool bGetFullSelectionListForROFields )

- Set or clear the client-side state variable that determines whether or not to read the full list of selections

for all selection-type fields, even if the field is read-only. By default, this is true, to preserve the

behavior of older API revisions. If it is set to false, read-only fields will only list the selection values

that are actually selected. Setting this to false can improve performance if unselected values in read-

only selection fields are not used by the client program. This applies to selection fields and all similar

fields, such as user fields, relational fields, multi-selection fields, etc. The setting can be changed at

any time and will remain in effect for any subsequent calls to TSAuxiliaryItemStartUpdate,

TSPrimaryItemStartTransition, TSItemStartSubmit, and TSPrimaryItemStartSubmit on this TSServer

object.

void TSIgnorePreferences( bool bIgnore )

- Set or clear the client-side state variable that determines whether or not user preferences should or

should not be ignored to possibly limit visibility of field sections and number of notes and change

history, or to return all data that privileges allow. Default = false = apply preferences. This optional

behavior will remain in effect for the life of the client application instance and applies only to the

following display methods: TSAuxiliaryItemStartUpdate, TSAuxiliaryItemFinishUpdate,

TSAuxiliaryItemRead, TSItemStartSubmit, TSItemFinishSubmit, TSPrimaryItemStartTransition ,

TSPrimaryItemFinishTransition, and TSPrimaryItemRead. The state can be changed at any time and

will apply to subsequent API method invocations.

int TSItemAddAttachment( TSItem& item, int nType, const TSString& sLabel, const TSString& sText,

int nTransitionId = 0, int* nAttachmentId = NULL, int nAccessType =


- The TSItemAddAttachment method adds an attachment ( TS_ATTACHATTRIB_NOTE - Note,

TS_ATTACHATTRIB_URL - URLs, or TS_ATTACHATTRIB_FILE - Files) to the TSItem. The

sText argument refers to the full path to the file that will be read – for files, for notes: the note content,

or for URLs: the complete URL. This method is called from the AddAttachment method of TSItem.

Requires at least one of the “Add Attachments <qualifier>” privileges, depending on the API user’s

relationship to the item.

int TSItemAddItemLink( TSItem& item, int nDestTableId, int nDestItemId, int nLinkType, int

DestProjectId, int DestItemNumber, int nTransitionId = 0, int nAccessType =


- The TSItemAddItemLink method adds an item link to this TSItem. Either the table and item id, or the

project id and item number should be set before using. The nLinkType argument is a bit flag argument

with bit values defined as: TS_STORE_ACTION_TWOWAYLINK = 0x0100,

TS_STORE_ACTION_SOURCETRIGGER = 0x0200, and TS_STORE_ACTION_DESTTRIGGER

= 0x0400. This method is called from the AddItemLink method of TSItem. Requires at least one of the

“Add Attachments <qualifier>” privileges, depending on the API user’s relationship to the item. If

TS_STORE_ACTION_TWOWAYLINK is requested, privilege(s) are required for the linked item as

well.

91

int TSItemDeleteAttachment( int nAttachmentId, bool bDeleteBothSides = true )

- The TSItemDeleteAttachment method deletes the attachment from this item and from the attachment

list. This method is called from DeleteAttachment method of TSItem. Requires at least one of the

“Delete Attachments <qualifier>” privileges, depending on the API user’s relationship to the item.

int TSItemFinishSubmit( TSItem& item, int& nItemNumber, bool bPopulateItem = false )

- The TSItemFinishSubmit method is used to add the item to the database after field values in the field

list (obtained from StartSubmit) have been set. This method will only send fields that have been

modified back to the server. This method is called from FinishSubmit method of TSItem. For primary

table items this method requires the “Submit New Items” privilege. The assigned owner must have the

“Own Items” privilege, one or more “View <qualifier>” privilege, plus any “View <section_name>

Fields on Submit” and “Update <section_name> Fields” privileges containing required fields. For

auxiliary items this method requires the “Submit” and “View” privileges for the table into which the

auxiliary item is being submitted.

int TSItemStartSubmit ( TSItem& item, int nTransitionId = 0, const TSString& sTransitionName =

TSString() )

- The TSItemStartSubmit method should be used to fill in this item appropriately for a submit.

StartSubmit populates the item with defaults and orders fields as they would be for a submit, including

filling out field selection lists. The other three member lists of a TSItem: changeList, attachmentList

and linkList, will be emptied. The table id must be preset. This method is called from the StartSubmit

method of TSItem.

- For primary table items this method requires the “Submit New Items” privilege. The assigned owner

must have the “Own Items” privilege, one or more “View <qualifier>” privilege, plus any “View

<section_name> Fields on Submit” and “Update <section_name> Fields” privileges containing

required fields. For auxiliary items this method requires the “Submit” and “View” privileges for the

table into which the auxiliary item is being submitted.

- If neither of the optional argument are supplied, then the browser-enabled default submit transition is

used. Alternately, you can supply a valid hidden submit transition defined for the project. This can be

done by the submit transition's item ID or display name (case-sensitive). If nTransitionId is > 0 then

that argument is used. If 0, and if sTransitionName is not empty, then that argument is used.

int TSItemUpdateAttachment( TSItem& item, TSAttachment& attachment, const TSString& sLabel,

const TSString& sText, int nAccessType = TS_ATTACHACCESS_DEFAULT )

- The TSItemUpdateAttachment method updates an existing attachment of the TSItem. The sText

argument refers to the full path to the file that will be read – for files, for notes: the note content, or for

URLs: the complete URL. This method is called from the UpdateAttachment method of TSItem.

Requires at least one of the “Update Attachments <qualifier>” privileges, depending on the API user’s

relationship to the item.

int TSPrimaryItemCancelTransition( TSPrimaryItem& primItem )

- The TSPrimaryItemCancelTransition method clears the lock on this record. It is for use after a call to

TSPrimaryItemStartTransition, but when TSPrimaryItemFinishTransition will not be called. This

method is called from the CancelTransition method of TSPrimaryItem.

int TSPrimaryItemFinishTransition( TSPrimaryItem& primItem, bool bStealLockFlag = false, bool

bPopulateItem = false )

- The TSPrimaryItemFinishTransition method is used to transition the item in the database after field

values in the field list (obtained from StartTransition) have been set. This method will only send fields

that have been modified back to the server. After a successful database update, the lock (if it exists)

will be removed. This method can return TS_LOCK_UNAVAILABLE if the lock has expired and

another user has taken the lock. This method is called from the FinishTransition method of

TSPrimaryItem.

- If this is a Post Item, Publish Problem or Subtask type transition, then a posted item is submitted using

the standard submit transition. The post submit will fail if there are required fields that do not have

92

default values. If the transition specifies a destination table (and project, if a primary table), then that

destination is used. If the posted item is a primary item and the transition's post item project is defined

as 'Query At Runtime', then the project of the initiating item is used since query at runtime cannot

work through the API.

- Requires one of the “Transition <qualifier>” privileges. Depending on how the workflow and project

fields are defined, as well as the transition type, it could require any or all of the “View

<section_name> Fields on Transition” and “Update <section_name> Fields” privileges. It is also

required that the owner of the transitioned item have the "Own Items" privilege and one of the

applicable “View Item” privileges. Also note that currently you cannot use

TSPrimaryItemStartTransition and TSPrimaryItemFinishTransition for any External Post transition or

for a Copy, Post or SubTask transition where the Post Item Project is ‘Select At Runtime’.

int TSPrimaryItemFinishTransition( TSPrimaryItem& primItem, bool bStealLockFlag = false, bool

bPopulateItem = false, TSItem& submitItem, bool bPopulateSubmitItem = false )

- Similar to above but intended for use with a Copy, Post Item, Publish Problem or Subtask type

transition only. If used with any other transition type, the additional arguments are ignored unless they

are invalid.

- submitItem must be either a TSPrimaryItem or a TSAuxiliaryItem object and StartTransition must have

already been called on that object or an error will be returned. You may call StartTransition with an

alternate, hidden submit transition if you wish. You must initialize submitItem with the table and

project into which you wish to submit the post item because these values override the table and project

ids defined for the originating transition.

- The post submit will fail if there are required fields that have not be explicitly filled in after

StartTransition or that do not have default values.

- It is possible for the originating transition to succeed and for the subsequent submit to fail due to

invalid fields or insuficcient submit privileges. This mimics browser behavior.

int TSPrimaryItemGetSubmitTransitions( TSPrimaryItem& primItem, std::list<TSTransition*>&

transList, bool bIncludeHidden = true )

- This method is called from the GetSubmitTransitions method of TSPrimaryItem.

int TSPrimaryItemGetTransitionList( TSPrimaryItem& primItem, std::list<TSTransition*>& transList )

- The TSPrimaryItemGetTransitionList method returns a list of TSTransition records in the results list

that indicate which transitions are valid for this item. Either the table id and item id, or the project id

and item number must be preset. This method is called from the GetTransitionList method of

TSPrimaryItem. Privileges required are: "Update All Items", "Delete Items", and "Transition All

Items".

int TSPrimaryItemRead( TSPrimaryItem& primItem )

- The TSPrimaryItemRead method works like the TSItem's Read, but also populates the m_nProjectId,

m_nItemNumber, m_nStateId, and m_sItemType members. This Read method will either read by table

id and item id, or if either are 0 and the project id and item number are set, it will read by project id and

item number. This method is called from the Read method of TSPrimaryItem. Depending on how the

workflow and project fields are defined, it could require any or all of the “View <section_name>

Fields” privileges and one of the applicable “View Item” privileges.

int TSPrimaryItemStartTransition( TSPrimaryItem& primItem, int nTransitionId, const TSString&

sTransitionName = TSString(), bool bLockFlag = true )

- The TSPrimaryItemStartTransition method should be used to fill in this item as appropriate for a

transition. The transition id and the transition name indicate which transition to use. Populates the item

and orders fields as they would be for the transition, including filling out field selection lists. The other

three member lists of a TSItem: changeList, attachmentList and linkList, will not be updated. This

method locks this record. Note that while the record is locked, any other user (via API or browser

interface) will receive an error (TS_LOCK_UNAVAILABLE for API) if they attempt to transition the

same record. The time a lock is held is set by the SBM administrator. Either the table id and item id or

93

the project id and item number must be preset. This method is called from the StartTransition method

of TSPrimaryItem. Requires one of the “Transition <qualifier>” privileges. Depending on how the

workflow and project fields are defined, as well as the transition type, it could require any or all of the

“View <section_name> Fields on Transition” and “Update <section_name> Fields” privileges. It is

also required that the owner of the transitioned item have the "Own Items" privilege and one of the

applicable “View Item” privileges.

int TSProjectRead( TSProject& proj )

- The TSProjectRead method will either read by table id and project id (m_nItemId in base class) or if

the project id is 0 and the full project name is not empty, it will read by full project name. The name,

and either the project id or full project name, will then be populated. This method is called from the

Read method of TSProject.

int TSRecordRefRead( TSRecordRef& recRef )

- The TSRecordRefRead method is called from the Read method of TSRecordRef. All appropriate data

members will be filled in. The table id and item id must be set prior to using this method. The method

will return TS_INVALID_PARAMETERS if either are not set. The base class method will only

populate m_sItemName.

int TSUserRead( TSUser& user )

- Called from TSUser::Read. Obtains a specified user record.

int TSUserAdd( TSUser& user, int nPersonalFoldersFlag, int nContactRecordFlag, const

std::vector<TSString>& groupNames, const std::vector<int>& groupIds )

- Called from TSUser::Add. Adds a user to the database.

- The nPersonalFoldersFlag is ignored by the server as of 2009 R1. User private folders are always

created.

int TSUserChangePassword( TSString& sPassword, int nUserId, const TSString& sLoginId = TSString()

)

- Called from TSUser::ChangePassword. Changes the password for a user.

int TSUserUpdate(TSUser& user, int nContactRecordFlag )

- Called from TSUser::Update. Updates a user and the associated contact record for a user.

int UpdateList( TSRecordList* list, int tableId, int recid1, int recid2 )

- Use to update a record in a given table. This method provides direct access to the database without

checking for read only fields, required fields, etc. To check field properties, call the Transition method

with the nTransition parameter set to Update. The columns in the database associated with recid1and

recid2 are as follows:

RecordType recid1 recid2

TS_MEMBERS TS_USERID TS_GROUPID

TS_PRIVILEGES TS_USERID TS_GROUPID

TS_SELECTIONS TS_FLDID (Not used)

TS_TRANSISSUETYPES TS_TRANSID (Not used)

TS_TRANSTRIGGERSTATES TS_STATEID (Not used)

TS_TRANSTRIGGERTRANSITIONS TS_TRANSITIONID (Not used)

TS_ADMINGROUPS TS_USERID TS_GROUPID

TS_ADMINTABLES TS_USERID TS_GROUPID

94

- Check the schema document for correct usage of the tables. You must lock the record before calling

this method if you are updating a list of primary items or auxiliary items. See SetRecordLockById() or

SetRecordLockByNumber().

- Note: Setting the TSRecord member variable recordState with SetNewRecordWithID is deprecated.

The record will not be updated.

int UpdateRecord( TSRecord* rec, TSRecord* newRecord /*=NULL*/ )

- Use to update a single record in a table (as opposed to updating a record in a list). You must lock the

record before calling this method if you are updating a primary item or auxiliary item. See

SetRecordLockById() or SetRecordLockByNumber().

- This method provides direct access to the database without checking for read only fields, required

fields, etc. To check field properties, call the Transition method with the nTransition parameter set to

Update.

- Caution: as of 5.0, calling this after reading the record using the ReadRecordWithWhere method using

a limited vector of selected fields, will update the record with 0 values in the fields not specified in the

vector. Use the following UpdateRecord overload to bypass this behavior.

- If applicable, see the special notes pertaining to journal fields in the introduction.

- Note: Setting the TSRecord member variable recordState with SetNewRecordWithID is deprecated.

The record will not be updated.

int UpdateRecord( TSRecord* rec, const std::vector< TSString >& fieldNames )

- Similar to above but updates only those fields specified (by database name). Recommended for

updating records obtained via ReadRecordWithWhere using a limited vector of selected fields. Does

not populate a newRecord parameter as does the prior overload.

int ValidateUser( const char* loginid, const char* pwd, int authFlags /*=TS_AUTH_TEAMTRACK*/,

int* userId /*=NULL*/ )

- Validates the SBM login id and password being used to connect to the web server; called from

Connect. ‘authFlags’ should either be TS_AUTH_TEAMTRACK (default), TS_AUTH_LDAP, or

TS_AUTH_NTCR (requires that NT Challenge Response be set up on the web server). The argument

can also be zero, in which case the password is not checked. Though this argument used to be a BOOL,

the function is backward compatible since BOOL is an int type and TRUE =

TS_AUTH_TEAMTRACK = 1.

int ValidateVersion()

- Use to validate the version of the API being used against the version of the SBM software installed on

the web server to verify that they are compatible.

Protected Methods

TSSocket* GetSocket()

- Return a pointer to the open socket.

TSSocket* OpenSocket()

- Allocate memory for a new TSSocket object and return a pointer to it.

int Send( TSSocket* socket, const char* s, int len = 0 )

- Send the string s of lenght len over the socket to the TeamTrack server.

Additional protected members are for internal use only.

95

TSSocket

This class is the object used to send and receive data on a TCP/IP socket. It is a child of the MFC CSocket

class. Certain methods are overridden for specific use in this API. Depending on whether you are writing

your API program on UNIX or Windows this will either be Micro Focus’ own CSocket class or the MFC

CSocket class.

Note: On either the Linux or Unix platforms, a generic, non-MFC, CSocket class is used. The definition for

that class can be found in TSSocket.h.

Public Methods

TSSocket()

- Constructor method; establishes the buffer size and calls the Initialize() method; The ancestor,

CSocket, constructs a synchronous socket object and calls Create()

~TSSocket()

- Destructor method; closes the socket connections and frees up the buffer.

void ClearBuffer()

- Sets the bufferStart and bufferEnd variables to 0.

BOOL Connect( const char* hostAddress, unsigned int portNumber )

- Calls the ancestor’s Connect method in order to establish a connection to the socket.

BOOL Create( LPCTSTR protocol, LPCTSTR directory, LPCTSTR dll,

LPCTSTR auth, LPCTSTR proxy, LPCTSTR entryPoint,

unsigned int connectionSettings, bool bSSOToken)

- Called from the ancestor’s constructor; initializes bufferStart and bufferEnd to 0 and calls the Create()

method on the MFC object CSocket to create the socket and attach to it by calling the Bind() method,

which binds the socket to the specified address. Authentication information is provided and a flag

denoting whether SSO or Basic Authentication is to be used.

int FillBuffer()

- Receive the contents of the socket into the buffer; read incoming data off the socket.

void Initialize()

- Allocates (a 2048 byte block of) memory for the socketBuffer and cast the pointer to it into a char.

int IsConnected()

- Checks to see if the socket is connected on the host address and port numbers passed. If connected, the

connected variable is TRUE.

int Read( char* buffer, int size )

- Copies the socketBuffer to buffer for the number of characters specified by size.

char ReadChar()

- Obtains one character in the socketBuffer array at bufferStart and then increments bufferStart..

int ReadLine( char* buffer, int size )

- Reads a line of data into the buffer.

int ReceiveDouble( double* val )

- Receives data of type double into the buffer from the socket.

96

int ReceiveInt( int* val )

- Receives data of type integer into the buffer from the socket.

int ReceiveString( TSString* str )

- Receives a string of data into the buffer from the socket.

int ReceiveString( char* str, int size )

- Receives a string of data into the buffer from the socket; specifies the number of characters to be

copied into the buffer.

97

TSString

Objects of this type are used to manage the strings of data transmitted to and from the database across the

socket. It can be used to perform comparisons, concatenations, etc.

Public Methods

TSString()

- Constructor method; initializes the buffer to null.

TSString( const TSString& str )

- Constructor method; initializes the buffer with the contents of the string argument.

~TSString()

- Destructor method; frees memory allocated internally for the character buffer.

int CompareNoCase( const char* str )

- Evaluates the contents of the buffer.

void Copy( TSObject* sourceString )

- Uses the assignment operator to copy the contents of sourceString to the calling string’s buffer.

TSObject* Duplicate()

- Creates a new instance of a TSString object and initializes the new instance with the calling TSString’s

buffer contents.

char* GetBuffer()

- Obtains the contents of the buffer.

char* GetBuffer( size_t minsize )

- Obtains the contents of the buffer.

int Length()

- Obtains the size (length) of the buffer if it exists.


- Creates a new instance of a TSString object, returning a pointer to the new instance.

TSString operator + ( char* str )

- Adds the char parameter passed to the existing string.

TSString operator + ( TSString second )

- Adds the string parameter passed to the existing string.

TSString& operator += ( TSString str )

- Adds the string’s buffer onto the existing string.

TSString& operator += ( char c )

- If there is buffer excess, it is incorporated into the buffer.

TSString& operator += ( char* str )

- Allocates more memory to incorporate the character passed into the existing string.

98

TSString& operator = ( const char* str )

- Allocates more memory to incorporate the character being referenced by the pointer in order to

incorporate it into the existing string.

TSString& operator = ( TSString str )

- Assigns the buffer of the string being passed to the existing string object.

BOOL operator == ( TSString str )

- Used to determine if the buffer is empty.

BOOL operator == ( const char *str )

- Used to determine if strings are identical (case sensitive).

char operator [] ( int idx )

- Obtains the contents of the buffer at the index being passed.

int Replace( char chOld, char chNew )

- Replaced one character for another. Returns the number of replaced instances of the character. Zero if

the string isn’t changed.

int Replace( const char* sOld, const char* sNew )

- Replaced one substring for another. Returns the number of replaced instances of the character. Zero if

the string isn’t changed.

int SocketString( TSString& str )

- Used internally. Returns the calling TSString’s value for sending across the socket.


- Builds a string for debugging purposes.

void TrimLeft ( const char* str=NULL )

- Removes spaces or the specified characters from the left side of the string.

void TrimLeft( const char c )

- Removes spaces or the specified character from the left side of the string.

void TrimLeft( const TSString str )

- Removes spaces or the specified characters from the left side of the string.

void TrimRight( const char* str=NULL )

- Removes spaces or the specified characters from the right side of the string.

void TrimRight( const char c )

- Removes spaces or the specified character from the right side of the string.

void TrimRight( const TSString str )

- Removes spaces or the specified characters from the right side of the string.

TSString( const char* str )

- Constructor method; initializes the string with the data being referenced by the variable passed.

99

TSStringList


maintain a list of TSString objects.

Public Methods

TSStringList()


virtual ~TSStringList()


TSString CommaSeparatedList() const

- Creates a comma separated string of the TSStrings on the TSStringList.

bool Find( LPCTSTR searchValue ) const

- Returns true if a TSString from the TSStringList exists who matches the passed in searchValue.

TSString* GetAt( TSPosition* pos )

- Obtains a pointer to a TSString from the list at the position passed.

const TSString* GetAt( TSPosition* pos ) const

- Obtains a const pointer to a TSString from the list at the position passed.

void PopulateByCommaSeparatedList( const TSString& sList )

- Populates the calling TSStringList from a string of comma separated values.

100

TSTransAttr


describes a transition attribute that can be applied for the benefit of integrations.

Public Methods

TSTransAttr( TSServer& server, int nItemId = 0 )

- Constructor method; initializes the object and automatically sets the table id.

TSTransAttr( const TSTransAttr& that )


TSTransAttr& operator = ( const TSTransAttr& that )


virtual ~TSTransAttr()


int GetExtId() const

- Accessor method returning member variable m_nExtId, the constant identifier assigned by the

integration application. This number must be unique for a given prefix.

int GetPreScriptId() const

- Accessor method returning member variable m_nPreScriptId, the ts_id of the pre-transition script to be

executed, or 0 if none.

int GetPostScriptId() const

- Accessor method returning member variable m_nPostScriptId, the ts_id of the post-transition script to

be executed, or 0 if none.

const TSString& GetPrefix() const

- Accessor method returning member variable m_sPrefix, the (three letter, upper case) acronym

associated with an integration and its enabler license.

bool HasValidLicense() const

- Returns true if the transition attribute is associated with a valid (existing and not expired) enabler

license.

void SetExtId( int ExtId )

- Accessor method to set member variable m_nExtId, the constant identifier assigned by the integration

application. This number must be unique for a given prefix.

void SetItemName( const TSString& sItemName )

- Accessor method to set the TSRecordRef member variable m_sItemName, the name of the transition

attribute. When displayed, the name is usually prepended by the prefix to uniquely identify the

attribute.

void SetPreScriptId( int nPreScriptId )

- Accessor method to set member variable m_nPreScriptId, the ts_id of the pre-transition script to be


101

void SetPostScriptId( int nPostScriptId )

- Accessor method to set member variable m_nPostScriptId, the ts_id of the post-transition script to be


void SetPrefix( const TSString& sPrefix )

- Accessor method to set member variable m_sPrefix, the (three letter, upper case) acronym associated

with an integration and its enabler license.

int Add()

- Adds this to the database. If successful, the ts_id of the newly added record is returned. If the 'Prefix –

ExtId' combined key already exists in the database, an error message and

TS_INVALID_PARAMETERS is returned. If some other error occurs, TS_ERROR is retuned.

int Update()

- Updates this in the database. Returns TS_OK if successful. If the 'Prefix – ExtId' combined key already

exists in another record in the database, an error message and TS_INVALID_PARAMETERS is

returned. If update fails otherwise it is likely because the item id specified does not exist and

TS_ITEM_NOT_FOUND is retuned.

102

TSTransition


describes a transition.

Public Methods

TSTransition( TSServer& server, int nTransitionId = 0 )

- Constructor method; initializes the object and automatically sets the table id.

TSTransition( const TSTransition& that )


TSTransition& operator = ( const TSTransition& that )


virtual ~TSTransition()


const TSString& GetNewStateName() const

- Accessor method returning member variable m_sNewStateName, the name of the new state.

const TSString& GetOldStateName() const

- Accessor method returning member variable m_sOldStateName, the name of the old state.

int GetOrigFieldId() const

- Accessor method returning member variable m_nOrigFieldId, which corresponds to the value of “Set

New Item in This Item’s Field”, if that feature is employed for this transition.

int GetPostFieldId() const

- Accessor method returning member variable m_nPostFieldId, which corresponds to the value of “Set

This Item in New Item’s Field”, if that feature is employed for this transition.

int GetSigned() const

- Accessor method returning member variable m_nSigned, which if set to ‘1’, means that an electronic

signature is required for this transition.

int GetSignFieldId() const

- Accessor method returning member variable m_nSignFieldId, which corresponds to the value of

“DateTime Field to Update”, if that feature is employed for an electronic signature.

int GetType() const

- Accessor method returning member variable m_nType, which is the transition type.

const TSTransAttrList& GetTransAttrList() const

- Accessor method returning member variable m_transAttrList, a list of TSTransAttr records, if any.

const TSString& GetWorkflowName() const

- Accessor method returning member variable m_sWorkflowName, the name of the workflow.

bool IsHidden() const

- Returns true if the transition is hidden; that is, it's TS_TRANS_FLG_TRIGGER is set (No Button On

Form).

103

bool IsQuick() const

- Returns true if the transition is configured as a quick transition; that is, it's

TS_TRANS_FLG_QUICK_TRANSITION flag is set.

104

TSTreeList

This class is derived from TSRecordList. Refer to its section for documentation of inherited methods. It is

used to maintain a list of TSRecord objects. It should be used in place of a TSRecordList when working

with tables that are recursive, e.g., TS_PROJECTS, TS_FOLDERS or TS_WORKFLOWS. A TSTreeList

must be used if calling any of the FindRecord methods on the list as these methods will not work correctly

for hierarchical items unless a TSTreeList is used. The entire interface is inhertied though the

implementation is derived. The class can be found in the TSList files.

Public Methods

TSTreeList()


~ TSTreeList()


105

TSUser


defines the interface for user objects.

Public Methods

TSUser()


TSUser( const TSUser& that )


TSUser& operator = ( const TSUser& that )

- Assignment method.

~TSUser()


int Add( int nPersonalFoldersFlag, int nContactRecordFlag, const std::vector<int>& groupIds )

int Add( int nPersonalFoldersFlag, int nContactRecordFlag, const std::vector< TSString>& groupNames )

- External users will be put into the auto external group if set in the administrator.

- nPersonalFoldersFlag: 1 or 0, to create or not create 4 personal folders: in-box, etc.

- nContactRecordFlag: 1 or 0, to create or not create a contact record for the new user.

- The third parameter can be either a vector of group IDs or groups names to which this user is to be a

member.

- External users will always have a contact record created. Flag is ignored.

int ChangePasswordByUserId( int nUserId, TSString sPassword )

int ChangePasswordByUserId(TSString sLoginId, TSString sPassword )

- First parameter is either the user ID (ts_id) or their login ID (string).

- sPassword is the new password and it will be encoded before being sent across the socket.


- Accessor method returning member variable m_nAccessType (see below).

int GetBrowserMask() const

- Accessor method returning member variable m_nBrowserMask (see below).

int GetChangeHistoryMask() const

- Accessor method returning member variable m_nChangeHistoryMask (see below).

int GetContactId() const

- Accessor method returning member variable m_nContactId (see below).

int GetDateFormat() const

- Accessor method returning member variable m_nDateFormat (see below).

const TSString& GetEmail() const

- Accessor method returning member variable m_sEmail (see below).

const TSString& GetEmailCC() const

- Accessor method returning member variable m_sEmailCC (see below).

106

int GetFieldSectionMask() const

- Accessor method returning member variable m_nFieldSectionMask (see below).

const TSString& GetFolderProfile() const

- Accessor method returning member variable m_sFolderProfile (see below).

int GetGMTOffset() const

- Accessor method returning member variable m_nGMTOffset (see below).

int GetHomePageReport() const

- Accessor method returning member variable m_nHomePageReport (see below).

int GetItemLookupTypes() const

- Accessor method returning member variable m_nItemLookupTypes (see below).

const TSString& GetLastLoginDate() const

- Accessor method returning member variable m_sLastLoginDate (see below).

const TSString& GetLoginId() const

- Accessor method returning member variable m_sItemName, member inherited from TSRecordRef.

int GetMaxChanges() const

- Accessor method returning member variable m_nMaxChanges (see below).

int GetMaxItems() const

- Accessor method returning member variable m_nMaxItems (see below).

int GetMaxNotes() const

- Accessor method returning member variable m_nMaxNotes (see below).

const TSRecordRefList& GetMembership() const

TSRecordRefList& GetMembership()

- Accessor methods returning const or non-const references to member variable m_membership (see

below). Beware that if this reference is no longer valid if this goes out of scope or is otherwise

destroyed.

const TSString& GetMemo() const

- Accessor method returning member variable m_sMemo (see below).


- Accessor method returning member variable m_sName (see below).

int GetNotesMask() const

- Accessor method returning member variable m_nNotesMask (see below).

int GetOtherUser() const

- Accessor method returning member variable m_nOtherUser (see below).

int GetPasswordMinLength() const

- Accessor method returning member variable m_nPasswordMinLength (see below).

int GetPasswordOptions() const

- Accessor method returning member variable m_nPasswordOptions (see below).

107

const TSString& GetPasswordSetDate() const

- Accessor method returning member variable m_sPasswordSetDate (see below).

int GetPreferredTableId() const

- Accessor method returning member variable m_nPreferredTableId (see below).

int GetQuickLink() const

- Accessor method returning member variable m_nQuickLink (see below).

int GetStateChangeFlag() const

- Accessor method returning member variable m_nStateChangeFlag (see below).

const TSString& GetTelephone() const

- Accessor method returning member variable m_sTelephone (see below).

int GetTimeFormat() const

- Accessor method returning member variable m_nTimeFormat (see below).

const TSString& GetUserCreatedDate() const

- Accessor method returning member variable m_sUserCreatedDate (see below).

int GetUserId() const

- Accessor method returning member variable m_nItemId, member inherited from TSRecordRef.

bool IsDeleted() const

- Accessor method returning true if member variable m_nDeleted is 1 (see below).

bool IsSpecialCharsRequired() const

- Accessor method returning true if member variable m_nSpecialCharsRequired is 1 (see below).

bool IsUsingConcurrentLicense () const

- Accessor method returning true if m_nUsingConcurrentLicense is 1 (see below).

int ReadByLoginId( TSString sLoginId )

- Read a user record by specifying the login ID (string).

int SetAccessType( int nNewAccessType )

- Accessor method to set member variable m_nAccessType (see below).

int SetBrowserMask( int nNewBrowserMask )

- Accessor method to set member variable m_nBrowserMask (see below).

int SetChangeHistoryMask( int nNewChangeHistoryMask )

- Accessor method to set member variable m_nChangeHistoryMask (see below).

int SetContactId( int nNewContactId )

- Accessor method to set member variable m_nContactId (see below).

int SetDateFormat( int nNewDateFormat )

- Accessor method to set member variable m_nDateFormat (see below).

int SetDeleted( bool bNewDeleted )

- Accessor method to set member variable m_nDeleted to 1 or 0 (see below).

108

const TSString& SetEmail( const TSString& sNewEmail )

- Accessor method to set member variable m_sEmail (see below).

const TSString& SetEmailCC( const TSString& sNewEmailCC )

- Accessor method to set member variable m_sEmailCC (see below).

int SetFieldSectionMask( int nNewFieldSectionMask )

- Accessor method to set member variable m_nFieldSectionMask (see below).

int SetGMTOffset( int nNewGMTOffset )

- Accessor method to set member variable m_nGMTOffset (see below).

int SetHomePageReport( int nNewHomePageReport )

- Accessor method to set member variable m_nHomePageReport (see below).

int SetItemLookupTypes( int nNewItemLookupTypes )

- Accessor method to set member variable m_nItemLookupTypes (see below).

const TSString& SetLoginId( const TSString& sNewLoginId )

- Accessor method to set member variable m_sItemName, member inherited from TSRecordRef.

int SetMaxChanges( int nNewMaxChanges )

- Accessor method to set member variable m_nMaxChanges (see below).

int SetMaxItems( int nNewMaxItems )

- Accessor method to set member variable m_nMaxItems (see below).

int SetMaxNotes( int nNewMaxNotes )

- Accessor method to set member variable m_nMaxNotes (see below).

const TSString& SetMemo( const TSString& sNewMemo )

- Accessor method to set member variable m_sMemo (see below).

const TSString& SetName( const TSString& sNewName )

- Accessor method to set member variable m_sName (see below).

int SetNotesMask( int nNewNotesMask )

- Accessor method to set member variable m_nNotesMask (see below).

int SetPassword( const TSString& sNewPassword )

- Accessor method to set member variable m_sPassword and sets m_bPasswordModified to true (see

below).

int SetPasswordMinLength( int nNewPasswordMinLength )

- Accessor method to set member variable m_nPasswordMinLength (see below).

int SetPasswordOptions( int nNewPasswordOptions )

- Accessor method to set member variable m_nPasswordOptions (see below).

int SetPreferredTableId( int nNewPreferredTableId )

- Accessor method to set member variable m_nPreferredTableId (see below).

int SetQuickLink( int nNewQuickLink )

- Accessor method to set member variable m_nQuickLink (see below).

109

int SetSpecialCharactersRequired( bool bNewSpecialCharsRequired )

- Accessor method to set member variable m_nSpecialCharsRequired to 1 or 0 (see below).

int SetStateChangeFlag( int nNewStateChangeFlag )

- Accessor method to set member variable m_nStateChangeFlag (see below).

const TSString& SetTelephone( const TSString& sNewTelephone )

- Accessor method to set member variable m_sTelephone (see below).

int SetTimeFormat( int nNewTimeFormat )

- Accessor method to set member variable m_nTimeFormat (see below).

int SetUserId()

- Accessor method to set member variable m_nUserId (see below).

int SetUsingConcurrentLicense( bool bNewUsingConcurrentLicense )

- Accessor method to set member variable m_nUsingConcurrentLicense to 1 or 0 (see below).

int Update( int nContactRecordFlag )

- Access type = None, User, or Managed Administrator: nContactRecordFlag can be 0 – Do not update

contact record, 1 – Create/Update contact record, or 2 – Delete contact record.

- Access type = External: nContactRecordFlag can be 0 – Do not update contact record or 1 –

Create/Update contact record. Can not delete the contact record.

- Access type = API/Script: nContactRecordFlag is ignored completely. No contact record is ever

created for API/Script user.


bool m_bPasswordModified

- Set to true if m_sPassword has been modified.

int m_nAccessType

- Bit mask indicating user's access to products.

0 = None

1 = User

4 = External

16 = Managed Administrator

32 = API/Script

int m_nBrowserMask

- User Preference - Bit mask indicating various browser related options. See TS_FLDMASK_ in

TSDef.h.

int m_nChangeHistoryMask

- User Preference - Bit mask indicating how Change History is to be displayed. See TS_FLDMASK_ in

TSDef.h.

int m_nContactId

- TS_ID from TS_CONTACTS table if the user has a contact record.

int m_nDateFormat

- User Preference - Date formatting to use. See TS_DATE_FORMAT_ in TSDef.h.

110

int m_nDeleted

- Set to 1 if user is marked as deleted.

int m_nFieldSectionMask

- User Preference - Bit mask indicating which field sections to display. See TS_FLDMASK_ in

TSDef.h.

int m_nGMTOffset

- User Preference - Difference between user's local time and (behind) GMT time.

int m_nHomePageReport

- User Preference - TS_ID from TS_REPORTS for report to be shown on user's homepage.

int m_nItemLookupTypes

- User Preference - Types of items to populate results list during a lookup search. See TS_MANAGE_

in TSDef.h.

int m_nMaxChanges

- User Preference - Maximum number of Change History records to display for each item.

int m_nMaxItems

- User Preference - Maximum number of items to display on a page at a time.

int m_nMaxNotes

- User preference indicating maximum number of notes to display for each item.

int m_nMinPasswordLength

- Minimum length allowed for a password. -1 if no minimum length is required.

int m_nNotesMask

- User Preference - Bit mask indicating how notes are to be displayed. See TS_FLDMASK_ in TSDef.h.

int m_nOtherUser

- TS_ID from TS_USERS table of other user when logging in as another user.

int m_nPasswordOptions

- User password changing privileges. See TS_PASSWORD_ in TSDef.h.

int m_nPreferredTableId

- User Preference - TS_ID from TS_TABLES for user's preferred table.

int m_nQuickLink

- User Preference - Operation performed by browser Quick Link button.

- The available options are based upon tables, solutions and user privileges as follows:

Select a Project, Then Submit a New Item = 0

Mange the Knowledge Base = 9

Submit/Lookup (Primary Table Name) = Primary Table Id; for each primary table into which the

user has privilege to both submit and to view items.

Submit into Base Project: (Project Name) = - Project Id; for each project within each primary table

into which the user has privilege to submit items.

Mange (Auxiliary Table Name) = Auxiliary Table Id; for each auxiliary table the user has

privilege to view.

111

int m_nSpecialCharsRequired

- Set to 1 if special characters are required in the user's password.

int m_nStateChangeFlag

- User Preference - Flag indicating where State Change History should be displayed, if at all.

0 = Do not display

1 = Display at top

2 = Display at bottom.

int m_nTimeFormat

- User Preference - Time formatting to use. See TS_TIME_FORMAT_ in TSDef.h.

int m_nUsingConcurrentLicense

- Set to 1 if uses a concurrent license.

TSRecordRefList m_membership

- List of the groups to which the user belongs.

TSString m_sEmail

- User's email for notifications.

TSString m_sEmailCC

- Email address for carbon copy notifications.

TSString m_sFolderProfile

- Folder structure indicated by clicking browser Save Profile button.

TSString m_sLastLoginDate

- Last day user logged in. TS_BLANK_DATETIME or -2 if user has never logged in.

TSString m_sMemo

- Miscellaneous text displayed in the Administrator next to the user and on the system report:Users.

TSString m_sName

- User's full name.

TSString m_sPassword

- User's password. Never populated by server. Only allowed to set, and only if appropriate privileges are

set.

TSString m_sPasswordSetDate

- Date password was last set.

TSString m_sTelephone

- User's telephone number.

TSString m_sUserCreatedDate

- Date the user was added to the system.

112

TSUserDefinedSchema

This class is derived from TSObject. Refer to its section for documentation of inherited methods. This class

provides a means for obtaining a given table’s user-defined field list. The class can be found in the

TSServer files.

Public Methods

TSUserDefinedSchema()


~TSUserDefinedSchema()


void Copy( TSObject* sourceSchema )

- Copy the contents of sourceSchema into the current TSUserDefinedSchema object.


TSObject* Duplicate( int type = 0 )

- Creates a new instance of a TSUserDefinedSchema object and duplicates the calling

TSUserDefinedSchema’s members onto the new instance.



- Returns a new instance of a TSUserDefinedSchema object, returning a pointer to the new instance.


int SocketString( TSString& /*str*/ )

- This method is not needed for a user-defined schema object.



- Builds a string of tableid and name; used mainly for debugging purposes.




- List of all fields defined for the table this schema represents.

TSString name

- The name of the table this schema represents.

int tableId

- The ID of the table this schema represents.

int cacheCounter

- Cache counter associated with this table. If this value changes between reads, then one or more records

have been updated and field values might be out of date.

113

Global Methods

Error Status Methods

void TSAppendLastErrorMessage( char* sErrorMessage )

- Accessor method setting TSServer static member variable TSErrorMessage, by appending passed in

sErrorMessage to the existing error message.

void TSAppendLastErrorMessage( const TSString& sErrorMessage )

- Accessor method setting TSServer static member variable TSErrorMessage, by appending passed in

sErrorMessage to the existing error message.

void TSClearLastError( )

- Accessor method clearing TSServer static member variable errorCode by setting to TS_OK.

TS_API int TSGetLastError( )

- Accessor method returning TSServer static member variable errorCode.

TS_API const char* TSGetLastErrorMessage( )

- Accessor method returning TSServer static member variable TSErrorMessage, the current error

message including the most recent server side error message, unless TSSetLastErrorMessage method

has been called already. This method is preferred over the GetLastErrorMessage method, as the latter

returns only the server side error message.

void TSSetLastError( int errorCode )

- Accessor method setting TSServer static member variable TSErrorCode to passed in errorCode.

void TSSetLastErrorMessage( char* sErrorMessage )

- Accessor method setting TSServer static member variable TSErrorMessage to passed in

sErrorMessage.

Encoding Methods

void TSEncodeDouble( double in, TSString& out )

- Converts a double to a string.

void TSEncodeInt( int in, TSString& out )

- Converts an integer to a string.

void TSEncodeString( TSString& in, TSString& out )

- Encodes a string to be sent through the web server enclosed in quotes.

void TSEncodeString( const char* in, TSString& out )

- Encodes a character constant to a string.

void TSEncodeText( const char* in, TSString& out )

- Encodes a string to be sent to the web server but doesn’t enclose it in quotes.

void TSEncodeText( TSString& in, TSString& out )

- Format what’s in the buffer and print it to the screen.

114

Other Methods

int TSInitializeWinsock()

- Windows socket startup code to initialize the Winsock DLL.

Appendix A, Revised Date Format

As of version 7.1 date fields with date-only or date-time attributes will use the native DBMS date datatype

instead of an integer for storing date values. Fields with time-of-day and elapsed time attributes will

continue to store the number of seconds, starting at zero, but the data type of the column will be changed

from int to float to account for the increased range.

Pre-Version 7.1 date field behavior

For a date field, these API's would receive or return an integer value. The integer value would be

interpreted as the number of seconds since Jan 1st, 1970 for date-only and date-time fields and the number

of seconds starting at zero for elapsed-time and time-of-day fields.

TSRecord::GetInt(const char* fieldname )

TSRecord::SetInt( const char* fieldName, int value )

int TSDisplayField::GetInternalValue( int& nValue ) const

int TSDisplayField::SetInternalValue( int nValue )

Version 7.1 date field behavior

In order to work with dates beyond the limitations of the integer range, these API's will retrieve the value

for a date field as the number of days since Dec 30th, 1899 for date-only and date-time fields and the

number of seconds starting at zero for elapsed-time and time-of-day fields. For date-only and date-time

fields the fractional portion represents part of a day. Only whole number value are accepted for elapsed-

time and time-of-day fields. For example, a value of 6.25 would represent the date "Jan 5th, 1900 6:00:00

AM". Note: For Windows programmers, the double date value is compatible with the COleDateTime

class.

Here is a list of methods that should be used when getting and setting date fields.

double TSRecord::GetDouble(const char* fieldname )

int TSRecord::GetDouble(const char* fieldname, double* value )

TSRecord::SetDouble( const char* fieldName, double value )

int TSDisplayField::GetInternalValue( double& dValue ) const

int TSDisplayField::GetInternalValue( struct tm& stValue ) const

int TSDisplayField::SetInternalValue( double fValue )

int TSDisplayField::SetInternalValue( struct tm& stValue )

115

int TSDisplayField::SetDisplayValue( const TSString& sNewDisplayValue )

The API SetDisplayValue will still accept the date or time string according to the user's preferences as

before. However, it will also now accept a date string in SBM's ISO 8601 date format regardless of the

user's preference settings. SBM's ISO 8601 date format is ‘YYYY-MM-DDTH24:mm:ss+tzH:tzM’.

Example, 2007-07-01T19:24:11+00:00.

SQL Statements and Date Fields

These API functions require or take an optional SQL query string (also referred to as a ‘where clause’).

ReadDynaListWithWhere

ReadRecordListWithWhere

ReadRecordWithWhere

ExecuteSQL

GetIdentity

GetIdentityString

As of version 7.1, query strings that reference a date field need to compare the date field with a value that is

compatible with the DBMS specific date data type.

Example, To retrieve all records that have been modified after July 27, 2007 at 9:00 PM.

SQL for MS SQL Server,

TS_LASTMODIFIEDDATE > ‘2007-7-27 21:00:00’

SQL for Oracle,

TS_LASTMODIFIEDDATE > To_Date(‘2007-7-27 21:00:00’,’yyyy-mm-dd HH24:MI:SS’)

Micro Focus Solutions Business Manager API...2020/02/26 · 2 Dear Customer, This document...

Documents

Transcript of Micro Focus Solutions Business Manager API...2020/02/26 · 2 Dear Customer, This document...