Micro Focus Solutions Business Manager API

(1)

Micro Focus Solutions Business Manager

API

Reference Guide

Solutions Business Manager Version 11.7.1

(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,

(3)

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 TSDynaColumnList ...39 TSDynaRecord ...40 TSDynaRecordList ...41 TSDynaValue ...42 TSDynaValueList ...42

(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

(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.

(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, per-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

(10)

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

(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)

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

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()

TSDynaRecord( const TSDynaRecord& other )

- Copy Constructor method. virtual ~TSDynaRecord() - Destructor method.

(14)

14 TSPosition

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

list of TSRecord, 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()

- 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

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()

TSDynaRecord( const TSDynaRecord& other )

- Copy Constructor method. virtual ~TSDynaRecord()

(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

(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.

(19)

For Use With Database Representation Classes

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)

For Use With Database Representation Classes

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.

(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 with fields populated and ordered as shown in the browser at the 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 with fields populated and ordered as shown in the browser at the 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.

(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.

(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.

(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.

(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

(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>

Reads a particular record from a table for a specified id and displays the data on the screen. Demonstrates 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>

Reads a particular record from a table for a specified id and displays the data on the screen. Demonstrates 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() - Destructor method. 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

(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:

(31)

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

(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 ) - Assignment operator method.

virtual ~TSAuxiliaryItem() - Destructor method. 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. - Requires a roundtrip to the server.

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. - Requires a roundtrip to the server.

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

(33)

TSChangeHistory

This class is derived from TSRecordRef. Refer to its section for documentation of inherited methods. It 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 ) - Assignment operator method.

virtual ~TSChangeHistory() - Destructor method. 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

(34)

int GetPriorReal () const

- Accessor method returning member variable m_nPriorReal. int GetType() const

- Accessor method returning member variable m_nType.

Protected Member Variables

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

(35)

TSDisplayField

This class is derived from TSRecordRef. Refer to its section for documentation of inherited methods. It 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 ) - Assignment operator method.

virtual ~TSDisplayField() - Destructor method.

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.

Micro Focus Solutions Business Manager API