RDA2 Programmers Guide

Retail Pro

®

8 Series

RDA2 Programmers Guide

Retail Pro

3252 Holiday Court

La Jolla, CA 92037 USA

USA 1-800-738-2457

International +1-858-550-3355

www.retailpro.com

About this Guide

This document is intended to be a guide to help Software Developers use the Retail Pro APIs to

create extensions and customizations to the Retail Pro® software.

If you believe the information presented here is incomplete or inaccurate, we encourage you to

contact us at

[email protected]

.

The software described herein is furnished under a license agreement.

Retail Pro

3252 Holiday Court

La Jolla, CA 92037 USA

USA 1-800-738-2457)

International +1-858-550-3355

www.retailpro.com

Copyright © 2008 Intuit, Inc.® _{All rights reserved. Redistributed by Retail Pro under license.}

Retail Pro 3252 Holiday Court La Jolla, CA 92037 U.S.A.

Trademarks

Retail Pro and the Retail Pro logo are registered trademarks and/or registered service marks in the United States and other countries. Oracle and Oracle 9i are registered trademarks and/or registered service marks of Oracle Corporation. All rights reserved. Other parties’ trademarks or service marks are the property of their respective owners and should be treated as such.

Table of Contents

About this Guide ... ii

Introduction ...1

Revision History ...1

The RDA2 Object Model ...2

RDA2 and the Retail Pro Database...2

RDA2 Basics...2

Tables... 2

Documents ... 2

Nested Documents ...3

Fields...3

RDA2 Server Interface (IRdaDB) ...4

RDA2 Server Interface (IRdaDB) ...5

Properties and Methods...5

All TableNames Property ... 5

Connected Property... 6

Preferences Property ... 6

Connect Method... 6

CreateTableByID Method... 7

CreateTableByName Method ... 7

Disconnect Method ... 7

UpdatePreferences Method... 7

IRDATable Interface ...8

Properties and Methods...9

Active Property ... 10

ActiveIndexID Property... 10

ActiveIndexName Property ... 10

AllIndexNames Property ... 11

Bof Property... 11

Bookmark Property... 11

CustomInterface Property ... 12

DataPath Property ... 12

DirectAccess Property ... 12

Empty Property ... 12

Eof Property... 12

FileName Property... 13

History Property... 13

Name Property ... 14

NoSequences Property... 14

UseBlockReadWrite Property... 14

Close Method... 14

Document Method ... 14

EraseRecord Method... 15

Find Method... 15

First Method... 15

Last Method ... 16

NewRecord Method... 16

Next Method ... 16

Open Method ... 16

PostRecord Method... 17

Prior Method... 17

IRdaHistory Interface...18

Properties and Methods...18

Month Property ... 18

Year Property... 18

SetMonthYear Method ... 19

IRdaDirectAccess Interface...20

Properties and Methods...20

RecordCount Property ... 20

RecordNumber Property ... 20

GoToRecord Method ... 21

IRdaDocument Interface ...22

Properties and Methods...22

Add2XMLNode Method... 23

AllFieldNames Property ... 24

AllNestedDocNames Property... 24

Count Property... 24

CustomInterface Property ... 24

DescriptiveInfo Property... 25

DeSyncDetected Method ... 25

EditMode Property... 25

FieldByID Method... 26

FieldByName Method... 26

GetBoolean Method... 27

GetDateTimeMethod ... 27

GetString Method ... 28

GetSubDouble Method ... 28

LoadFromStream Method... 29

Name Property ... 29

NestedDocByID Property ... 29

NestedDocByName Property... 30

NoInventoryLookups Property ... 30

RefreshDocument Method... 30

RefreshProvider Method... 31

ReSyncPosition Method ... 31

ReSyncToLastSetPosition Method ... 31

SaveToStream Method ... 32

SetBoolean Method... 32

SetDate/Time Method... 32

SetDouble Method ... 33

SetInteger Method... 33

SetPosition Method... 33

SetString Method ... 34

SetSubDouble Method... 34

XMLDOMDocument Method ... 34

XMLSchema2Dir Method ... 35

IRdaField Interface...36

Properties and Methods...36

Caption Property ... 36

Description Property ... 36

FieldType Property ... 37

ID Property ... 37

LookupList Property ... 37

Name Property ... 37

Size Property... 38

Value Property ... 38

Text Method... 38

IRdaInventory Interface...39

Properties and Methods...39

UseInTransit Property... 39

UseMinMax Property ... 40

UseMulti Property... 40

UsePrice Property ... 40

ConnectItemToStyle Method... 41

DisconnectItemFromStyle Method... 41

StyleItems Method... 42

IRdaSO Interface...43

Properties and Methods...43

AddDeposit Method... 43

IRdaVouTerms Interface ...44

Percent/Day Pairs...44

Properties and Methods...45

Date Property ... 45

Kind Property... 45

Split Property ... 46

SplitTotal Property... 46

Get_PercentDays Method ... 46

Set_PercentDays Method... 47

IRdaTender Interface...48

Properties and Methods...48

AddItem Method... 49

CreditCardIsRounded Property... 49

DeleteItem Method ... 49

RoundedUndefined Property ... 50

Sum Property ... 50

TenderItems Property ... 50

Undefined Property... 50

XML Property... 51

IRdaTenderItem Interface ...52

Associated Data Types...52

Tender Type... 52

Properties and Methods...52

Amount Property... 53

Desc Property... 53

Info Property... 53

TenderType Property ... 53

IRdaStoreCredit Interface...54

Properties and Methods...54

InitStoreCreditID Method... 54

FCAmount Property... 55

IRdaCheck Interface...56

Properties and Methods...56

BankNumber Property ... 56

CheckNumber Property ... 56

CustomerName Property... 56

DateofBirth Property... 57

DriverLicenseNumber Property... 57

StateCode Property ... 57

IRdaCreditCard Interface ...58

Properties and Methods...58

AuthorizationNum Property ... 58

CardNumber Property... 58

CardType Property... 59

ControlNum Property ... 59

ExpMonth Property... 59

ExpYear Property ... 59

ReferenceNum ... 59

IRdaCharge Interface ...60

Properties and Methods...60

DiscountDays Property ... 60

DiscountPercent Property ... 60

NetDays Property... 61

IRdaPayments Interface...62

Properties and Methods...62

NumofPayments Property... 62

PaymentAmount Property... 62

StartingDate Property ... 62

IRdaGift Interface...63

Properties and Methods...63

GiftNumber Property ... 63

InitGiftNumber Method... 63

IRdaCollection Interface ...64

Properties and Methods...64

Item Method... 64

Length Property ... 64

RDA2 Table Information ...65

Customers ... 66

Vendors... 67

Items ... 67

Invoices... 68

POs... 68

SOs... 69

Former Vouchers ... 69

Pending Vouchers ... 70

ASN Vouchers ... 70

Memos ... 71

Slips ... 71

SubLocDefs ... 71

SubLocQtys ... 72

MovNotes ... 72

MovOrders... 73

TOs ... 73

Nested Document Names and ID Numbers ...74

Table Schemas ...75

Departments... 75

Customers ... 76

Vendors... 78

Items ... 79

Invoices... 83

ReceiptItem (Nested Table) ... 88

POs... 91

POItem (Nested Table) ... 94

SO ... 97

SOItem (Nested Table) ... 102

SODeposit (Nested Table) ... 106

SOHistory (Nested Table) ... 106

Former Vouchers ... 107

Pending Vouchers ... 111

ASN Vouchers ... 115

VoucherItem (Nested Table) ... 119

Memos ... 122

MemoItem(Nested Table)... 124

Slips ... 126

MovNotes ... 132

MovNoteItem (Nested Table)... 134

MOs ... 136

MOItem (Nested Table)... 138

TOs ... 140

TOItem (Nested Table)... 141

XML Preferences ...144

Updating Preferences ...144

Sample Preference Document... 145

Programming with RDA2...146

Tips and Tricks ...146

Converting SID Types ... 146

Setting Fee and Shipping Amounts... 146

Using COM Objects in a Delphi Console Application ... 147

RDA2 and .NET – A Word of Warning ... 148

Visual Basic Examples ...149

Connecting to the Database ... 149

Adding Table Names to a Combo Box ... 149

Opening a Table and Setting the Active Index ... 149

Add a Department... 149

Add an Item to a Purchase Order... 150

Use a Field with a Lookup List to Populate a Combo Box... 151

Create an IrdaInventory Object... 151

Create an IRdaSO Object... 151

Create IRdaTender Objects...152

To create an IRdaTender Object for the Invoices Table... 152

To create an IRdaTender Object for SO deposits ... 152

Get the Terms of a Purchase Order... 152

Introduction

This document is intended to be a guide to help Software Developers use the Retail Pro APIs to

create extensions and customizations to the Retail Pro software. The RDA2.dll is used for

standalone applications to read and write information to the Retail Pro database, but the interfaces

used in RDA2 are also used to pass data in the Retail Pro plugins API. It is necessary to

understand the RDA2 object model i order to create functional Retail Pro plugins.

Revision History

Revision 2 – In RDA2 versions dated 12/5/01 and later the IRdaTenderXML object has been

renamed IRdaTender. The Programmer’s Guide now refers only to IRdaTender.

Revision 3 – Updated Documentation to include IRdaTenderItem and the specific tender

interfaces. Added new properties and methods to the IRdaDocument Interface

The RDA2 Object Model

RDA2 and the Retail Pro Database

The Retail Pro Version 8 and earlier is built on B-Tree Filer. As such, data is not stored in a

traditional table format.

RDA2 uses the underlying structure of the Retail Pro database and presents the data in a more

traditional table oriented format; therefore, the table schema exposed by RDA2 do not reflect the

physical (and in some cases, logical) structure of Retail Pro itself.

RDA2 Basics

The major classes found in the RDA2 library are the IRdaTable, IRdaDocument and IRdaField

classes.

Tables

IRdaTables represent tables. All other RDA2 objects are created from IRdaTable. IRdaTable

itself does not directly expose individual fields and values but does control the current record

position of a table as well as other table parameters.

Documents

IRdaDocuments are created from IRdaTable objects or existing IRdaDocument objects.

Internally, IRdaDocuments use XML documents and can present data in the XML format.

IRdaDocument objects directly expose the individual fields and values of a table.

There are two types of IRdaDocuments: standard and nested. Standard documents are linked to

IRdaTables and created from IRdaTable objects.

Nested Documents

Nested documents are used in places where multiple records of information can exist for a single

record in a table. Nested documents are always “attached” to standard documents (that is, they are

created from IRdaDocument objects that are “standard” documents). Nested documents do not

exist for every table in the Rda2 model.

For example, the Invoices table consists of what would normally be thought of as Invoice header

records. An IRdaTable object is created for the Invoices table. There is an IRdaDoucment object

automatically connected to the IRdaTable object. In this case, the IRdaDocument object could be

used to manipulate the invoice header records, add a new invoice, delete an invoice, etc.

The Invoice items (i.e. the items connected to the Invoice header records) would be accessed

using a nested document. In this case, it would be the “ReceiptItems” nested document. (Nested

documents are sometimes referred to as nested tables). The nested document is an IRdaDocument

object created using the methods of IRdaDocument itself. In this case, the ReceiptItems nested

document exposes the fields and values of the invoice items.

For a complete list of nested documents and the standard documents they are attached to, see

Nested Document Names and ID Numbers.

Fields

Most of the data in the Retail Pro database is presented by RDA2 using a table model with fields

as the table columns and rows representing each record of data.

The fields themselves are manipulated using the IRdaDocument object or IRdaField object.

There are two ways to specify a particular field in RDA2: Field ID numbers and Field names.

Every field in an RDA2 table is assigned a field ID number. Almost every field ID number is

assigned to a constant enumerated in the RDA2 object model. Field ID constants start with the

FID prefix (F-I-D). For example, the constant fidTaxAmt when used with the Receipts table

refers to the field that contains the total amount of tax for the receipt.

Fields are also assigned Field names. Field names are not enumerated in the RDA2 library. Field

names are only used with the IRdaField object. Field names start with FLD.

Note: since FID and FLD can appear very similar in lower case depending on type font (fid and

fld), field ID number constant names have sometimes been confused with field names.

RDA2Server

(IRdaDB)

IRdaTable

IRdaInventory

IRdaSO

IRdaHistory

IRdaDirectAccess

IRdaDocument

IRdaVouTerms

IRdaTender

IRdaDocument

(Nested)

IRdaTenderItem

IRdaField

DOMDocument

IRdaField

DOMDocument

IRdaCollection

IRdaStoreCredit

IRdaFC

IRdaCheck

IRdaCreditCard

IRdaCharge

IRdaPayments

RDA2 Server Interface (IRdaDB)

The Rda2Server object is used to connect to a specific Retail Pro database. All other objects in

the RDA2 object model are created from the Rda2Server object.

Use the Connect method of Rda2Server to connect to an Retail Pro database. Once connected, use

the CreateTableByID or CreateTableByName methods to create IRdaTable objects that enable

access to the Retail Pro data.

Use the Disconnect method to close the connection to the database. You only need to explicitly

disconnect from the Retail Pro database if you want to reuse the same object to connect to a

different database; otherwise, when your program releases the RDA2Server object it will

automatically close any open tables and disconnect.

The Preferences property returns an XML document containing the system preferences. The

UpdatePreferences method allows you to set currency rates.

Properties and Methods

AllTableNames Property – Returns all available table names.

Connected Property – Indicates state of connection to database.

Preferences Property – Returns the Retail Pro preferences.

Connect Method – Connects to the database.

CreateTableByID – Creates an IRdaTable object.

CreateTableByName – Creates an IRdaTable object.

Disconnect Method – Disconnects from the database.

UpdatePreferences Method – Updates the Retail Pro Preferences.

All TableNames Property

AllTableNames returns a list of available tables as an IRdaCollection object.

Syntax:

IRdaCollection := Rda2Server.AllTableNames;

Remarks:

The tables exposed by the Rda2Server object may vary with different versions of Retail Pro. The

AllTableNames property returns the names of all the tables available in the current Retail Pro

database.

Connected Property

Returns a boolean value indicating whether or not the Rda2Server object is currently connected to

the database. Read only.

Syntax:

blnDBConnected := Rda2Server.Connected;

Preferences Property

Returns a DOMDocument object that contains a subset of the Retail Pro preferences. Read only.

(See the documentation on the XML Preferences Document.)

Syntax:

DOMDocument := Rda2Server.Preferences;

Connect Method

Establishes a connection to an RPro database. Example.

Syntax:

Rda2Server.Connect(DataPath, Workstation, UserName, Password)

Parameters:

DataPath – a string value containing the path to Retail Pro. Example: 'c:\Retail'

Workstation – a long integer indicating the workstation number.

UserName – Not implemented, leave blank.

Password – Not implemented, leave blank.

Remarks:

If you set the Workstation parameter to zero, Retail Pro will use the value of the environment

variable RPROWS to determine the workstation number. Using zero without this variable set will

lead to various error conditions.

There is no provision for an error return or error value using the Connect method. Use the

Connected property to determine whether or not the connection was successful.

The workstation parameter will affect data such as preferences and sequence numbers that are

workstation dependent.

If there is no workstation directory for the workstation specified in the Connect method, a new

workstation directory will be created.

CreateTableByID Method

Creates and returns an IRdaTable object based on a table ID. This method does not actually create

a new table structure. Rather, it creates an IRdaTable object based on table structures that are

predefined by Rda2.

Syntax:

Set IRdaTable = Rda2Server.CreateTableByID(TableID)

Parameters:

TableID – a long integer. Must be a valid table ID number. (See the RDA2 Table Schema

Document).

CreateTableByName Method

Creates and returns an IRdaTable object based on a table name.

Syntax:

Set IRdaTable = Rda2Server.CreateTableByName(TableName)

Parameters:

TableName – a string containing a valid table name. The parameter is case sensitive.

Disconnect Method

Disconnects the Rda2Server object from the Retail Pro database. In most cases, it is not necessary

to use the Disconnect method.

Syntax:

Rda2Server.Disconnect

UpdatePreferences Method

Used to update the currency rate preferences. This method will only change the currency rates for

currencies that are already in the system. (See the VB RDA2ObjectModel project for an

example.)

Syntax:

Rda2Server.UpdatePreferences(Preference)

Parameters:

Preference – an IXMLDOMElement corresponding to the CURRENCY node in the XML

Preferences document.

IRDATable Interface

The IRdaTable object presents data from the Retail Pro database in a table like format.

The properties and methods of the IRdaTable interface are used to manipulate the data on a

row-by-row basis. Individual fields are not accessible from the IRdaTable object. Use the

IRdaDocument and IRdaField interfaces to manipulate individual fields.

IRdaTable objects are instantiated using the CreateTableByID and CreateTableByName methods

of an Rda2Server object. The RDA2 object model contains a predefined table schema. (See the

RDA2 Table Schema Documentation). New table structures cannot be defined or opened using

RDA2.

IRdaTables do not reflect a true relational model for the Retail Pro database. Data is represented

in a row/column format where the columns of the table are fields in the Retail Pro database. Once

a table is opened, RDA2 maintains a current record position within the table. Row order within an

open table is determined by the current active index of the table. The current index can be

changed using the ActiveIndexName and ActiveIndexID properties.

Use the Open and Close method or the Active property of IRdaTable to open and close the table.

Use the First, Last, Next, Prior, Find methods, or the Bookmark property to change the current

record position.

The Bof and Eof properties indicate whether the current position is at the beginning or the end of

the table.

Use the NewRecord method to add a new record to the table and the PostRecord method to save a

new record or update the current record.

IRdaDocument, IrdaDirectAccess, and IrdaHistory objects are created using the Document

method and DirectAccess and History properties of IRdaTable respectively.

Properties and Methods

Active Property – Indicates whether a table is active (open) or not.

ActiveIndexID Property – Sets the active index for a table.

ActiveIndexName Property – Sets the active index for a table.

AllIndexNames Property – Returns the names of all available indexes.

Bof Property – Indicates that the current table is at the first record.

Bookmark Property – Gets or sets the current record.

CustomInterface Property – Creates an IRdaInventory or IRdaSO object.

DataPath Property – Not used.

DirectAccess Property – Allows direct access to table positioning.

Empty Property – Indicates that a table is empty.

Eof Property – Indicates that the current position is the last record in the table.

FileName Property – Returns the name of the current data file.

History Property – Creates an IRdaHistory object.

IndexCount Property – Returns the number of available indexes.

IsRecordDeleted Property – Indicates that a record has been deleted.

Name Property – Not used.

NoSequences Property – Indicates the state for sequence numbers.

UseBlockReadWrite Property – Allows block reading and writing.

Close Method – Closes the table.

Document Method – Creates an IRdaDocument object.

EraseRecord Method – Deletes a record.

Find Method – Finds an index key value.

First Method – Sets the current record position to the first record.

Last Method – Sets the current record position to the last record.

NewRecord Method – Inserts a new record.

Next Method – Moves the current record position to the next record.

Open Method – Opens a table.

PostRecord Method – Saves the current record to the database.

Prior Method – Moves the current record position to the prior record.

Active Property

Returns a true/false value indicating whether a table is active (open) or not. Can also be used to

set the Active property for a table.

Syntax:

blnTableActive := IrdaTable.Active;

or

IrdaTable.Active := True | False;

Remarks:

Setting this property can force a table to open or close. If the Active property is False and is set to

True, the table will be opened. If the Active property is True and is set to False, the table will be

closed.

ActiveIndexID Property

Returns or sets active index of a table using the index ID number (long integer). Example.

Syntax:

lngIndexID := IrdaTable.ActiveIndexID;

or

IRdaTable.ActiveIndexID := lngIndexID;

Remarks:

Setting the Active index of a table changes the record order within the table. For example, if the

active index of the Departments table is DCS then the table is ordered by the DCS field. If the

active index is changed to DCS Name, the table is ordered by DCS Name.

Setting the Active index of a table affects the behavior of the Find method.

Note: Each table has a default index that is active when the table is opened. See the list of Table

Indexes.

ActiveIndexName Property

Returns or sets the active index of a table using the index name (string).

Syntax:

strIndexName := IrdaTable.ActiveIndexName;

or

IRdaTable.ActiveIndexName := strIndexName;

See the remarks under ActiveIndexByID property.

AllIndexNames Property

Returns a list of all index names available for the table. The index names are returned as an

IRdaCollection object. This property is read only.

Syntax:

IndexNames := IrdaTable.AllIndexNames;

Bof Property

Returns a Boolean value that indicates if the current record is the first record in the table.

Syntax:

blnBOF := IrdaTable.Bof;

Bookmark Property

Use the Bookmark property to get or set the current record position in the IRdaTable object.

Bookmarks are returned as integers expressed as a variant data type.

Syntax:

vntBMark := IRdaTable.Bookmark;

or

IRdaTable.Bookmark := vntBMark;

Remarks:

Bookmarks makes for a quick way of revisiting a known record in an IRdaTable. If you need to

do a lot of searching through a table that does not have a suitable index you can create a hash

table based on your search criteria and store the bookmarks in it. It takes some time to initially go

through the entire table and generate hash values and read bookmark values, but it pays if you

have to to many reoccurring searches on the same table.

In the Items table, the Bookmark is synonymous to Item ID so if you know the item ID you can

quickly locate that item using the Bookmark property.

CustomInterface Property

Returns an RDA2 object. The returned object depends on the IRdaTable that has been opened.

Read only.

Syntax:

Object := IRdaTable.CustomInterface;

Remarks:

CustomInterface returns the following objects based on the IRdaTable that has been opened:

Table CustomInterface

Object

Inventory IRdaInventory

SOs IRdaSO

Invoices IRdaTender

SODeposit IRdaTender

DataPath Property

The DataPath property has been superceded by the DataPath parameter of the Connect method.

The IRdaTable DataPath property is no longer used.

DirectAccess Property

Returns an IRdaDirectAccess object for the IRdaTable object. Read only.

Syntax:

IRdaDirectAccess := IrdaTable.DirectAccess;

See the documentation on IrdaDirectAccess.

Empty Property

Returns a Boolean value indicating whether the table is empty. Read only.

Syntax:

blnTableEmpty := IrdaTable.Empty;

Eof Property

Returns a Boolean value indicating whether the current record is the last record in the table. Read

only.

FileName Property

Returns or sets the name of the file used by IRdaTable table directly. This property can

sometimes be used to access a file that is not normally exposed by RDA2.

Syntax:

IRdaRTable.FileName := strFileName;

or

strFileName := IrdaRTable.FileName;

strFileName is a string variable.

CAUTION: When using this property to set the file name, the file itself must match the schema

of the currently open table. Setting the FileName property incorrectly can have catastrophic

and/or unpredictable results.

History Property

Returns an IRdaHistory object for the table. Read only. (See IRdaHistory).

Syntax:

IRdaHistory := IRdaTable.History;

Remarks:

Not every table supports the IRdaHistory object. IRdaHistory objects can only be created for the

Invoices, Former Vouchers, Pending Vouchers, ASN Vouchers, Memos and Slips tables.

IndexCount Property

Returns the number of indexes for a table as a long integer. Read only.

Syntax:

lngIndexCount := IRdaRTable.IndexCount;

IsRecordDeleted Property

Returns a Boolean value indicating whether or not a record in the table is marked for deletion.

Read only. Applies only to tables that are using ‘Default Order’ as the active index. (See

ActiveIndexID and ActiveIndexName properties.)

Syntax:

blnRecordDeleted := IRdaTable.IsRecordDeleted;

Remarks:

When using the ‘Default Order’ as the active index for a table, all records from the database are

included in the table. Due to the way the Retail Pro database operates, records that are marked for

deletion, but not yet actually deleted, could be included in the table. IsRecordDeleted will be true

Name Property

No longer used in RDA2.

NoSequences Property

Indicates whether RetailPro is using sequenced numbers for receipts, sales orders, etc. Returns a

boolean value. Read only.

Syntax:

blnNoSeq := IRdaTable.NoSequences;

Remarks:

If sequence numbers are not being used, NoSequences returns True. If sequence numbers are

being used, NoSequences returns False.

UseBlockReadWrite Property

Returns or sets the block read/write flag.

Syntax:

IRdaTable.UseBlockReadWrite := True | False;

or

blnUseBlock := IRdaTable.UseBlockReadWrite;

Remarks:

Setting UseBlockReadWrite to True can result in faster read and write times when reading an

entire table using IRdaDirectAccess. In general, UseBlockReadWrite should be set to False.

Close Method

Closes a table. Setting the Active property to False will also close the table.

Syntax:

IRdaTable.Close

Document Method

Returns the IRdaDocument object for the table. (See IRdaDocument).

Syntax:

IRdaDocument = IRdaTable.Document;

EraseRecord Method

Deletes the current record of the IRdaTable.

Syntax:

IRdaTable.EraseRecord;

Remarks:

Although the record is erased, the current position in the IRdaTable object does not change as a

result of invoking EraseRecord. In other words, the Bookmark value remains the same after the

EraseRecord method is invoked and the field values are available until the current record position

in the table is changed.

Find Method

Searches the current active index for a key value and returns a boolean value indicating whether

the record was found or not. Example.

Syntax:

blnFound := IRdaTable.Find(FindValue, ExactMatch);

Parameters:

FindValue – a string expression containing the key value to find.

ExactMatch – boolean – Setting ExactMatch to True causes RDA2 to locate the key that matches

FindValue exactly. See remarks.

Remarks:

If the key value is found, Find returns True and the current record is positioned to the found

record. If the index value is not found, Find returns false and the current record is unchanged.

Find does not operate as a filter on the RDA table. Find attempts to find the first record that

matches the FindValue. Find will not operate on indexes that do not have unique values.

In general, ExactMatch should be set to False when using this method. The actual structure of the

RPro index keys makes it difficult to construct a FindValue that will exactly match an RPro key.

First Method

Positions the current record at the first record of the table based on the active index.

Syntax:

IRdaTable.First;

Remarks:

Last Method

Positions the current record at the last record of the table based on the active index.

Syntax:

IRdaTable.Last;

Remarks:

Invoking the Last method will also set the Eof property to true.

NewRecord Method

Creates a new record in the table. Example.

Syntax:

IRdaTable.NewRecord;

Remarks:

NewRecord is used only to create a new row in the table represented by the IRdaTable object.

NewRecord does not update the data file itself. The PostRecord method is used to update the data

file.

Immediately after NewRecord is called, the table’s Bookmark property will be 0. The Bookmark

property will contain the Bookmark of the new record after the PostRecord method is called. If

PostRecord is never called, the table is not updated.

If the current position of the table is changed after the NewRecord method is called but before

PostRecord is called, the results are unpredictable and the table (and data file) may be corrupted.

The recommended procedure is to call NewRecord, set all necessary fields and call PostRecord.

Next Method

Positions the current record to the next record of the table based on the active index.

Syntax:

IRdaTable.Next;

Remarks:

Invoking the Next method when the Eof property is true has no effect.

Open Method

Opens the table and positions the current record to the first record based on the default index for

the table. (See Table Indexes).

PostRecord Method

Updates the current row of the table in the database. If the NewRecord method is called and the

current row is a new row for the table, then PostRecord inserts the new row into the database.

Example.

Syntax:

IRdaTable.PostRecord;

Remarks:

The current active row of the table (and the Bookmark property) do not change as a result of

calling PostRecord. PostRecord causes all fields of the table to be updated.

In some instances, the record position after calling PostRecord may be lost. This can lead to

problems if you are, for example: iterating through a table and making changes to several records

in a row. If you run into this problem a way of solving it is to save the Bookmark property

immediately before calling PostRecord and resetting it to the saved value immediately afterwards.

Prior Method

Positions the current record to the prior record of the table based on the active index.

Syntax:

IRdaTable.Prior;

Remarks:

IRdaHistory Interface

IRdaHistory objects are created using the History property of IRdaTable.

Data in the RPro database is stored on a month/year basis. When opened, an IRdaTable points to

the most current month/year in the RPro database. The IRdaHistory object is used to manipulate

the month/year setting so that history data can be accessed by the IRdaTable object.

Use the IRdaHistory Month and Year properties to determine the month/year currently set for the

IRdaTable object. Use the SetMonthYear method to change the month/year for the IRdaTable

object.

Not every table supports the IRdaHistory object. IRdaHistory objects can only be created for the

Invoices, Former Vouchers, Pending Vouchers, ASN Vouchers, Memos and Slips tables.

Properties and Methods

Month Property – Returns the current month setting.

Year Property – Returns the current year setting.

SetMonthYear Method – Sets a new month/year.

Month Property

Returns the history month as a long integer. For a table that is opened on the current RPro

database, the Month property will contain the current month. Read only.

Syntax:

lngMonth := IRdaHistory.Month;

Year Property

Returns the history year as a long integer. For a table that is opened on the current RPro database,

the Year property will contain the current year. Read only.

Syntax:

SetMonthYear Method

Sets the IRdaTable to a history month and year. The table MUST be closed before using this

method.

Syntax:

IRdaHistory.SetMonthYear(Month, Year);

Parameters:

Month – the month number (1 to 12) as a long integer.

Year – the Year number (ex. 2000) as a long integer.

Remarks:

Setting the history month and year to a month and year that don’t exist does NOT generate an

error condition. Errors are not generated until an attempt is made to read the table data.

You can use the IRdaTable.FileName property to verify whether the selected data file actually

exist before trying to open the table.

IRdaDirectAccess Interface

Provides a means of directly accessing the record count and number of an IRdaTable and

changing the active record of an IRdaTable. (See IRdaTable DirectAccess Property).

Properties and Methods

RecordCount Property – Returns the number of records in a table.

RecordNumber Property – Returns the current record number (bookmark).

GoToRecord Method – Sets the current record of the table.

RecordCount Property

Returns the number of records in a table as a long integer. Read only.

Syntax:

lngRecCount := IRdaDirectAccess.RecordCount;

Remarks:

RecordCount is only valid for tables that have ‘Default Order’ as an index and only when

‘Default Order’ is the active index on the table. Otherwise, RecordCount will return a –1. (See the

ActiveIndexID property and the section on Table Indexes).

RecordNumber Property

Returns the current record number of the table as a long integer. Read only.

Syntax:

lngRecNumber := IRdaDirectAccess.RecordNumber;

Remarks:

The value returned by RecordNumber will be affected by using any of the table positioning

methods (First, Last, Next or Prior). The record number returned is identical to the IRdaTable

Bookmark property.

GoToRecord Method

Sets the current record of the IRdaTable and returns a boolean value indicating whether the

current record was set or not.

Syntax:

blnGoTo := IRdaDirectAccess.GoTo(lngRecNumber);

Parameters:

lngRecNumber – the record number expressed as a long integer. (Identical to the Bookmark value

of the IRdaTable object).

Remarks:

The GoToRecord method can only be used with tables that have ‘Default Order’ as an index and

only when ‘Default Order’ is the active index. Otherwise, GoToRecord will always return false

and the current record of the table will not be changed. (See the ActiveIndexID property and the

section on Table Indexes).

IRdaDocument Interface

The IRdaDocument object can be used to manipulate the fields in an IRdaTable. IRdaDocument

objects are created using the Document method of IRdaTable and are linked to the IRdaTable

object.

IRdaField objects are instantiated using the FieldByID and FieldByName methods of

IRdaDocument.

Nested documents (see Nested Documents) are created using the NestedDocByID and

NestedDocByName properties of IRdaDocument.

Some methods of the IRdaDocument (DesyncDetected, ResyncPosition,

ResyncToLastSetPosition, RefreshDocument, and RefreshProvider) are only functional when

called from inside a Retail Pro plugin.

Properties and Methods

Add2XMLNode Method – Adds a node to an XML document.

AllFieldNames Property – Returns a list of all field names in the current document.

AllNestedDocNames Property – Returns a list of all nested document names in the current

document.

Count Property – Returns the number of records in a nested document.

CustomInterface Property – Creates an IRdaTender or IRdaVouTerms object.

DescriptiveInfo Property – Returns an XML document containing field descriptions.

DesyncDetectedMethod – IRdaField and IRdaDocument (nested) data providers are

desynchronized.

EditMode Property – Reads or sets whether Retail Pro has the current document in editable mode

or not.

FieldByID Method – Creates an IRdaField object.

FieldByName Method – Creates an IRdaField object.

GetBoolean Method – Returns the value of a field with datatype boolean.

GetDateTime Method – Returns the value of a field with datatype date.

GetDouble Method – Returns the value of a field with datatype double.

GetInteger Method – Returns the value of a field with datatype integer.

GetString Method – Returns the value of a field with datatype string.

GetSubDouble Method – Returns the value of a double datatype field that can have multiple

values.

NestedDocByName Property – Creates an IRdaDoucment object for a nested document.

NoInventoryLookups Property – Disables lookup of extended item information on nested item

documents.

RefreshDocument Method – Refreshes the values in the UI with data from the IRdaDocument

data provider.

RefreshProvider Method – Forces the IRdaDocument to update its values with the data currently

in the UI.

ResyncPosition Method – Forces the IRdaDocument (nested) position to be the same as the UI

position.

ResyncToLastSetPosition Method – Forces UI position to be set to current IRdaDocument

(nested) position.

SaveToStream Method – Implements a method of copying an IRdaDocument.

SetBoolean Method – Sets the value of a field with datatype boolean.

SetDateTime Method – Sets the value of a field with datatype date.

SetDouble Method – Sets the value of a field with datatype double.

SetInteger Method – Sets the value of a field with datatype integer.

SetPosition Method – Sets the current record of a nested document.

SetString Method – Sets the value of a field with datatype string.

SetSubDouble Method – Sets the value of a double datatype field that can have multiple values.

XMLDOMDocument Method – Returns an XML document representing the current record.

XMLSchema2Dir Method – Saves the XML schema of a document to a file.

Add2XMLNode Method

Adds a node to an XML document. The method is not used to write any information to the RPro

database. This method could be used to add nodes to an existing XML document to include

additional information prior to exporting the document to another system.

Syntax:

IRdaDocument.Add2XMLNode(XMLNode, IncludeSchemaTag);

Parameters:

XMLNode – IXMLDOMNode object – the XML node to be added to the XML document.

IncludeSchemaTag – boolean – If true, the schema tag is added along with the node. If false, no

schema tag is added.

AllFieldNames Property

Returns a list of all the field names contained in the IRdaTable. The list is returned as an

IRdaCollection object. Read only.

Syntax:

Set FieldList = IRdaDocument.AllFieldNames

AllNestedDocNames Property

Returns a list of all the IRdaDocuments nested within the current IRdaDocument. The list is

returned as an IRdaCollection object. Read only.

Syntax:

NestedDocumentNames := IRdaDocument.AllNestedDocNames;

Count Property

Returns or sets the number of records in a nested document. (See Nested Documents.) Example.

Syntax:

lngNestCount := IRdaDocument.Count;

or

IRdaDocument.Count := lngRecCount;

CustomInterface Property

Returns an IRdaTender or IRdaVouTerms object. The returned object depends on the table that

was used to create the IRdaDocument object. Read only.

Syntax:

Object := IRdaDocument.CustomInterface;

Remarks:

CustomInterface applies to IRdaDoucment objects created from IRdaTable objects and

IRdaDocuments created as nested documents from existing IRdaDocuments.

If the IRdaDocument was created from an IRdaTable for the Invoices table or is a SODeposit

nested document of the SOs table, CustomInterface returns an IRdaTender object.

If the IRdaDocument was created from an IRdaTable object for the POs table, CustomInterface

returns an IRdaVouTerms object. Example.

If the IRdaDocument was created as the SODeposit nested document from an IRdaTable object

for the SOs table, then CustomInterface returns an IRdaTender object.

DescriptiveInfo Property

Returns a DOMDocument object (XML) that contains descriptions for the fields in the

IRdaTable. Read only.

Syntax:

xmlDescripInfo := IRdaDocument.DescriptiveInfo;

Remarks:

The DOMDocument returned by DescriptiveInfo is not a complete table schema. The XML

document returned by DescriptiveInfo consists of a FIELDS node with a child FIELD node for

every field in the table. The FIELDS node has a COUNT attribute with the number of fields in

the table. Each child FIELD node has the CAPTION, ID and TYPE attributes. (See Sample

Descriptive Info Document.) Note: DOMDocument is a class of MSXML.dll.

DeSyncDetected Method

Sometimes when accessing nested documents from within a plugin you will end up with a state

where the IRdaDocument data provider and the IRdaField data provider are pointing to different

records in the nested table.

DesyncDetected returns True if this is the case.

Syntax:

blnProvidersOutOfSync := IRdaDocument.DesyncDetected;

Remarks:

This method is only meaningful when called from within a plugin, and then only if the current

document is a nested document. Use this method before calling ResyncPosition or

ResyncToLastSetPosition to avoid uneccessary resynchronization calls.

EditMode Property

Sets or returns whether Retail Pro has the current document in editable mode or not. This is useful

for example to enable a side button plugin only if current document is in edit mode.

Syntax:

blnDocEditable := IRdaDocument.EditMode;

or

IRdaDocument.EditMode := True | False;

Remarks:

FieldByID Method

Returns an IRdaField object for a table field specified by the field ID number.

Syntax:

IRdaField := IRdaDocument.FieldByID(ID);

Parameters:

ID – long - the field ID number.

Remarks:

The field ID must be for a field that is part of the IRdaTable. You cannot create an IRdaField

object for fields that are not in the IRdaTable object linked to the IRdaDocument. FieldByID

cannot be used for fields in nested documents.

Do not use field names with the FieldByID method. Field ID numbers are enumerated in the

RDA2 library - see Field ID Constants.

FieldByName Method

Returns an IRdaField object for a table field specified by the field name. Example.

Syntax:

IRdaField := IRdaDocument.FieldByName(Name);

Parameters:

Name – string - the field name. Case-sensitive.

Remarks:

The field name must be a field that is in the IRdaTable. You cannot reference fields that are not in

the IRdaTable. FieldByName cannot be used for fields in a nested document. The name

parameter is case sensitive and must match the field name in the RDA2 table schema.

See the RDA2 Table Schema for the list of field names in each table. Field names can also be

obtained by using the AllFieldNames property of IRdaDocument. Do not use field ID constants

with the FieldByName method.

GetBoolean Method

Returns the value of an IRdaDocument field with type boolean as a boolean.

Syntax:

Boolean := IRdaDocument.GetBoolean(FieldID, IsNull);

Parameters:

FieldID - long integer - the field ID number.

IsNull – boolean - True if the value is null, otherwise False.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to access the value of fields with type

boolean.

GetDateTimeMethod

Returns the value of an IRdaDocument field with type datetime as a datetime.

Syntax:

DateTime := IRdaDocument.GetDateTime(FieldID, IsNull);

Parameters:

FieldID - long integer - the field ID number.

IsNull – boolean - True if the value is null, otherwise False.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to access the value of fields with type

datetime.

GetDouble Method

Returns the value of an IRdaDocument field with type double as a double.

Syntax:

Double := IRdaDocument.GetDouble(FieldID, IsNull);

Parameters:

FieldID - long integer - the field ID number.

IsNull – boolean - True if the value is null, otherwise False.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

GetInteger Method

Returns the value of an IRdaDocument field with type integer as an integer.

Syntax:

Integer := IRdaDocument.GetInteger(FieldID, IsNull);

Parameters:

FieldID - long integer - the field ID number.

IsNull – boolean - True if the value is null, otherwise False.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to access the value of fields with type integer.

GetString Method

Returns the value of an IRdaDocument field with type string as a string.

Syntax:

String := IRdaDocument.GetString(FieldID, IsNull);

Parameters:

FieldID - long integer - the field ID number.

IsNull – boolean - True if the value is null, otherwise False.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to access the value of fields with type string.

GetSubDouble Method

Some fields in the Retail Pro database can contain “multiple” values (i.e. fields that have different

values by stores number or price level). GetSubDouble allows you to designate which one of the

available values is returned. For example, for installations with multiple stores, inventory

quantities will be stored by store number. The GetDouble method would return the quantity for

the store running the application using RDA2. GetSubDouble can return the value for any of the

stores. Values are returned as data type double.

Syntax:

Double = IRdaDocument.GetSubDouble(FieldID, SubID, IsNull);

Parameters:

FieldID – long integer – the ID number of the field.

LoadFromStream Method

Loads a previously saved stream (variant). Equivalent to pasting a new document object into the

IRdaDocument.

Syntax:

IrdaDocument.LoadFromStream(Stream);

Parameters:

Stream – a variant created using the SaveToStream method of IRdaDocument.

Name Property

Returns the name of the IRdaDocument object as a string. Read only.

Syntax:

Name := IRdaDocument.Name;

NestedDocByID Property

Returns the IRdaDocument object for a nested document using the nested document’s ID number.

Read only.

Syntax:

NestedIRdaDocument := IRdaDocument.NestedDocByID(ID);

Parameters:

ID – a long integer representing the ID number of the nested document.

Remarks:

Not all IRdaDocument objects will return nested documents. Whether or not an IRdaDocument

object will return nested documents depends on the IRdaTable to which it is attached. Nested

documents exist in IRdaDocument objects linked to the Invoices, POs, SOs, Former Vouchers,

Pending Vouchers, ASN Vouchers, Memos or Slips tables. (See Nested Document Names and ID

Numbers).

NestedDocByName Property

Returns the IRdaDocument object for a nested document using the nested document’s name.

Read only. Example.

Syntax:

NestedIRdaDocument := IRdaDocument.NestedDocByName(NestedDocName);

Parameters:

NestedDocName – string – the name of the nested document.

See the Remarks in the NestedDocByID Property section above. (See NestedDocByNames and

NestedDocByID properties).

NoInventoryLookups Property

Prevents nested items documents (ReceiptItems, SOItems, etc.) from looking up the extended

item information from inventory when loading. This means that only basic item information will

be available however it will result in a significant performance increase if iterating through many

nested item documents.

Syntax:

blnNoInventoryLookups := IRdaDocument.NoInventoryLookups;

or

IRdaDocument.NoInventoryLookups := True | False;

Remarks:

See the RDA2 Table Schema Documentation for information regarding which fields are basic vs.

extended item information.

RefreshDocument Method

The RefreshDocument method allows a plugin to force the Retail Pro UI to update its values

based on the data currently in the IRdaDocument data provider. This is useful when a plugin has

written information to the current IRdaDocument but it does not trigger Retail Pro to update its

UI automatically.

Syntax:

IRdaDocument.RefreshDocument;

Remarks:

RefreshProvider Method

This method is the opposite of RefreshDocument, it will force the values in the Retail Pro UI to

be saved to the IRdaDocument data provider.

Syntax:

IRdaDocument.RefreshProvider;

Remarks:

This method is only useful in plugins. Be careful with calling this method since it can force an

update of the current document. This can lead to unexpected results, especially when the current

document is new and unfinished.

ReSyncPosition Method

The ResyncPosition method allows a plugin to resynchronize the positions of the IRdaField (UI)

and IRdaDocument on a nested document. This method will force the IRdaDocument position to

move to the IRdaField (UI) position.

Syntax:

IRdaDocument.ResyncPosition;

Remarks:

This method is only useful in plugins. This method can be time consuming, make sure to use

DesyncDetected to verify that it is really necessary to resynchronize first.

Example:

if IRdaDocument.DesyncDetected then

IRdaDocument.ResyncPosition;

ReSyncToLastSetPosition Method

The ResyncToLastSetPosition method allows a plugin to resynchronize the positions of the

IRdaField (UI) and IRdaDocument on a nested document. This method will force the IRdaField

and the highlighted position in the Retail Pro UI to move to the position selected in the last call

to SetPosition.

Syntax:

IRdaDocument.ResyncToLastSetPosition;

Remarks:

This method is only useful in plugins. This method can be time consuming, make sure to use

DesyncDetected to verify that it is really necessary to resynchronize first.

Example:

if IRdaDocument.DesyncDetected then

IRdaDocument.ResyncToLastSetPosition;

SaveToStream Method

Returns the current document in IRdaDocument as a variant.

Syntax:

Variant = IrdaDEocument.SaveToStream();

Remarks:

The SaveToStream and LoadFromStream methods provide a means of copying and pasting a

document from and to the IRdaDocument object. The variant returned by SaveToStream should

not be used for any other purpose.

SetBoolean Method

Sets the value of an IRdaDocument field with type boolean.

Syntax:

IRdaDocument.SetBoolean(Value, FieldID);

Parameters:

Value – boolean – New value for the field.

FieldID – long integer - the field ID number.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to set the value of fields with type boolean.

SetDate/Time Method

Sets the value of an IRdaDocument field with type date.

Syntax:

IRdaDocument.SetDate(Value, FieldID);

Parameters:

Value – date – New value for the field.

FieldID – long integer - the field ID number.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to set the value of fields with type date.

SetDouble Method

Sets the value of an IRdaDocument field with type double. Example.

Syntax:

IRdaDocument.SetDouble(Value, FieldID);

Parameters:

Value – double – New value for the field.

FieldID – long integer - the field ID number.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to set the value of fields with type double.

SetInteger Method

Sets the value of an IRdaDocument field with type integer.

Syntax:

IRdaDocument.SetBoolean(Value, FieldID);

Parameters:

Value – integer – New value for the field.

FieldID – long integer - the field ID number.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to set the value of fields with type integer.

SetPosition Method

Sets the “current record” position of an IRdaDocument object. Example.

Syntax:

IrdaDocument.SetPosition(RecNum);

Parameters:

RecNum – long integer – “record” number.

Remarks:

SetString Method

Sets the value of an IRdaDocument field with type string. Example.

Syntax:

IRdaDocument.SetBoolean(Value, FieldID);

Parameters:

Value – string – New value for the field.

FieldID – long integer - the field ID number.

Remarks:

This method can be used with “regular” and nested IRdaDocument objects. For nested

IRdaDocument objects, this method is the only way to set the value of fields with type integer.

SetSubDouble Method

Some fields in the RPro database can contain “multiple” values (for example, fields that have

different values by stores number or price level). SetSubDouble allows you to designate which of

the multiple values is being set. See GetSubDouble for additional information.

Syntax:

IRdaDocument.SetSubDouble(Value, FieldID, SubID);

Parameters:

Value – double – the new field value.

FieldID – long – the ID number of the field.

SubID – long – an integer value indicating which one of the multiple values to return. SubID is

zero based.

XMLDOMDocument Method

Returns an XML document representing the current record of the IRdaDocument object.

Syntax:

xmlDoc := IrdaDocument.XMLDOMDocument(IncludeSchemaTag);

Parameters:

IncludeSchemaTag – boolean – If True, the schema tag is included in the XML document. If

False, the tag is not included.

Remarks:

xmlDoc is an DOMDocument object (member of the MSXML class). The XML document

returned by this method contains a single element node whose attribute values are the values of

the fields in the IRdaDocument object. Valid for “regular” and nested IRdaDocuments.

XMLSchema2Dir Method

Writes the schema for a table or nested document to an XML Document file and returns the name

of the output file.

Syntax:

OutputFileName := IRdaDocument.XMLSchema2Dir(DirName, FullData);

Parameters:

DirName – a string expression containing the directory name for the output.

FullData – a boolean value that determines the scope of the output. If FullData is set to False,

only the XML field name and data type are included in the schema. If FullData is set to True, the

schema includes the XML field name, data type, label (equivalent to caption of the IRdaField

object), description and length.

IRdaField Interface

IRdaField objects are created using the FieldByID and FieldByName methods of the

IRdaDocument object. An IRdaField object can be created for each field of the IRdaDocument.

Properties and Methods

Caption Property – Returns the field caption.

Description Property – Returns the description of a field.

FieldType Property – Returns the datatype of the field.

ID Property – Returns the field ID number of a field.

LookupList Property – Returns the list of available values for fields with preset values.

Name Property – Returns the name of a field as a string.

Size Property – Returns the size of a field in bytes.

Value Property – Returns or sets the value of a field.

Text Method – Returns the value of a field as a string representation.

Caption Property

Returns the caption used for the field as a string value. (The caption is the short description for

the field and is used in Retail Pro as column headings in grids). Read only.

Syntax:

Caption := IrdaField.Caption;

Description Property

Returns the description used for the field as a string value. Read only.

Syntax: