Copyright: SFREP


DDE Help
Contents

Dynamic Data Exchange:  General Concepts

Communicating between Processes

DDE Conversations

Conversational Exchanges

Appraise-It in DDE Exchanges

Providing Appraise-It Data to Other Applications

Writing the DDE Macro

Writing Macros

Introduction

Response Database Macros

Macro Files

Customizing Appraise-It Using Macros

Introduction

Custom Commands

Using Macros to Provide Custom Commands

Appraise-It Macro Language

Introduction

Variables

User Information

Keywords

Cell Representation

Special Syntax

Operators

Procedures, Functions, and Sub Procedures


Communicating between Processes

When working in a Windows environment, a whole new world opens up, with seemingly limitless possibilities.  Information from one program may be linked to another program.  This information may consist of an appraisal, a spreadsheet, a photo image, a map, a sketch, communications data, or any Windows program information.

Without leaving your desk, it is possible to link together an appraisal report, subject photo, map, sketch, an individual invoice, plus a monthly statement spreadsheet, and fax the information to a client.

Dynamic Data Exchange provides the medium through which data can be exchanged between application programs or processes.  This means, for example, that information from an Appraise-It  report may be linked to a letter in Microsoft® Word, a monthly statement in Microsoft® Excel, and then faxed to a client via Delrina WinFAX Pro.


DDE Conversations

The Conversation Relationship:  Clients & Servers

Before the Conversation is Initiated

Appraise-It ServiceName, TopicName, and ItemName

ServiceName, TopicName and ItemName for Other Applications

Initiating and Terminating the Conversation


The Conversation Relationship:  Clients & Servers

The relationship between the application programs that are sharing information is called a conversation.  Conversations occur between clients and servers.  The client is the requester and receiver of the shared information.  The server provides the information to the client.  Appraise-It is an application program that may act as both a client and a server, in other words, both requesting and providing information.


Before the Conversation is Initiated

To initiate a DDE conversation, the client and server applications need to know where to locate the information to be exchanged, and how it is to retrieved.  The directions to the information are provided to the server application program in Basic code instructions.  There are three main components to these directions:  ServiceName, TopicName, and ItemName.  When using Appraise-It, you will typically provide the Basic instructions in the form of a macro written in one of Appraise-It's response databases.


Appraise-It ServiceName, TopicName, and ItemName

Item	Description
ServiceName	TRA
TopicName	Full path of report
ItemName	Form Name | Line # | Field # across
The ServiceName for Appraise-It is simply TRA.  The TopicName is the full drive, directory, and file name for the report from which you wish to retrieve information.  For example, if you have a report named Sample.RPT located in the TRADATA\DATA directory of your C drive, the TopicName is C:\TRADATA\DATA\SAMPLE.RPT.

The ItemName is determined by the form name and the field location as indicated by the line number and the location of the field across the line.  For example the first field on line 4 is 4|1.  The next field on line 4, reading across from left to right is 4|2.

Related Topics:

Form Names

Field Locations

An Example of ServiceName, TopicName, and ItemName


Form Names

A complete listing of the Form Name for Appraise-It reports and addenda is available in the TRA.INI file located in the Windows directory.  Simply scroll down to the section under [Descriptions].


Field Locations

Appraise-It provides a macro that makes the determination of ItemName locations fast and simple.

1.	Start Appraise-It.

2.	Open a new report.

3.	Strike Ctrl+M simultaneously.  The TRA macro filename dialog box appears.

4.	Type print.bas.

5.	Choose OK.

6.	Notice that the field location numbers appear in the fields of the report.

Note:  If the locations do not appear, check to make sure that Auto Cell Transfer (Options:  Advanced menu) is checked.


An Example of ServiceName, TopicName, and ItemName

To provide the Property Address from the URAR, which is located on line 4, field 1 across, from a report located at C:\TRADATA\DATA\SAMPLE.RPT, use this information:

ServiceName = TRA

TopicName = C:\TRADATA\DATA\SAMPLE.RPT

ItemName = "ua2" | 4 | 1


ServiceName, TopicName and ItemName for Other Applications

It is not within the scope of this documentation to provide DDE information for other Windows applications.  Refer to the documentation or technical support for the specific application, or Microsoft® Windows for further information.

When searching other documentation for ServiceName, TopicName and ItemName, it is possible that the other application may use different terms for this identification system.  In general, the three terms refer to three levels within the application program.  The ServiceName may be the application name or an abbreviation for the application name, but this is not an absolute requirement.  The TopicName further defines the application.  The ItemName identifies the details within the topic name which are to be exchanged.


Initiating and Terminating the Conversation

Once you know the ServiceName and TopicName for the application with which you wish to exchange information, you are ready to initiate (and then terminate) the conversation.  See Providing Appraise-It Data to Other Applications, for examples of macros written to exchange information between Appraise-It and other application programs.  Included as part of the Appraise-It macro is a Shell command which checks to see if the other application is open.  See Shell (filename of application) for additional information on this command.  However, the actual conversation is initiated through the DDEInitiate command and terminated through the DDETerminate command.

Related Topics:

DDEInitiate (ServiceName-string, TopicName-string) DDETerminate (expression)


DDEInitiate (ServiceName-string, TopicName-string)
DDETerminate (expression)

The DDEInitiate command starts the conversation between the two programs and provides a channel through which the conversation occurs.  The ServiceName is unique for the particular application program.  The TopicName identifies the individual drive and path information for your files on your system.  The DDETerminate command ends the conversation specified by the expression for the channel.

Word for Windows Example:
ChanNumber! = DDEInitiate("WinWord", "c:\\cpp\\doc\\testdde.doc")
. . .
DDETerminate(ChanNumber!)

Microsoft® Excel Example:
ChanNumber! = DDEInitiate("Excel", "c:\\excel\\xlddetst.xls")
. . .
DDETerminate(ChanNumber!)

WordPerfect® for Windows Example:
ChanNumber! = DDEInitiate("WordPerfect", "Commands")
. . .
DDETerminate(ChanNumber!)

The examples above use a single variable for the channel number and specify the DDEInitiate command with ServiceName and TopicName.  Notice that for Word and Excel, the path requires double back-slashes (\\) to separate components.  Notice also that the TopicName for WordPerfect for Windows DDE conversations uses a slightly different syntax by specifying "Commands" as the TopicName.  The DDETerminate command uses the variable expression for the channel number to terminate the conversation.


Conversational Exchanges

After the conversation is initiated, the data exchange can occur.  There are several means by which data exchanges can happen.

Related Topics:

DDE Request

DDE Poke

DDE Execute


DDE Request

For situations in which the client application requests data from the server application, a DDERequest command may be used.  The data requested may be specific information from an individual field, or information such as the number of currently open reports, the identification of the current user, or the addenda included in a current report.

Related Topics:

DDERequest(expression,TopicName-string)

DDERequest with TopicName as Query

Request Items


DDERequest(expression,TopicName-string)

Requests information from the server via the channel in the first parameter, from the location specified by the TopicName string in the second parameter.

WordBasic Example:
Sub MAIN
ChanNumber = DDEInitiate("TRA", "c:\cpp\tradata\data\pugh.rpt")
a$ = DDERequest$(ChanNumber, "ua2|4|1")
b$ = DDERequest$(ChanNumber, "ua2|159|1")
Insert a$
Insert b$
DDEExecute ChanNumber, "[RunMacro(  ScrollToLine(110)  )]"
DDETerminate(ChanNumber)
End Sub

The example above requests the information from fields 4|1, and 159|1 in the URAR (the property address and market value conclusion) and assigns the data to the string variables a$ and b$ respectively.  Note the placement of the quotations on the second parameter.  This placement is in accordance with WordBasic syntax, since Word is the client and Appraise-It is the server in this example.


DDERequest with TopicName as Query

Sends a Query request to the server.  Currently, the only available option for the Query TopicName is "ActiveReports".

WordBasic Example:
ChanNumber! = DDEInitiate( "TRA", "Query" )
DDERequest$( ChanNumber!, "ActiveReports" )
DDETerminate(ChanNumber!)

The WordBasic example above uses DDEInitiate with "Query" as TopicName to start the DDE conversation.  Then a DDERequest is sent to TRA (as the server) to provide information about the currently open reports (ActiveReports).  The conversation is terminated with a DDETerminate command.

Paradox® Example:
method pushButton(var eventInfo Event)
var
   d1, d2 DDE
   active, active2 AnyType
endVar

d1.open( "tra", "Query" )
d1.setItem( "ActiveReports" )
active = d1
msgInfo( "ActiveReports = ", active )
d2.open( "tra", "c:\\cpp\\tradata\\skels\\ua2skel\\test.rpt", "ua2|3|1" )
active2 = d2
msgInfo( "By Position = ", active2 )
d1.close()
d2.close()
endmethod

The Paradox example above uses "Query" as the TopicName in an Open command, then provides a DDE Request (active = d1) with ActiveReports as the TopicName to return the currently open reports in Appraise-It, the server.


Request Items

Request:	TopicName	Information Returned:
ActiveReports	Query	A comma separated list of all open reports, with the active report as the first item in the list
FileNo	File Name	The file number of the active report
"formtype"|Line|Across	File Name	The contents of the cell on form of type "formtype", in the cell indicated by "Line|Across"
ListForms	File Name	A comma separated list of all addenda included in the active report
MajorForm	File Name	The form type of the major form of the active report, e.g. "ua2", "704", "eval"
UserID	File Name	The current user's ID for the active form


DDE Poke

Another situation occurs when the client application provides data to the server application.  The client can send the data to the server for the first time, or update information already sent to the server.  For this situation, use the DDEPoke command.

Related Topics:

DDEPoke (expression, Server-ItemName-expression, data-expression)


DDEPoke (expression, Server-ItemName-expression, data-expression)

Sends data via the channel specified in the first parameter, from the client application to the server application.  The second parameter is a string expression for the location in the server to which the data will be provided, which is the server ItemName.  The third parameter is a cell expression for the location in the client from which the data is taken.

Example:
DDEPoke(ChanNumber!, "Address", "ua2"|4|1)

The example above provides the information from the URAR, field 4|1, which is the property address, to a location in the server application (which is Word for Windows™ in this example) marked with the bookmark, "Address".  Note that the cell expression places quotes only around the form name, "ua2".  This is according to the syntax for Appraise-It's macro language., which is the client in this example.


DDE Execute

Another type of DDE exchange occurs when a client asks the server to execute a command, such as a macro.  In this situation, the appropriate command for the client to send to the server is DDEExecute.

Related Topics:

DDEExecute (expression, string)

Appraise-It Execute Items


DDEExecute (expression, string)

Sends a command to the server to execute.  The first parameter is the channel, the second parameter is a string expression for the command to be executed.  The second parameter is the command to be executed and may have an additional command with its own parameters nested within the original command.

WordPerfect Example:
DDEExecute(ChanNumber!, "MacroPlay(MacroName:amerge.wcm)")

Paradox Example:
DDEExecute(ChanNumber1, "[RunMacro(SplitScreen(\"pdoxwin.exe\",\"tra.exe\"))]

The examples above use DDEExecute to send a macro command to be executed.  WordPerfect syntax requires the command "MacroPlay(MacroName:filename for macro to be executed)".


Appraise-It Execute Items

Execute Syntax:	TopicName	Action
[RunMacro(- - - )]	File Name	Runs macro commands indicated by - - -.
[RunMacro(- - -.bas)]	File Name	Executes the macro commands in the file - - -.bas.


Providing Appraise-It Data to Other Applications

Just as it is necessary to determine the location in Appraise-It from which you are retrieving information, it is necessary to determine in the other application where the information will be retrieved.  The methods for this retrieval vary from application to application.  In general, you will want to insert the Appraise-It field at the location you wish in your other application.

Again, you should refer to your application's manual for information on how this is done for your specific application.


Writing the DDE Macro

Once you know where to locate the information you wish to retrieve from Appraise-It, and how to insert the information in your application, you are ready to write the DDE macro.

Related Topics:

An Example of a DDE Global Macro for Word

An Example of a DDE Global Macro for Excel

An Example of a DDE Global Macro for WordPerfect® for Windows


An Example of a DDE Global Macro for Word

Suppose you want to provide the property address and market value from the URAR to a document in Microsoft Word.  In your particular situation, you want to execute Word on the F drive, then open a document called TestDDE.Doc on the C drive, CPP directory, and DOC sub-directory.  Additionally, you want the Word bookmarks for the property address and market value to be called "Addrss" and "MktVal," respectively.  The actual macro for the Appraise-It global response database looks like this:

exe$ = "f:\\winword\\winword.exe c:\\cpp\\doc\\testdde.doc"

shell( exe$ )

ChanNumber! = DDEInitiate("winword", "c:\\cpp\\doc\\testdde.doc")

DDEPoke( ChanNumber!, "Addrss", "ua2"|4|1 )

DDEPoke( ChanNumber!, "MktVal", "ua2"|159|1 )

DDETerminate(ChanNumber!)

Each line of the macro breaks down as follows:

exe$ = "f:\\winword\\winword.exe c:\\cpp\\doc\\testdde.doc"

Provides the drive and full path for executing Word plus the drive and full path for the Word document you wish to open"

shell( exe$ )

Provides the full path as well as any other components to the command line.  Shell checks if the exe$ is currently running:  if the exe is not running, Shell starts it up; if the exe is currently running, Shell switches the focus to the specified exe.

ChanNumber! = DDEInitiate("winword", "c:\\cpp\\doc\\testdde.doc")

Provides a channel number for the conversation defined by DDEInitiate("winword", "drive and full path for Word document you wish to open.")

DDEPoke( ChanNumber!, "Addrss", "ua2"|4|1 )

DDEPoke( ChanNumber!, "MktVal", "ua2"|159|1 )

Provides (or pokes) to Word, via the channel number, to the Word "Bookmark" for the property address, the information specified in the "form name for URAR"|field location for property address.

Pokes to Word, via the channel number, to the Word "Bookmark" for the Market Value, the information specified in the "form name for URAR"|field location for market value.

In Word, the document which retrieves the DDE information would have Word Bookmarks inserted for Addrss and MktVal at the exact location to which the Appraise-It information should be provided.

For example:

Lender
Lender Address

Re:  (Insert Addrss Bookmark here)

Dear Lender:

As requested, the above property was duly inspected and found to have an estimated market value of $(Insert MktVal Bookmark here).

If you have any questions on the enclosed appraisal report, please do not hesitate to contact me.

Sincerely,

Each field of information from Appraise-It is transferred to Word via a DDEPoke command which includes the Appraise-It ItemName and a Word Bookmark name.  The Appraise-It ItemName provides the Appraise-It form name and field location for the information.  The Word Bookmark name is created to designate the location in the Word document for the Appraise-It information.

DDETerminate(ChanNumber!)

Finally, the DDE conversation is terminated using the DDETerminate command with the variable expression for the channel number.


An Example of a DDE Global Macro for Excel

Suppose you want to provide the borrower name and market value from the URAR to a document in Microsoft Excel.  In your particular situation, you want to execute Excel on the F drive, then open a worksheet called XLDDETST.XLS on the C drive, Excel directory.  Additionally, you want the Excel locations for the borrower's name and market value to be "R11C1" and "R11C5," respectively.  The actual macro for the Appraise-It global response database looks like this:

exe$ = "f:\\excel\\excel.exe c:\\excel\\xlddetst.xls"

shell( exe$ )

ChanNumber! = DDEInitiate("excel", "c:\\excel\\xlddetst.xls")

; addresses

DDEPoke( ChanNumber!, "R11C1", "ua2"|7|1 )

DDEPoke( ChanNumber!, "R11C5", "ua2"|160|1 )

DDETerminate( ChanNumber! )

Each line of the macro breaks down as follows:

exe$ = "f:\\excel\\excel.exe c:\\excel\\xlddetst.xls"

Provides the drive and full path for executing Excel plus the drive and full path for the Excel worksheet you wish to open"

shell( exe$ )

Provides the full path as well as any other components to the command line.  Shell checks if the exe$ is currently running:  if the exe is not running, Shell starts it up; if the exe is currently running, Shell switches the focus to the specified exe.

ChanNumber! = DDEInitiate("excel", "c:\\excel\\xlddetst.xls")

Provides a channel number for the conversation defined by DDEInitiate("excel", "drive and full path for Excel document you wish to open.")

DDEPoke( ChanNumber!, "R11C1", "ua2"|7|1 )

DDEPoke( ChanNumber!, "R11C5", "ua2"|160|1 )

Provides (or pokes) to Excel, via the channel number, to the Excel "cell reference location for borrower's name", the information specified in the "form name for URAR"|field location for borrower's name.

Pokes to Excel, via the channel number, to the Excel "cell reference location for market value", the information specified in the "form name for URAR"|field location for market value.

In Excel, the worksheet which is to receive the DDE information looks like this:

DDETerminate( ChanNumber! )

Finally, the DDE conversation is terminated using the DDETerminate command with the variable expression for the channel number.


An Example of a DDE Global Macro for WordPerfect® for Windows

In WordPerfect, the macro procedure is a little different.  One of the simplest methods to use with WordPerfect is to perform a file merge combining a WordPerfect primary merge file with a secondary merge file that contains the Appraise-It data.

To perform the merge, the Appraise-It data must first be written to a WordPerfect file.  This file with the Appraise-It data becomes the WordPerfect secondary merge file.  You will also need to create a primary merge file with field locations for the Appraise-It data.  Then a WordPerfect macro is executed which merges the secondary and primary WordPerfect merge files.  See your WordPerfect documentation for more information about creating merges.

Suppose you want to provide the street address and legal description from the URAR to a document in WordPerfect for Windows.  The Global Macro which you write for Appraise-It requires an Open # and Print # command to write the secondary merge file.  Next a DDEExecute command is sent to run the merge macro within WordPerfect.

The actual macro for the Appraise-It global response database which executes WordPerfect on your C drive, creates a secondary merge file called Amerge2, and then executes a WordPerfect macro called Amerge.WCM, looks like this:

shell("c:\\wpwin\\wpwin.exe")

Open "c:\\wpwin\\amerge2" for output as #1

Print #1, "Start Record"+Chr$(10)

Print #1, Char$(9)+Cell(4,1)+Chr$(10)

Print #1, Char$(9)+Cell(5,1)+Chr$(10)

Print #1, "End Record"

Close #1

ChanNumber! = DDEInitiate("WordPerfect", "Commands")

DDEExecute(ChanNumber!, "MacroPlay(MacroName:Amerge.WCM)")

DDETerminate(ChanNumber!)

The lines of the macro break down as follows:

shell("c:\\wpwin\\wpwin.exe")

Provides the drive and full path for executing WordPerfect.  Shell checks if the exe$ is currently running:  if the exe is not running, Shell starts it up; if the exe is currently running, Shell switches the focus to the specified exe.

Open "c:\\wpwin\\amerge2" for output as #1

Print #1, "Start Record"+Chr$(10)

Print #1, Char$(9)+Cell(4,1)+Chr$(10)

Print #1, Char$(9)+Cell(5,1)+Chr$(10)

Print #1, "End Record"

Close #1

Opens the WordPerfect secondary merge file and writes the Appraise-It data to it.  "Start Record" and "End Record" are used as record delimiters in the secondary merge file.  Char$(9) and Char$(10) are Tab and Carriage Return respectively, and are used as field delimiters in the secondary merge file.  After the secondary merge file is written, the file is closed.

ChanNumber! = DDEInitiate("WordPerfect", "Commands")

Provides a channel number for the conversation defined by DDEInitiate("WordPerfect", "Commands").

DDEExecute(ChanNumber!, "MacroPlay(MacroName:Amerge.WCM)")

Executes the WordPerfect macro, Amerge.WCM.  This macro looks like:

Note the embedded codes for the field delimiters in the Reveal Codes portion of the WordPerfect window.  The WordPerfect primary merge file looks like this:


Writing Macros - Introduction
Introduction

Appraise-It provides you with three avenues through which you may send Basic language instructions.  You may provide Basic instructions through macros written in the Common Response Database and the Global Response Database, or through Basic language macro files which you direct Appraise-It to access.  These macro files may be maintained in Appraise-It's TRA directory, or in another directory.


Response Database Macros

Writing Response Database Macros

The general instructions for writing a macro are similar for both the Common Response Database and the Global Database.

Related Topics:

To Write a Response Database Macro


To Write a Response Database Macro

1.	Have the Appraise-It report open.

2.	Choose Database:

•	For the Global Response Database, choose Database, then Global.

•	For the Common Response Database, choose Cell then Common Response.

3.	Select Add.

4.	Enter Clipboard Name, then OK.

5.	Enter macro.

6.	Check Macro checkbox.

7.	Select Hot Key, if desired.

8.	Choose OK.

See The User's Guide, Chapter 10: Macros, for detailed instructions on writing a macro for Appraise-It.  Additionally, Chapter 10 provides sample macros as well as a brief Basic command reference.


Macro Files

You may feel more comfortable working with separate macro files, instead of using Appraise-It's Response Databases.  If so, simply create macro files using your usual text editor.  Save your Basic instructions in these files and Appraise-It provides a quick method to retrieve them.

Related Topics:

Executing Macro Files


Executing Macro Files

Appraise-It allows you to access your macro files using Ctrl + M:

1.	Have the Appraise-It report open.

2.	Enter Ctrl + M.

3.	Enter path/filename for macro file.

•	If the macro is in the TRA directory, simply enter the filename.

•	If the macro is in a directory other than TRA, enter the path and filename.

4.	Choose OK.  Your macro is executed.


Customizing Appraise-It Using Macros - Introduction
Introduction

From the start, Appraise-It was designed to be a flexible component of an integrated forms processing system.  You can expect to see more and more standard component software evolving over the next few years.  This component software is easily integrated with other software applications.  Appraise-It supports many existing forms of component technology today.  Appraise-It's existing DDE capability, working together with an advanced macro language offers users complete data import and export capability to any DDE-enabled application.  Additionally, Appraise-It's customizable menu system allows you to add your company-specific macros directly to Appraise-It's menu.

When a new product is released that integrates data with Appraise-It, a simple addition to the TRA.INI file quickly gives the user instant access to this new product through Appraise-It's Tools menu.  The Tools menu is almost completely built from custom entries found in our TRA.INI file.  These customizations provide the integrating interfaces between our Windows products via macro language and DDE.  Tools like Microsoft Mail™ are enabled using our macro language's capability to register and call nearly any Dynamic Link Library.


Custom Commands

Custom Commands in TRA.INI

Before You Add the Custom Command

Adding a New Custom Command to the Tools Menu


Custom Commands in TRA.INI

The Tools menu as shown above is almost completely built from custom entries found in the Custom Command section of the TRA.INI file.

You may view and edit the existing custom commands in the TRA.INI file using your favorite text editor.

The entries in the Custom Commands section of the TRA.INI file are in the form:

TextIdentifier=MenuName,MenuText,BasicScriptFile,AcceleratorKey(optional)


Before You Add the Custom Command

Suppose you wanted to perform a type of cost analysis of your report data.

1.	Write a cost analysis routine using, for example, Microsoft Access™ or Excel™.

2.	Write an Appraise-It macro to pass the desired data from the report into the analysis routine via DDE.

3.	Perform the analysis, and if you wish, Poke the data back into your report.

4.	Decide whether you want to run the macro as a global or common response, or if you want to add the command to the Tools menu.


Adding a New Custom Command to the Tools Menu

1.	Save the macro script as a file, such as NEWTOOL.BAS.

2.	Open the TRA.INI file in your favorite text editor.

3.	Modify the Custom Commands section to include this line:

NewTool=Tools,Cost Analysis,NewTool.bas

where NewTool is the custom command, Tools is the menu the command appears on, Cost Analysis is the menu item, and NewTool.bas is the macro script file.

4.	Save the TRA.INI file.


Using Macros to Provide Custom Commands

Appraise-It's powerful macro language allows you to write effective scripts that will perform almost any type of task.  Macros can be implemented as common responses, global responses, or stand alone scripts that can be executed as menu items or by the Ctrl+M key combination.

Related Topics:

Suggested Uses for Macros


Suggested Uses for Macros

•	Use to register and call almost any Windows Dynamic Link Library, including any you write

•	Use to manipulate report data via DDE and internal referencing schemes

•	Use to add and retrieve any graphical images in a report

•	Use to execute any menu command

•	Use to write advanced scripts using FOR and WHILE loops

•	Use to provide built-in WritePrivateProfileString and GetPrivateProfileString functions

•	Use to provide Message Box function


Appraise-It Macro Language - Introduction
Introduction

The Appraise-It macro language is similar to other Basic languages with which you may be familiar.  At the same time, it contains many unique commands and identifiers which apply only to the Appraise-It program.  Once you are acquainted with these unique commands and identifiers, you will be well on your way to providing macros that accommodate your own specific circumstances.


Variables

Different variable structures are used to represent different data types.  The following are the Basic type representations used in this package:

Structure	Type	Example
identifier	real variable	ID
identifier$	string variable	ID$
identifier%	integer variable	ID%
identifier&	long variable	ID&
identifier!	single variable	ID!
identifier#	double variable	ID#


User Information

Information from Registration Procedure

Registering your Appraise-It product provides these variables:

Variable Name	Description of Information Provided During Registration Procedure
Company$(Name)	Company Name
Company$(Address1)	Company Address Line 1
Company$(Address2)	Company Address Line 2
Company$(Phone)	Company Phone Number
Company$(TaxID)	Company Tax ID Number
Appraiser$(Name)	Appraiser's Name (current user)
Appraiser$(ID)	Appraiser's ID Number (current user)
Appraiser$(License)	Appraiser's License # (current user)
Appraiser$(State)	Appraiser's State (current user)
Appraiser$(Expire)	Appraiser's License Expiration Date (current user)
Appraiser$(Certification)	Appraiser's Certification # (current user)


Keywords

Pre-defined Keywords

Some terms and variables are already defined in the language.  Here are the variables that are pre-defined in the language.

Related Topics:

Across

Checkbox

Keypress

Leave

Line

Multi

Multihandle

Single

Totallines


Across

Across represents the location of the current field, as numbered from left to right across the current line.


Checkbox

Checkbox is a field type identifier used to identify a checkbox.


Keypress

Keypress identifies when a key has been pressed on the keyboard.


Leave

Leave identifies that the editor has left a field location and may be used as the second parameter to a Call function.


Line

Line represents the vertical location of the current field, as determined by numbering the lines down from the top of the form.


Multi

Multi is a field type identifier used to identify a multi field.


Multihandle

Multihandle is a field type identifier used to identify any line but the first line of a multi-line field.


Single

Single is a field type identifier used to identify a single field.


Totallines

Totallines indicates the total number of lines in a report.


Cell Representation

A cell can be represented in different forms:

Current Form	Example
Cell ( expression, expression )	Cell(14, 1)
Cell ( string-type, expression, expression )	Cell("ua2", 14, 1)
integer-type | integer-type	14|1
string-type | integer-type | integer-type	"ua2"|14|1
Cell ( string-type | string-type )	Cell( " offscrn ", " File# " )
Related Topics:

Cell or Field


Cell or Field

Cell and field are used interchangeably to indicate an area in which information is stored or where calculations are done.  A field may be represented by two keyword variables:

•	Line indicates the line number of the field, or how far down from the top of the form the field is located.

•	Across indicates the location of the field as numbered across from left to right on the current line, or how many fields over from the left of the form the field is located.


Special Syntax

Single and Double Slashes

The  \  character is used to represent special of non-printable characters.

Use two slashes  \\  to represent a single slash character.

Example:
  "C:\\AUTOEXEC.BAT"


Operators

Math Operators

Comparison Operators

String Operators


Math Operators

Appraise-It supports these math operators:

Operator	Description
*	Multiplies
/	Divides
+	Adds
-	Subtracts
^	Raises the number to the power of the exponent


Comparison Operators

Appraise-It supports these operators which are used to compare expressions:

Operator	Description
<	Less than
>	Greater than
<=	Less than or equal to
>=	Greater than or equal to
<>	Not equal to


String Operators

Appraise-It supports these operators which are used in string concatenations, equivalencies, and comparisons.

Operator	Description
+	Concatenates
=	Equal to  (not case sensitive)
<>	Not equal to  (not case sensitive)


Procedures, Functions, and Sub Procedures

In general terms, procedures are portions of a program that perform tasks.  Functions are procedures that result in a value.  Sub procedures do not result in the return of a value.

Related Topics:

Pre-defined Functions


Pre-defined Functions

Appraise-It has certain functions which have already been defined.

Related Topics:

Abs (number-expression)

ActivateApp()

ActiveField (cell-identifier)

AddAttachment%(identifier-string, filename-string, description-string)

Call (cell-identifer, selection-expression)

Call (filename)

Checked

CheckedorYes (cell identifier)

Chr$(expression)

ClearComp(integer)

Close #(integer-expression)

Comp$ (integer-expression)

CompT$ (integer-expression)

Compile (source filename, destination filename)

Constant$(report name)

CopyComps (source-integer, destination-integer)

Date (expression)

Date$ (expression)

DateValue (string)

DeleteFile% (filename)

EmbedImages%(state%)

FieldCount (expression)

FieldType (cell-identifier)

FileExists% (filename)

ForceAutoSave

Format$ (date-expression, string)

Function

GetAttachment$(identifier-string)

GetAttachments$(flag %)

GetImage$ (identifier)

GetImages$ ( flag expression )

GetPPE$ ( section string, match string, filename )

GetPPS$(section string, entry string, default string, filename)

GetRequest (global variable identifier)

Go (cell-identifier)

HasAddendum%

If...Then...Else

InputBox$ (prompt-string, title-string, default-reponse-string)

Insert (string)

InStr% (start, string, sub-string)

Launch ( string )

LaunchComments

Left$ (string, length)

Len (string)

LoadExtended

Mid$ (string, start, length)

MsgBox (string)

NumFormat$ (string expression, integer)

Open (filename) For Append As # (integer)/ Open (filename) For Output As # (integer)

Print # (integer, string-expression-list)

PrintReport% (printscheme, driver-name)

Ques (string)

Register (DLL name, function name, parameter list)

RemoveAttachment (identifier-string)

Replace(string)

Report$

RestoreCursor

Return

Right$ (string, integer)

RLS$

SaveAttachment(identifier-string, destination-directory-string)

SaveReport (filename)

ScrolltoLine (expression)

SecureReport

Selection

SendCommandMessage (menu ID)

SetImage% (identifier, filename)

SetRequest (global variable identifier

Shell (filename of application)

SplitScreen (filename of application, filename of application

Status (string)

Str$ (expression)

Sub

Sum (cell range)

SwapComps (integer, integer)

This

Ucase$(string)

Unwarn

Val ( string )

Wait

WaitForTerminate (filename of application)

Warn

Warn (cell-type)

While...Wend

WinExecute(filename of application)

WritePPS% ( section string, entry string, filename )

= (expression)

= (string)

xCell$ (formname$, line%, across%, fontflag%)

SkelState%(skeleton%)

FormName$( )

SetFileName (new-name-string)


Abs (number-expression)

Returns the absolute value of the number indicated as the parameter.

Example:
  If Abs(Val(2|1))>=
      (Val(2|4)/100) Then
      Call(2|6, Calc)
  End If

The example above uses Abs to calculate the absolute value of 2|1.  The If-Then statement uses the Abs function to calculate whether the absolute value of 2|1 is greater than or equal to the value of 2|4 divided by 100.  If so, then 2|6 is called for the Calc selection.


ActivateApp()

Returns focus and control to Appraise-It.


ActiveField (cell-identifier)

Returns true if the parameter is the current field.

Example:
If ActiveField(14|6) Then
  A$="N"
ElseIf ActiveField(14|7) Then
  A$="L"
ElseIf ActiveField(15|9) Then
  A$="I"
End If

The example above uses If-then statements to cover situations in which this code will be Run from other field locations.  These other situations are handled by specifying A$ variable identities according to the ActiveField location, which is the location from which the code is Run.


AddAttachment%(identifier-string, filename-string, description-string)

Attaches a file to the report which is embedded with the file at save time and is transmitted with the report via e-mail, EDI, etc.  AddAttachment% returns a 1 if the attachment is successful, or a 0 for an unsuccessful attachment.

Example:
AddAttachment%(                     ,                  ,                   )

The example above uses AddAttachment% to attach the ________________ to the __________________________.  The third parameter is ______________________________.  AddAttachment% returns a 1 for a successful attachment and a 0 for an unsuccessful attachment.


Call (cell-identifer, selection-expression)

Performs the code contained in the cell indicated by the first parameter, using the expression given in the second parameter as the called cell's Selection value.  Call performs this code using the called cell's location, not the current cell's location.

Example:
Fields 36|1, 36|2, and 36|3:
Select Case Selection
  Case Leave
    Call(Line|4, Calc)
End Select

36|4:
Select Case Selection
  Case Calc
    = Val(Line|1)*Val(Line|2)*Val(Line|3)
    Call(18|1, Calc)
End Select

The example above Calls the calculation case of 36|4 from all three fields, 36|1, 2, and 3.   Field 36|4 calculates a multiplication formula for the values from the first three fields, and then Calls still another field, 18|1, whose value depends on 36|4.  Call is the appropriate function choice for the first three fields, because the calculation needs to be performed and provided in field 36|4 using 36|4's Calc selection (as opposed to being Run using the current cell's selection).  If fields 36|1 through 36|3 contained the Run function instead of Call, the multiplication calculation would replace the values in each of the first three fields.


Call (filename)

Performs the code contained in the file indicated by the parameter.

Example:
Call("script.bas")
Call("script.bxe")

The example above uses Call("script.bas") to perform the source code, and Call("script.bxe") to perform the compiled code.


Checked

Returns true if the check box at the current location contains a value.

Example:
If Checked Then
  Call(13|1, Calc)
End If

The example above performs the calculation in 13|1 when the currently active checkbox contains a value.


CheckedorYes (cell identifier)

Returns true if checkbox contains an X or a Y.

Example:
If CheckedorYes(1|2) Then
  Call(13|1, Calc)
End If

The example above Calls the Calc case of 13|1 if field 1|2 contains an X or a Y.


Chr$(expression)

Returns a string which is the ANSI character for the parameter.

Example:
String$ = Chr$(65) + Chr$(66)

The example above yields the ANSI character for 65 concatenated with the ANSI character for 66, or AB.  Refer to an ANSI character table for additional information on the ANSI codes 0 - 255.


ClearComp(integer)

Clears the comps data in the market grid at the location specified by the integer value.

Example:
ClearComp(2)

The example above clears the data contained in Comparable #2 of the market grid.


Close #(integer-expression)

Closes an open file.  The integer-expression refers to the file to be closed, which was opened using the Open command.  After the file is closed, additional data cannot be written to the file unless it is opened again.  Closing the file releases the integer that identifies the open file for use again with other files.

Example:
Open "c:\\tra\\urar.txt" For Output As #1
Print #1, "Check Age", "Check $" + Chr$(13) + Chr$(10)
Print #1, "Date"
Close #1

The example above opens urar.txt, writes information to it, then closes the file.

See Open (filename) For Append As # (integer)/
Open (filename) For Output As # (integer) and Print # (integer, string-expression-list) for additional information.


Comp$ (integer-expression)

Returns a string expression that is the name of the form or addendum that contains the Comps information indicated by the integer expression.  Each time Comp$ is called, a prompt appears asking you to select the type of Comp.

Example:
Comp1Form$ = Comp$(1)
Comp5Form$ = Comp$(5)

The example above uses Comp$ (1) to return the string for the form that contains Comp 1 information, or the "ua2".  Comp$ (5) returns the string for the form that contains Comp 5 information, or "cmps46".  In this example, two prompts appear, asking you to select the type of Comp.


CompT$ (integer-expression)

Returns a string expression that is the name of the form or addendum that contains the Comps information for the comparable indicated by the integer expression, but which is also of the same comparable type selected by the last Comp$ command.  Unlike Comp$, CompT$ does not provide a prompt asking you to select the type of Comp.

Example:
Comp1Form$ = Comp$(1)
Comp5Form$ = CompT$(5)

The example above uses CompT$(5) to return the string for the form that contains Comp 5 information of the comparable (rental, sales) type provided for Comp$(1).


Compile (source filename, destination filename)

Compiles the source file indicated by the first parameter into a destination for the compiled file indicated by the second parameter.

Example:
Compile("script.bas", "script.bxe")

The example above compiles the source code in Script.BAS into the compiled code in Script.BXE.  Note that the Script.BXE is a larger file than Script.BAS, but runs faster.


Constant$(report name)

Returns the full path of the current report indicated by the parameter, which is the report name.

Example:
If Constant$("SketchApp") <> "not found" then
  SketchFile$ = Constant$("SketchData") + "\\" +
     cell("Offscrn", "File#") + ".SKT"

The example above, when the Sketch Application is current, provides the full path of the current sketch file, as determined on the user's system.

Constant$ supports these parameters:

Directory	Description
PhotoApp	directory where Wilson's photo exe is stored
PhotoMem	directory where Wilson's photo memory files are stored
PhotoUser	directory where Wilson's data are stored
SketchApp	directory where the sketch application is stored
SketchData	directory where the sketch data files are stored
ReviewApp	directory where the review program is stored
TRAApp	our application directory which by default is c:\tra
TRAData	our data directory which by default is c:\tradata\data
TRAPriv	our personal user directory which by default is c:\trapriv


CopyComps (source-integer, destination-integer)

Copies the comps data in a market grid from the source to the destination indicated by the integer values.

Example:
CopyComps(2, 5)

The example above copies the comps data at Comparable #2 of the market grid to Comparable #5 of the market grid.


Date (expression)

Returns the numeric version of the system date.  This is passed as the first parameter to Format$ (expression, string-expression).  See also Format$ (date-expression, string).

Example:
NewDate!=Date
2|1=Format$(NewDate!, "mmmm d, yyyy")

The example above assigns NewDate! as a numeric version of the system date which is in turn passed to Format$ and converted to, for example, January 1, 1995.


Date$ (expression)

Returns the current system date in a 10-character string of the form mm-dd-yyyy, where mm is the month (01-12), dd is the day ( 01-31 ), and yyyy is the year (1980-2099).  This is the equivalent of Format$(Now, "mm-dd-yyyy").  See also Format$ (date-expression, string).

Example:
UserDate$=InputBox("Enter the Valuation Date.", "TRA", Date$)

The example above creates a dialog box titled TRA, with the prompt, "Enter the Valuation Date."  Date$ provides the current system date, such as 01-01-1995, as the default response.


DateValue (string)

Returns the numerical value of the date which has been represented as a string expression.  See also Format$ (date-expression, string).

Example:
DeltaMonth!=DateValue(UserDate$)
DeltaMonth!=DeltaMonth! - DateValue(This)

The example above takes a numeric value for the string UserDate and uses that value in a calculation in the next line of code.


DeleteFile% (filename)

Returns 1 if the file specified in the parameter has successfully been deleted, otherwise the function returns 0.

Example:
a%=DeleteFile%(X12File$)

The example above returns a%=1 if X12File$ is successfully deleted, or 0 if, for example, the file does not exist.


EmbedImages%(state%)

Embeds the associated images of a report upon saving if state% is 1. EmbedImages%(0) turns off embedding of images for the report.

Example:
EmbedImages%(1)
SaveReport( )

The example above embeds the associated images of a report with the saved report.

Example:
EmbedImages%(0)

The example above turns off the feature which embeds the associated images of a report with the saved report.


FieldCount (expression)

Returns the number of fields on the line given by the parameter.

Example:
Sub CopyLine(Dst%, Src%)
  J%=1
  While J%<=Fieldcount(Dst%)
    If FieldType(Cell(Dst%, J%))<>MultiHandle Then
      Cell(Dst%, J%)=Cell("ua2", Src%, J%)
    End If
    J%=J%+1
  Wend
End Sub

The example above uses FieldCount to provide the number of fields in the destination line.  While the number of fields in the destination line is less than or equal to those in the source line, the sub procedure will copy the field contents of the line from the source to the destination.


FieldType (cell-identifier)

Returns the type of field (MultiHandle, CheckBox, Multi, Single) of the parameter.

Example:
If FieldType(Cell(Dst%, J%))<>MultiHandle Then
  Cell(Dst%, J%)=Cell("ua2", Src%, J%)
End If

The example above uses FieldType to determine if the destination specified by the cell identifier is other than MultiHandle.


FileExists% (filename)

Returns 1 if the file specified in the parameter exists, otherwise the function returns 0.

Example:
If FileExists% (SketchFile$) = 0 then
  SketchFile$ = ""
End If

The example above uses FileExists% to determine if a file named SketchFile$ already exists.


ForceAutoSave

Forces the active report to be auto saved.  This is useful when shelling out to another process, ensuring that a recovery file is created if anything goes wrong.

Example:
SendCommandMessage( 24334 )      ;File Save As
ForceAutoSave

The example above provides the Save As dialog box, followed by a forced auto-save.


Format$ (date-expression, string)

Returns a date in a numeric format.  The first parameter is the date and the second parameter is a string that tells the function in what format the date should be returned.  See also Date$ (expression).

Example:
NewDate!=Date
2|1=Format$(NewDate!, "mmmm d, yyyy")

The example above assigns NewDate! as a numeric version of the system date which is in turn passed to Format$ and converted to, for example, January 1, 1995.

Appraise-It supports these Date Formats:

Format	Provides Data As:
"mm-dd"	09-08
"mm-dd-yy"	09-08-95
"mm-dd-yyyy"	09-08-1995
"mm-yy"	09-95
"mm-yyyy"	09-1995
"mmm-yy"	Sep-95
"mmm-yyyy"	Sep-1995
"mmmm d"	September 8
"mmmm d, yyyy"	September 8, 1995
"mmmm, yy"	September, 95
"mmmm, yyyy"	September, 1995
"mm/dd/yy"	09/08/95
"mm/dd/yyyy"	09/08/1995
"mm/yy"	09/95
"mm/yyyy"	09/1995
"yy"	95
"yyyy"	1995


Function

Defines a function procedure by its name and arguments and then provides the code that constitutes the function.

Example:
Function Adjustment!(A%)
  Select Case Sign(A%)
    Case 1
      Adjustment! = SalesPrice! - Adjustment!
    Case 0
      Adjustment! = SalesPrice!
    Case -1
      Adjustment! = SalesPrice! - Abs(Adjustment!)
  End Select
Exit Function

The example above defines a function called Adjustment! and calculates the value for the adjustment for positive, negative and zero adjustment values.


GetAttachment$(identifier-string)

Returns the filename associated with the attachment identified in the parameter.

Example:
Location$ = GetAttachment$("location")

The example above provides the filename for the location map to Location$.


GetAttachments$(flag %)

Retrieves a comma-separated list of attachments.  If flag% is 0, a list of file names alone is returned.  If flag% is 1, identifier|filename is returned.

Example:
a$ = GetAttachments$(0)

The example above from a report with two attachments - ___________ and ______________ returns this list to a$:

______________________________________________________

Example:
a$ = GetAttachments(1)

The example above from a report with two attachments of _________  and ___________ returns this list to a$:

______________________________________________________


GetImage$ (identifier)

Returns the filename associated with the image specified by the identifier.

Example:
A$ = GetImage$("CMP_4_4X6"))

The example above returns in A$ the filename, D:\PHOTOMGR\JPG\NK101202.JPG for the image identified by "CMP_4_4X6".  See also GetImages$ ( flag expression ) .


GetImages$ ( flag expression )

Returns a list of the filename and/or identifier for all image objects in a report.  Specifying (0) as the flag expression returns filenames only.  Specifying (1) returns identifier|filename.

Example:
a$ = GetImages$(0)

The example above from a report with two photographs of comp 4 and comp 5, returns this filename list in a$:  D:\PHOTOMGR\JPG\NK101202.JPG;D:\PHOTOMGR\JPG\NK102736.JPG;

Example:
a$ = GetImages$(1)

The example above from a report with two photographs of comp 4 and comp 5, returns this identifier|filename list in a$:  CMP_4_4X6|D:\PHOTOMGR\JPG\NK101202.JPG;
CMP_5_4X6|D:\PHOTOMGR\JPG\NK102736.JPG;

See also GetImage$ (identifier) .


GetPPE$ ( section string, match string, filename )

Get Private Profile Entry uses a pattern match to find an exact entry in an INI section.  GetPPE returns the first entry in the specified section of the INI file that matches the pattern.

Example:

1.PM:

[PHOTOS]
SUBJECT{FRONT VIEW}=1958 WOODCHASE BOULE
  ~D:\PHOTOMGR\JPG\NK102736.JPG
SUBJECT{REAR VIEW}=1958 WOODCHASE BOULE
  ~D:\PHOTOMGR\JPG\OFSS4220.JPG
SUBJECT{STREET SCENE}=1958 WOODCHASE BOULE
  ~D:\PHOTOMGR\JPG\OFSS4954.JPG
COMP1{FRONT VIEW}=2001 WOODCHASE BOULE
  ~D:\PHOTOMGR\JPG\OE3A4536.JPG
COMP2{FRONT VIEW}=1002 WEST POINTER
  ~D:\PHOTOMGR\JPG\NK1O1202.JPG
COMP3{FRONT VIEW}=4567 PINEY POINT
  ~D:\PHOTOMGR\JPG\OE3A4256.JPG
GENERAL 001 TOP{VIEW FROM PROPERTY}=4567 PINEY POINT
  ~D:\PHOTOMGR\JPG\NINQ3722.JPG

a$ = GetPPE$ ("PHOTOS", "GENERAL 001 TOP",
          Constant$("File#")+".PM)

The example above when executed on 1.PM returns to a$ the string "GENERAL 001 TOP{VIEW FROM PROPERTY}


GetPPS$(section string, entry string, default string, filename)

Get Private Profile String (similar to the Windows API call) returns the item in an INI file that matches the section string and entry string, otherwise it returns the default string.

Example:

Win.INI file:

[Extensions]

cal=calendar.exe ^.cal
crd=cardfile.exe ^.crd
trm=terminal.exe ^.trm
txt=notepad.exe ^.txt

MVB=MVIEWER2.EXE ^.mvb
PDF=C:\ACROEXCH\ACROEXCH.EXE ^.PDF
PDS=C:\ACROEXCH\ACROEXCH.EXE ^.PDF

acrodir$ = GetPPS$("Extensions", "PDF", "N/A", "WIN.INI"

The example above returns in Acrodir$ the item in the Extensions section of the Win.INI file that match "PDF" or C:\ACROEXCH\ACROEXCH.EXE ^.PDF

See also WritePPS% ( section string, entry string, filename ).


GetRequest (global variable identifier)

Retrieves data placed in a global variable.  Data placed in these global variables remain resident until the application terminates and may be accessed by any other macro session or via DDE.

Example:
GetRequest("Glob_Ident")

The example above returns any text assigned to the global identifier "Glob_Ident".

Note:  The data in "Glob_Ident" may also be accessed via DDE by setting the topic to "System" and performing a DDERequest on "Glob_Ident".

See also DDE Request and SetRequest (global variable identifier.


Go (cell-identifier)

Moves the editor to the cell specified as the parameter.

Example:
If Selection=Keypress Then
  Go(16|9)
End If

The example above moves the editor from 14|6 to 16|9 if a key is pressed.


HasAddendum%

Allows you to check for the existence of an addendum before accessing it.

Example:
if HasAddendum%("offscrn") then
  Launch("offscrn")
end if

The example above checks for the offscreen addendum (or the Report Profile) and if one exists, launches that addendum.


If...Then...Else

Performs the instructions if the stated condition exists or is true.  Else provides for alternative conditions.

Example:
If Report$="ua2" Then
  8|1="ua2"|101|1
Else
  Go(156|1)
End If

The example above uses If-Then statements to determine if the form is the URAR, and if so, transfers the contents of 101|1 of the URAR to the addendum field 8|1.  If the form is not the URAR, the editor goes to 156|1.


InputBox$ (prompt-string, title-string, default-reponse-string)

Creates a dialog box with a prompt, a title, and a default response.

Example:
Insert(InputBox$("What is the zip code?",
 "Zip Macro", "99999"))

The example above creates the input box as shown above.  Choosing OK inserts the text 99999 into the field.


Insert (string)

Inserts a string into the editor.  If the field already contains data, Insert places the macro information at the location of the insertion point, leaving the existing data intact.  See Replace(string) if you wish to replace the existing data, instead of inserting the macro data in addition to the information that already exists.

Example:
Insert("W. Palm Beach")

The example above provides the string expression "W. Palm Beach" at the current field location.


InStr% (start, string, sub-string)

Returns the position at which the second string occurs within the first string

Example:
BreakPoint = InStr%(1, FullAddress$, ",")

The example above uses InStr% to return the position at which the first comma occurs in a string expression that consists of the full street address, city, state.


Launch ( string )

Opens the form named in the parameter.  See LoadExtended.

Example:
{
  MenuItem "&Extended  Ctrl+E"
  MenuCode
  {
    Launch("ua2")
    LoadExtended
  }
}

The example above uses Launch to open the URAR form specified by the string parameter.


LaunchComments

Enables/disables automatic launching of the extended comment window in a macro if data exceeds field space.

Example:
LaunchComments 0

The example above disables the automatic launching of the extended comment window.

Example:
LaunchComments 1

The example above enables the automatic launching of the extended comment window.


Left$ (string, length)

Returns a string expression of the characters to the furthest left in the string expression.  The number of characters returned is determined by the length integer expression.

Example:
BreakPoint% = InStr (1, FullAddress$, ",")
FirstLine$ = Left$ (FullAddress$, BreakPoint%)

The example above uses Left$ to divide a string expression at a breakpoint determined by the location of a comma.


Len (string)

Returns the number of characters in a string expression.

Example:
Len ("Ashenputtel")

The example above uses Len to return 11, which is the number of characters in the string "Ashenputtel".


LoadExtended

Provides a special editor for the forms that have extended comments.

Example:
{
  MenuItem "&Extended  Ctrl+E"
  MenuCode
  {
    Launch("ua2")
    LoadExtended
  }
}

The example above uses LoadExtended to open the extended comment editor of the URAR form specified in the string parameter of Launch.


Mid$ (string, start, length)

Returns a portion of the string expression that is the first parameter.  The starting expression is the character position at which the returned string begins.  The length expression indicates how long of a string should be returned.  If the length is not provided or if the length provided is longer than the difference between the length of the string and the starting expression, the string returned starts at the starting expression and includes the remainder of the string expression.

Example:
BreakPoint1% = InStr (1, FullAddress$, ",")
BreakPoint2% = InStr (BreakPoint1% + 1, FullAddress$, ","
FirstLine$ = Left$ (FullAddress$, BreakPoint1%)
SecondLine$ = Mid$ (FullAddress$, BreakPoint1% + 1, BreakPoint2% - BreakPoint1%)
ThirdLine$ = Right$ (Full Address$, BreakPoint2%)

The example above uses Mid$ to extract the center portion of the string expression FullAddress$.


MsgBox (string)

Provides a message box with the message indicated by the message string.

Example:
MsgBox "Appraisal has been cancelled."

The example above provides a message indicating that the apprasial has been cancelled.


NumFormat$ (string expression, integer)

Takes a numeric string and returns a string to the number of decimal places specified as the integer.

Example:
a$ = NumFormat$("500", 3)

The example above returns 500.000 in a$.


Open (filename) For Append As # (integer)/
Open (filename) For Output As # (integer)

Opens a sequential file and allows data to be written to the file using the Print #(expression, string-expression-list) command.  The first parameter is a string-expression containing the name of the file to be opened and written to.  The second parameter is an integer-expression specifying a unique numeric identifier to be associated with the file.  This number is an alias for the file name, and any other files opened while this file is open must use a different numeric identifier.  It is used in all file related commands such as Print # and Close #.  A file can be opened either for output or for append.  If a file is opened for output, a new file is created and if the specified file already exists, all information previously contained in that file is erased.  If a file is opened for append, new text is added to the end of the existing file.

Example:
Open "c:\\tra\\urar.txt" For Output As #1
Print #1, "Check Age", "Check $" + Chr$(13) + Chr$(10)
Print #1, "Date"
Close #1

The example above opens c:\tra\urar.txt, writes information to and closes the file.  The file is open for output, so if urar.txt already exists, it will be rewritten with the new text.  When the file is opened, it is assigned the integer alias "1", and is referred to by the integer from this point on.

See Close #(integer-expression) and Print # (integer, string-expression-list).


Print # (integer, string-expression-list)

Writes data to a sequential file.  The integer-expression refers to the open file being written to.  The integer must refer to a file that has already been opened using the Open command.  The string-expression-list parameter is a comma-separated list of data that is to be written to the file.

Example:
Open "c:\\tra\\urar.txt" For Output As #1
Print #1, "Check Age", "Check $" + Chr$(13) + Chr$(10)
Print #1, "Date"
Close #1

The example above uses print commands to write "Check Age, Check $" to the open file, adds a paragraph mark (Chr$(13)) and a carriage return (Chr$(10)), then writes "Date" to the next line.  Note that the c:\tra\urar.txt is open before Print writes information to the file.  Note also that urar.txt is opened For Output As, so that if urar.txt already exists, it will be rewritten with the new text.

See Close #(integer-expression) and Open (filename) For Append As # (integer)/
Open (filename) For Output As # (integer) for additional information.


PrintReport% (printscheme, driver-name)

Prints the acitve report using the specified print scheme to the specified driver.  If no print scheme is specified, the Print Commander dialog box appears.

Example:
PrintReport% ("", "PDFWRITR")

The example above, without a print scheme specified, provides the Print Commander dialog box set to print to the driver, PDFWRITR.


Ques (string)

Provides an input box containing the contents of the string expression and Yes and No checkboxes.

Example:
If Ques( "Are you sure?" ) Then
  4|1 = "yes"
Else
  4|1 = "no"
End If

The example above provides an input box which inquires "Are you sure?" along with checkbox choices for yes and no.


Register (DLL name, function name, parameter list)

Allows definition and call of an external function in a DLL.

Example:
Register "UTILITY.DLL", "CopyFile", "SS"

The parameter list is defined as follows:

Parameter	Definition
s	C string
i	Short integer ~= 2 bytes
u	DWORD = 4 bytes
r	Reference to address
The example above registers a "CopyFile" function from the Utility.DLL, allowing for two C string parameters for the source and destination files.


RemoveAttachment (identifier-string)

Removes the attachment specified in the parameter.

Example:
RemoveAttachment (                             )

The example aboves removes the ---------------------- attachment from the active report.


Replace(string)

Replaces existing data in a field with a string of text.  See Insert (string) to leave the existing data intact and add the macro information to the information that already exists.

Example:
Replace("None")

The example above replaces the existing text in the field with None.


Report$

Returns the form identifier of the major form in the current report.

Example:
If Report$="ua2" Then
  8|1="ua2"|101|1
End If

The example above determines if the form is the URAR, and if so, transfers the contents of 101|1 of the URAR to the addendum field 8|1.


RestoreCursor

Restores the cursor in the event that external processes reset it.

Example:
DDETerminate (chan!)
RestoreCursor

The example above uses RestoreCursor as a precautionary measure after a DDE link has been terminated.


Return

Advances the editor to the next field.  Return is the equivalent of striking Enter while editing a field.

Example:
Replace("W. Palm Beach")
Return
Replace("FL")
Return
Replace("33405")

The example above, after inserting "W. Palm Beach" into the current field, moves the editor to the next field and enters .


Right$ (string, integer)

Returns a string expression of the characters to the farthest right in the string expression.  The number of characters returned is determined by the integer expression.

Example:
BreakPoint% = InStr (1, FullAddress$, ",")
FirstLine$ = Left$ (FullAddress$, BreakPoint%)
SecondLine$ = Right$ (Full Address$, Len(FullAddress$) - BreakPoint%)

The example above uses Right$ to divide a string expression at a breakpoint determined by the location of a comma.


RLS$

RLS (Remove Leading Spaces) deletes the leading spaces in a string.

Example:
a$ = RLS$("           test")

The example above returns "test" to a$ with no leading spaces.


SaveAttachment(identifier-string, destination-directory-string)

Saves the identified attachment to the destination directory.

Example:
SaveAttachment(                             ,                            )

The example above saves the _____________________ attachment to the _______________________ directory.


SaveReport (filename)

Saves the active report to the specified filename.  If no filename parameter is specified the Save As dialog box appears.

Example:
SaveReport (X12File$)

The example above saves the active report as X12File$.

Example:
SaveReport ( )

The example above provides the File Save As dialog box.


ScrolltoLine (expression)

Scrolls to the line given in the parameter.

Example:
Launch("ua2")
ScrolltoLine(12)
Go(13|1)

The example above launches the form named as the string parameter, the URAR, then ScrolltoLine moves line 12 to the top of the screen display, and the Go command moves the editor to field 13|1.


SecureReport

Currently under development.  Will protect a report from future modifications.


Selection

Returns the last action that happened.

Example:
Select Case Selection
  Case Keypress
    Go(12|4)
End Select

The example above uses Selection for the Keypress case.  If a keyboard key is pressed, the editor moves to 12|4.


SendCommandMessage (menu ID)

Causes the identified command on the TRA menu to execute.  The menu identifier must be known.

Example:
SendCommandMessage( 24334)        : File Save As

The example above sends a message to execute the TRA command 2334, File Save As.  A list of TRA commands is available upon request.


SetImage% (identifier, filename)

Places a graphic image (JPG, GIFF, etc.) into a defined image frame.  The first parameter identifies the frame, and the filename identifies the image.  See our photo page addenda for frame identifiers.

Example:
SetImage% (CMP_4_4X6, D:\PHOTOMGR\JPG\NK101202.JPG)

The example above places the file D:\photomgr\jpg\nk101202.jpg in the image frame identified by CMP_4_4X6.


SetRequest (global variable identifier

Places data in a global variable.  Data placed in these global variables remain resident until the application terminates and may be accessed by any other macro session or via DDE.

Example:
SetRequest("Glob_Ident", string$)

The example above assigns the text in string$ to the global identifier, "Glob_Ident".

See also GetRequest (global variable identifier).


Shell (filename of application)

Starts an application if the application is not already running, or switches the focus to the application if it is running currently.  The string expression parameter specifies the file name of the application to be started.

Example:
Shell("c:\\windows\\notepad.exe")

The example above uses Shell to start NotePad.

See WinExecute(filename of application) for an alternate command.


SplitScreen (filename of application, filename of application

Divides two running applications into two equal windows, and displays them simultaneously at their full width and one-half their vertical height.  The string expression parameters specify the names of the applications to be displayed.  Both applications must be currently running when this procedure is called.

Example:
Shell("c:\\windows\\notepad.exe")
SplitScreen("tra.exe", "c:\\windows\\notepad.exe")

The example above has TRA already running.  The Shell command starts Notepad, then SplitScreen is used to display the two applications simultaneously, with TRA in the top half of the display, and Notepad in the bottom half.

See Shell (filename of application).


Status (string)

Displays a string on the status bar.

Example:
Status("Please wait while adjustments are recalculated."

The example above displays the message contained in the string expression on the status bar.


Str$ (expression)

Returns a string representation of the value of a numeric expression.

Example:
20|2 = Str$(Val(22|2) - Val(22|3) - Val(21|2))

The example above uses Str$ to provide a string expression for the numeric value calculated when the values of 22|3 and 21|2 are subtracted from 22|2.  The complement to this function returns a numeric value of a string:


Sub

Defines a sub procedure by its name and arguments and then provides the code that constitutes the sub procedure.

Sub CopyLine(Dst%, Src%)
  J%=1
  While J%<=Fieldcount(Dst%)
    If FieldType(Cell(Dst%, J%))<>MultiHandle Then
      Cell(Dst%, J%)=Cell("ua2", Src%, J%)
    End If
    J%=J%+1
  Wend
End Sub

The example above defines a sub procedure, CopyLine, which copies a line from the URAR to the destination location as long as the number of fields in the source line is less than or equal to the number of fields in the destination line.


Sum (cell range)

Returns the sum of a range of cells.

Example:
Select Case Selection
  Case Calc
    = Sum(62|2:62|8) + Sum(63|2:63|8) + Sum(64|3:64|9)
    121|1 = This
End Select

The example above calculates the sum of the values in cells 62|2, 62|3, 62|4, 62|5, 62|6, 62|7, and 62|8, plus the sum of the values in cells 63|2, 63|3, 63|4, 63|5, 63|6, 63|7, and 63|8, plus 64|3, 64|4, 64|5, 64|6, 64|7, 64|8 and 64|9.  This value is provided to 121|1.


SwapComps (integer, integer)

Swaps the comps data in a market grid at one location to another location, indicated by the integer values.


This

Represents the current field and may be used as a cell representation.

Example:
This = 21|2
121|1 = This

The example above uses This in the first statement to provide the information from field 21|2 to the current field.  The second statement uses This to provide the information from the current field to 121|1.


Ucase$(string)

Returns a string in which all letters have been converted to uppercase.  Only lowercase letters are converted to uppercase; all uppercase letters and non-letter characters remain unchanged.

Example:
A$=Ucase$(This)

The example above uses Ucase$ to assign A$ as the current cell string in uppercase.


Unwarn

Removes the warning color flag.

Example:
If Selection = Calc Then
  = Val(14|5) + Val(15|8) + Val (16|8) + Val(17|5) + Val(18|8)
    If Val(This)<>100 Then
      Warn
    Else
      Unwarn
    End If
End If

The example above uses Unwarn to remove the warning flag color when fields 14|5, 15|8, 16|8, 17|5, and 18|8 add to 100.


Val ( string )

Returns the numeric value of a string of characters.  The string-expression is a sequence of characters that can be interpreted as a numeric value.  The Val function stops reading the string at the first character that it does not recognize as part of a number.  Val also strips blanks, tabs, and line feeds from the string.

Example:
Val ("        1615 198th Street N.E.")

The example above returns the value 1615198.  The complement to this function returns the string representation of a numeric value.


Wait

Sets a timed interval to wait before continuing.

Example:
Wait 10

The example above waits 10 seconds before continuing, allowing other applications to process.


WaitForTerminate (filename of application)

Waits for a specific application to terminate before continuing in the basic script, but still allows for processing of tasks.  Useful when the script launches another application but nothing should be done until the the original application terminates.

Example:
WaitForTerminate "x12_262.dll"

The example above allows the X12_262.DLL to terminate before proceeding to the next task.


Warn

Turns the current cell to the warning color.  UnWarn turns off the warning attribute in the current cell.

Example:
If Selection = Calc Then
  = Val(14|5) + Val(15|8) + Val (16|8) + Val(17|5) + Val(18|8)
    If Val(This)<>100 Then
      Warn
    Else
      Unwarn
    End If
End If

The example above uses Warn to change the current field to the warning flag color when fields 14|5, 15|8, 16|8, 17|5, and 18|8 do not add to 100.


Warn (cell-type)

Turns the cell specified in the parameter to the warning color.

Example:
14|6:
...
If (A$="I") or (A$="3") Then
  Warn(15|9)
End If
...

The example above use Warn to change cell 15|9 to the warning color if A$ = I or 3.


While...Wend

Performs a set of instructions as long as a specified condition is true.

Example:
Sub CopyLine(Dst%, Src%)
  J%=1
  While J%<=Fieldcount(Dst%)
    If FieldType(Cell(Dst%, J%))<>MultiHandle Then
      Cell(Dst%, J%)=Cell("ua2", Src%, J%)
    End If
    J%=J%+1
  Wend
End Sub

The example above uses While to execute the If-Then Statement.  While the number of fields in the destination line is less than or equal to those in the source line, the sub procedure will copy the field contents of the line from the source to the destination.


WinExecute(filename of application)

Execute an application if the application is not already running, or switches the focus to the application if it is running currently.  WinExecute returns

Example:
WinExecute("c:\\windows\\notepad.exe")

The example above uses WinExecute to start NotePad and returns
.

See Shell (filename of application) for an alternate command.


WritePPS% ( section string, entry string, filename )

Writes the Private Profile String in an INI file and assigns it to the specified entry and section.  May be assigned as an integer or not.

Example:
Conversion%=WritePPS%("Directories", "Output", 0, "X12_262.ini")

Example:
acrodir$ = GetPPS$("Extensions", "PDF", "N/A", "WIN.INI"
Write PPS "Extensions", "PDS", acrodir$, "WIN.INI"

The first example above assigns Conversion% as the private profile string "output" written in the "directories" section of the X12_262.INI file.

The second example writes acrodir$ as "PDS" in the "Extensions" section of the Win.INI file.  See also GetPPS$(section string, entry string, default string, filename)


= (expression)

Returns the evaluation of the expression to the right of the equal sign.

Example:
12|3:
Select Case Selection
  Case Calc
    = Val(12|1) + Val(12|2)
    122|1 = Val(12|1) + Val(12|2)
End Select

The example above uses = the first time to calculate the values of 12|1 plus 12|2 and provides this value to 12|3 when the case is Calc.  The second use of = provides the same calculation to field 122|1, specified on the left side of the equal sign.


= (string)

Returns the string expression to the right of the equal sign.

Example:
12|3:
Select Case Selection
  Case Leave
  = "Done"
  122|1 = "X"
End Select

The example above uses = the first time to provide "Done" to 12|3 when the case is Leave.  The second use of = provides an "X" to field 122|1, specified on the left side of the equal sign.


xCell$ (formname$, line%, across%, fontflag%)

Returns the complete information stored in the field specified by the string for the form name, and the line and across identifiers.  If the fontflag% is 0, no font information is embedded.

The xCell$ function is designed to retrieve field text and extended text associated with a field on the form.

Example:
a$ = xCell$ ("ua2", 20, 1, 0)

The example above uses xCell$ to retrieve the field text and extended comment data associated with the neighborhood boundaries information of the URAR.


SkelState%(skeleton%)

Sets the current form's status as a skeleton or disables skeleton status.  Returns the form to its previous status, either a skeleton or not.

Example:
a% = SkelState%(______________)

The example above returns the form indicated by the parameter to its previous state, toggling between skeleton status and non-skeleton status.


FormName$( )

Returns the name of the current form.

Example:
a$ = FormName$ ( )

The example above provides the name of the current form to a$.


SetFileName (new-name-string)

Assigns a new file name and path to the active report, with no return value.

Example:
SetFileName (X12File$)

The example above assigns the name X12File$ to the active report.


Glossary of Terms

client

client/server

conversation

dynamic data exchange (DDE)

functions

procedures

sequential file

server

sub procedures


client

An application program that requests and receives information from the server.


client/server

An application program that both requests and provides information.


conversation

The relationship between the application programs that are sharing information.


dynamic data exchange (DDE)

The medium through which information is shared between application programs.


functions

Procedures that result in the return of a value.


procedures

A portion of a program that performs a particular task.


sequential file

A text file with sequential input and output.


server

An application program that provides information to the client.


sub procedures

Procedures that do not result in a value being returned.