Microsoft Business Solutions–Solomon

Customization Manager Reference

Visual Basic for Applications
Release 6.0
 Microsoft® Business Solutions–Solomon

Customization Manager
Reference Visual Basic for
Applications
Release 6.0

RPMN-VBA0-0000600
6/2004
Copyright Manual copyright © 2004 Great Plains Software, Inc. All rights reserved. Great Plains
Software, Inc. is a wholly-owned subsidiary of Microsoft Corporation.
Your right to copy this documentation is limited by copyright law and the terms of the
software license agreement. As the software licensee, you may make a reasonable
number of copies or printouts for your own use. Making unauthorized copies,
adaptations, compilations, or derivative works for commercial distribution is
prohibited and constitutes a punishable violation of the law.
Trademarks Great Plains, Dynamics, eEnterprise, Dexterity, Solomon IV, and Solomon Software
are either registered trademarks or trademarks of Great Plains Software, Inc. in the
United States and/or other countries. Great Plains Software, Inc. is a wholly-owned
subsidiary of Microsoft Corporation. Microsoft, ActiveX, BackOffice, BizTalk,
FrontPage, JScript, Outlook, SourceSafe, Verdana, Visual Basic, Visual C++, Visual
C#, Visual InterDev, Visual SourceSafe, Visual Studio, Win32, Windows, and
Windows NT are either registered trademarks or trademarks of Microsoft Corporation
in the United States and/or other countries.
The names of actual companies and products mentioned herein may be trademarks or
registered marks - in the United States and/or other countries - of their respective
owners.
The example companies, organizations, products, domain names, e-mail addresses,
logos, people, places, and events depicted herein are fictitious. No association with any
real company, organization, product, domain name, e-mail address, logo, person,
place, or event is intended or should be inferred.
Warranty disclaimer Great Plains Software, Inc. and Microsoft Corporation disclaim any warranty
regarding the sample code contained in this documentation, including the warranties of
merchantability and fitness for a particular purpose.
Limitation of liability The content of this manual is furnished for informational use only, is subject to change
without notice, and should not be construed as a commitment by Great Plains
Software, Inc. or Microsoft Corporation. Great Plains Software, Inc. and Microsoft
Corporation assume no responsibility or liability for any errors or inaccuracies that
may appear in this manual. Neither Great Plains Software, Inc., Microsoft Corporation
nor anyone else who has been involved in the creation, production or delivery of this
documentation shall be liable for any indirect, incidental, special, exemplary or
consequential damages, including but not limited to any loss of anticipated profit or
benefits, resulting from the use of this documentation or sample code.
License agreement Use of this product is covered by a license agreement provided with the software
product. If you have any questions, please call the Microsoft Business Solutions
Customer Assistance Department at 800-456-0025 or 701-281-6500.
Publication date June 2004
Part number RPMN-VBA0-0000600
 Table of Contents iii

Table of Contents
Introduction 1
Welcome to Visual Basic for Applications ..............................................................................................1
What’s in this Manual? ............................................................................................................................1
Typographic Conventions ........................................................................................................................2

VBA Programming in Solomon 3

Overview..................................................................................................................................................3
Solomon Screen Object Model ................................................................................................................4
VBA Integrated Development Environment (IDE)..................................................................................4
Solomon Objects ....................................................................................................................................15
Solomon Events .....................................................................................................................................16
Solomon APIs ........................................................................................................................................16
Declaring Variables................................................................................................................................17
Including External Files .........................................................................................................................17
Levels and Events ..................................................................................................................................18
Message Functions .................................................................................................................................18
Sample Date Functions ..........................................................................................................................19
Structures ...............................................................................................................................................21
Transactional Flow of User Fields .........................................................................................................22
Treating Character Fields like Date Fields.............................................................................................22
Using SQL Statements ...........................................................................................................................23
Working with Grids................................................................................................................................24

Solomon Properties 27
BlankErr Property ..................................................................................................................................27
Enabled Property....................................................................................................................................28
FieldName Property ...............................................................................................................................29
Heading Property ...................................................................................................................................30
Mask Property ........................................................................................................................................31
Max Property..........................................................................................................................................32
Min Property ..........................................................................................................................................33
TabIndex Property..................................................................................................................................34
Visible Property .....................................................................................................................................35

Solomon Screen Events 37

Solomon Control Events ........................................................................................................................37
Chk Event (Solomon Control Object) ....................................................................................................38
Click Event (Solomon Control Object) ..................................................................................................41
Default Event (Solomon Control Object)...............................................................................................42
OnDelete Event (Solomon Control Object) ...........................................................................................43
iv Customization Manager Reference Visual Basic for Applications

PV Event (Solomon Control Object)......................................................................................................45

OnUpdate Event (Solomon Control Object) ..........................................................................................47
Display Event (Solomon Form Object)..................................................................................................50
Hide Event (Solomon Form Object).......................................................................................................51
Load Event (Solomon Form Object) ......................................................................................................52
LineChk Event (Solomon Grid Object)..................................................................................................53
LineGotFocus Event (Solomon Grid Object).........................................................................................55
OnCancel Event (Solomon Update Object)............................................................................................57
OnFinish Event (Solomon Update Object).............................................................................................59
OnInsert Event (Solomon Update Object)..............................................................................................61

Solomon API Function Calls 63

Solomon API Reference Summary ........................................................................................................63
AliasConstant Statement ........................................................................................................................68
ApplGetParms Function .........................................................................................................................69
ApplGetParmValue Function .................................................................................................................70
ApplGetReturnParms Function ..............................................................................................................72
ApplSetFocus Statement ........................................................................................................................73
ApplSetParmValue Statement ................................................................................................................74
CallChks Function..................................................................................................................................76
DateCheck Function...............................................................................................................................77
DateCmp Function .................................................................................................................................78
DateMinusDate Function .......................................................................................................................79
DatePlusDays Statement ........................................................................................................................80
DatePlusMonthSetDay Statement ..........................................................................................................81
DateToIntlStr Function...........................................................................................................................82
DateToStr Function ................................................................................................................................83
DateToStrSep Function ..........................................................................................................................84
DBNavFetch Functions ..........................................................................................................................85
DispFields Statement..............................................................................................................................87
DispForm Statement...............................................................................................................................89
DParm Function .....................................................................................................................................90
Edit_Cancel Statement ...........................................................................................................................91
Edit_Close Statement .............................................................................................................................92
Edit_Delete Function..............................................................................................................................93
Edit_Finish Function ..............................................................................................................................94
Edit_First Function.................................................................................................................................95
Edit_Last Function .................................................................................................................................96
Edit_New Function ................................................................................................................................97
Edit_Next Function ................................................................................................................................98
Edit_Prev Function...............................................................................................................................100
Edit_Save Statement ............................................................................................................................101
FPAdd Function ...................................................................................................................................102
FParm Function ....................................................................................................................................103
FPDiv Function ....................................................................................................................................104
FPMult Function ..................................................................................................................................105
FPRnd Function....................................................................................................................................106
 Table of Contents v

FPSub Function....................................................................................................................................107
GetBufferValue Statement ...................................................................................................................108
GetDelGridHandle Function ................................................................................................................109
GetGridHandle Function ......................................................................................................................110
GetObjectValue Function.....................................................................................................................111
GetProp Function .................................................................................................................................112
GetSqlType Function ...........................................................................................................................114
GetSysDate Statement..........................................................................................................................115
GetSysTime Statement.........................................................................................................................116
HideForm Statement ............................................................................................................................117
IncrStrg Statement................................................................................................................................118
IntlStrToDate Statement.......................................................................................................................119
IParm Function.....................................................................................................................................120
Is_TI Function......................................................................................................................................121
Launch Function...................................................................................................................................122
MCallChks Function ............................................................................................................................125
MClear Statement.................................................................................................................................126
MClose Statement ................................................................................................................................127
MDelete Function.................................................................................................................................128
MDisplay Statement.............................................................................................................................129
Mess Statement ....................................................................................................................................131
MessBox Statement..............................................................................................................................134
Messf Statement ...................................................................................................................................135
MessResponse Function.......................................................................................................................138
mFindControlName Function ..............................................................................................................139
MFirst Function....................................................................................................................................141
MGetLineStatus Function ....................................................................................................................142
MGetRowNum Function......................................................................................................................143
MInsert Statement ................................................................................................................................144
MKey Statement...................................................................................................................................146
MKeyFind Function .............................................................................................................................148
MKeyFld Statement .............................................................................................................................150
MKeyOffset Statement.........................................................................................................................152
MLast Function ....................................................................................................................................156
MLoad Statement .................................................................................................................................157
MNext Function ...................................................................................................................................159
MPrev Function....................................................................................................................................160
MRowCnt Function..............................................................................................................................161
MSet Statement ....................................................................................................................................162
MSetLineStatus Function.....................................................................................................................163
MSetProp Statement.............................................................................................................................165
MSetRowNum Statement.....................................................................................................................166
MSort Statement ..................................................................................................................................167
MUpdate Statement..............................................................................................................................168
NameAltDisplay Function....................................................................................................................169
PasteTemplate Function .......................................................................................................................170
PeriodCheck Function..........................................................................................................................171
vi Customization Manager Reference Visual Basic for Applications

PeriodMinusPeriod Function................................................................................................................172
PeriodPlusPerNum Function ................................................................................................................173
PVChkFetch Functions.........................................................................................................................174
SaveTemplate Statement ......................................................................................................................176
SDelete Statement ................................................................................................................................178
SDeleteAll Function.............................................................................................................................179
SetBufferValue Statement....................................................................................................................180
SetDefaults Statement ..........................................................................................................................181
SetLevelChg Statement ........................................................................................................................183
SetObjectValue Function .....................................................................................................................185
SetProp Statement ................................................................................................................................186
SetStatusBarText Statement .................................................................................................................188
SFetch Functions ..................................................................................................................................189
SGroupFetch Functions........................................................................................................................191
SInsert Statements ................................................................................................................................194
SParm Function ....................................................................................................................................196
Sql Statement........................................................................................................................................197
SqlCursor Statement.............................................................................................................................198
SqlCursorEx .........................................................................................................................................200
SqlErr Function ....................................................................................................................................204
SqlErrException Statement ..................................................................................................................206
SqlExec Statement................................................................................................................................208
SqlFetch Functions...............................................................................................................................209
SqlFree Statement ................................................................................................................................212
SqlSubst Statement...............................................................................................................................213
StrToDate Statement ............................................................................................................................214
StrToTime Statement ...........................................................................................................................215
SUpdate Statements..............................................................................................................................216
TestLevelChg Function ........................................................................................................................219
TimeToStr Function .............................................................................................................................221
TranAbort Statement ............................................................................................................................222
TranBeg Statement...............................................................................................................................223
TranEnd Statement...............................................................................................................................224
TranStatus Function .............................................................................................................................225
VBA_MExtend Function .....................................................................................................................226
VBA_MOpen Functions.......................................................................................................................227
VBA_SetAddr Statement .....................................................................................................................229

Glossary 233

Index 237
 Introduction 1

Introduction
Welcome to Visual Basic for Applications
Microsoft® Visual Basic for Applications (VBA) leads the industry in power, ease of
integration, and Visual Basic compatibility. You will find it easy to use VBA to create
scripts that automate a variety of tasks.

What’s in this Manual?

This manual provides:
• Visual Basic for Application language coding guidelines for Microsoft® Business
Solutions–Solomon.
• A complete list of Solomon API references.
Used to complement the Visual Basic for Applications product available in the
Solomon Customization Manager module, this manual is divided into the following
sections:

VBA Programming in Solomon

Summarizes Solomon’s implementation of Microsoft Visual Basic for Applications
(VBA). Topics discussed include the Solomon object model, the VBA integrated
development environment (IDE), how to declare variables, how to include external
files, and the use of SQL statements.

Solomon Properties
Lists and describes the Solomon properties available in the Visual Basic for
Applications language.

Solomon Screen Events

Lists, describes, and provides examples of the Solomon VBA screen events. These are
comprised of various window controls and objects.

Solomon API Function Calls

Lists, describes, and provides examples of Solomon API functions available in the
Visual Basic for Applications language.

Glossary
Defines commonly used VBA words and terminology.
2 Customization Manager Reference Visual Basic for Applications

Typographic Conventions
The following typographic conventions are used throughout this documentation:

To represent: Syntax is:

Statements and functions Boldface; initial letter uppercase:
Abs
Lenb(variable)
Arguments to statements or All lowercase, italicized letters:
functions variable, rate, prompt$
Optional arguments and/or Italicized arguments and/or characters in brackets:
characters [,caption$], [type$], [$]
Required choice for an A list inside braces, with OR operator ( | ) separating
argument from a list of choices choices:
{Goto label | Resume Next | Goto 0}
 VBA Programming in Solomon 3

VBA Programming in Solomon

Overview
Microsoft Visual Basic for Applications (VBA) is the world’s premier integrated
development technology for rapidly customizing packaged software applications and
integrating them with existing data and systems. VBA offers a comprehensive set of
programming tools based on the Microsoft Visual Basic development system, the
world’s most popular rapid application development system. Now, this powerful tool
has been embedded in the Solomon Customization Manager module!
With Microsoft VBA, Solomon developers can maximize the capabilities of the
Customization Manager module to create powerful Solomon customizations that meet
even the most demanding business needs quickly and cost effectively. By using VBA
and Customization Manager to customize Solomon, rather than developing
applications from the ground up, you are able to save time and money, reduce risks,
leverage developer skills, and produce the exact software solutions needed for your
unique business requirements.

Key Features
Microsoft Business Solutions implementation of VBA within Customization Manager
offers Solomon developers these important advantages:
• Common VBA technology – the same version of VBA use throughout Microsoft
Office and scores of other popular software products
• Standardized integrated development environment (IDE) – an industry-standard
IDE that includes the Visual Basic Editor, familiar to millions of software
developers worldwide
• Full core-language parity with Microsoft Visual Basic – the same core language
enhancements as Microsoft’s premier repaid application development tool
• Localized IDE and online Help – support for developers working in languages
other than English, including French, German, Japanese, and Chinese
• Developer IntelliSense® technology – instant reference to Solomon API syntax and
instant assistance with the Solomon object model
• Microsoft forms – create rich forms and custom dialog boxes in any Solomon
application
• ActiveX® controls support – embed ActiveX controls directly in Microsoft forms.
4 Customization Manager Reference Visual Basic for Applications

Solomon Screen Object Model

Solomon exposes its functionality to VBA through the Solomon Object Model, or
collection of objects that together represent a Solomon screen (window). The Solomon
Object Model is the interface that allows the following types of VBA to communicate
with Solomon screen objects:
• VBA within the Customization Manager module
• VBA in external applications such as Microsoft Office or other COM-compliant
application
Solomon developers can write small amounts of program code to control the behavior
of Solomon screen objects, and these objects can be controlled from within VBA and
Customization Manager as well as from any external COM-compliant tool.

VBA Integrated Development Environment (IDE)

The integrated development environment (IDE) is the development tool a Solomon
developer uses to create a custom Solomon solution that involves writing VBA code.
The editing and debugging environment, the Visual Basic Editor, exists outside of
Solomon. This allows the developer to write code and simultaneously view
programming results in the Solomon application. Although the IDE is outside of
Solomon, it runs in the same memory space, providing tight integration for event
handling as well as enhanced performance.

Figure 1: Visual Basic Editor

 VBA Programming in Solomon 5

Code Editor
The Visual Basic Editor includes a Code Editor (Figure 1) that provides color-coded
syntax as an aid to syntax development, IntelliSense features, code drag-and-drop,
block comment and uncomment, and syntax checking.
Solomon developers can open code windows for any object that supports code behind
it (e.g., a Solomon screen), as well as modules, classes, or forms added to the VBA
project. In each window, IntelliSense features (Figure 2) provide on-the-fly syntax and
programming assistance and reference:
• Complete Word – completes the word being type once enough letters have been
type to make the word distinct
• Quick Info – a tip providing syntax information that automatically appears when
you type a procedure or method name
• List Properties/Methods – a pop-up menu listing the properties and methods
available to an object preceding a period (.) in the syntax
• List Constants – a pop-up menu listing valid constants for the property or
argument being accessed
• DataTips – pop-up information that appears when VBA is in break mode; displays
the value of a variable underneath the cursor

Figure 2: VBA List Properties/Methods IntelliSense Feature

6 Customization Manager Reference Visual Basic for Applications

The Code Editor also allows Solomon developers to specify margin indicators to set a
breakpoint, set the next statement, or set a bookmark simply by clicking in the Code
Editor window margin (Figure 3).

Figure 3: Margin indicators

 VBA Programming in Solomon 7

Project Explorer and Properties Window

The VBA IDE Project Explorer displays VBA project components (i.e., forms,
modules, and references) associated with each open project, and the Properties
window displays the properties of application objects, forms, and controls (arranged
either alphabetically or by category).

Figure 4: Project Explorer and Properties window

8 Customization Manager Reference Visual Basic for Applications

VBA Debugging Tools

The VBA IDE’s powerful debugging tools, the same ones available to Visual Basic
developers, enable Solomon developers to quickly identify compile, program logic,
and run-time errors. These tools include:
• Locals window – automatically displaying all variables values currently in scope
• Watches window – permits monitoring specific variable or expression values;
permits interruption of code execution based on status of the watch expression
value
• Immediate window – evaluates any Visual Basic statement or expression
• Call Stack – displays active procedures and calls during break mode
To improve code debugging efficiency, Solomon developers can drag and drop code
from the Visual Basic Editor into the Immediate and Locals windows.

Figure 5: VBA Debugging Tools

 VBA Programming in Solomon 9

Object Browser
Key to efficient Solomon development is the ability to manipulate application and
component objects quickly. The IDE gives Solomon developers this capability with its
Object Browser that accurately differentiates between built-in properties, custom
properties, methods, event handlers, and user defined procedures (Figure 6).
Object Browser also shows function return types, parameter names and types, and user-
defined types and constants. Hyperlink jumps to referenced objects permit easy
navigation of the object hierarchy. Developers can also use the Object Browser to
search for objects and members across type libraries.

Figure 6: Object Browser

10 Customization Manager Reference Visual Basic for Applications

Microsoft Forms and Integrated Forms Designer

In addition to code editing, compilation, and execution, VBA gives the Solomon
developer outstanding control over the physical appearance of the customization
through the use of the powerful Microsoft Forms forms designer. With Microsoft
Forms, developers need to learn how to create custom window dialogs only once. After
that, the design process is the same for each new dialog. What’s more, existing dialogs
can be modified and used in other VBA projects or VBA-enabled applications.

Figure 7: Typical Custom Dialog

Because user forms can be displayed “modeless,” users can interact with a dialog’s
Solomon application while the dialog is being displayed.
Complementing Microsoft Forms is the IDE’s integrated form designer. Seamlessly
integrated into IDE, this designer provides a “visual canvas” that enables Solomon
developers to design user interface elements and write application code all from within
the same workspace.
 VBA Programming in Solomon 11

Figure 8: Integrated Form Designer and Controls Toolbox

Developers place dialog controls on the form using the Controls toolbox. Once the
controls are on the form, they can quickly be moved, resized, or duplicated according
to the needs of the form. The Controls toolbox can be set to display all registered
system controls or it can be customized by:
• Creating control templates – drag control(s) from a form back to the Controls
toolbox to create a reusable custom control template.
• Adding or removing pages – add pages to the Control toolbox that contain custom
groups of form controls
• Importing control pages – add pages by importing them from another developer.
You can also export control pages for use by other developers.
• Creating custom controls – change a control’s icon and its associated tool tip.
12 Customization Manager Reference Visual Basic for Applications

ActiveX Control Support

Microsoft Forms support ActiveX Controls, formerly called OLE Controls or custom
controls. ActiveX Controls are pre-built, reusable software components that enable
Solomon developers to add rich interactive capabilities to their custom software
solutions. More than 4,500 ActiveX controls are available today from a variety of
different vendors.

Figure 9: Sample “Calendar” ActiveX Control

 VBA Programming in Solomon 13

Add-In Support
For the ultimate in development flexibility and productivity, VBA fully supports
special-purpose add-ins such as code writers and form designers that:
• Are created as Component Object Model (COM) components.
• Support the IDTExtensibility2 interface.
Any add-in that meets these criteria can work within the Visual Basic Editor. Such
add-ins are “added in” via the IDE Add-In Manager.

Figure 10: Add-In Manager

14 Customization Manager Reference Visual Basic for Applications

Project Security
To protect their intellectual property and the integrity of their customizations, Solomon
developers can password-protect each VBA project. This ensures that only the most
dedicated hacker can ever access and decode project information.

Figure 11: IDE Project Protection – 40-Bit Encryption

 VBA Programming in Solomon 15

Solomon Objects
An object is any item used in the GUI (i.e., the Solomon window) to control data
input/output. Each field, label, or frame on a Solomon window – even the window,
itself – is considered to be an object All objects have properties, attributes that
determine how an object looks and what it does (open a form, display a value, etc.).

Embedded Screen Objects

Objects that exist on the Solomon application that are exposed to the VBA
environment are known as embedded screen objects. These objects are viewable from
the VBA Object Browser, Intellisense, and the property dialogs in the Solomon
Customization Manager module.
Each object is accessible within VBA code. This allows direct use of object and
property names when coding VBA projects. Following is an example of such usage:
' Highlight the Batch number field,
cbatnbrH.BackColor = vbHighlight
'Disable the autoreversing field.
Cautorev.Enabled = False
16 Customization Manager Reference Visual Basic for Applications

Solomon Events
An event is an activity occurring within the window environment at a point in time:
when you click the mouse, when a form is loaded, when a record is saved, etc. Events
are typically part of a Solomon object’s properties. Solomon events and their
associated object types are summarized below:

Solomon Event: Associated Object Type:

Click Button
Default Control
Chk Control
PV (possible value) Text Control
LineGotFocus Grid
LineChkEvent Grid
Load Form
Display Form
Hide Form
OnFinish Update
OnInsert Update
OnCancel Update
OnUpdate Update
OnDelete Update

Solomon APIs
Solomon provides a comprehensive set of Application Program Interface (API)
functions and statements that are fully compatible with the VBA language. Performing
tasks ranging from validating a date to aliasing certain Solomon constants used
specifically by the Transaction Import module, these APIs can handle just about any
development need your custom application may have. The current Solomon APIs are
listed and explained in “Solomon API Function Calls” on page 63.
 VBA Programming in Solomon 17

Declaring Variables
VBA supports full variable declaration methods. However, within the context of
Solomon, you should follow certain specific guidelines when declaring variables.
Do not be redundant in your variable declarations. Consider declaring these as
GLOBAL rather than DIM in each subroutine. This way, you’ll only need to declare
them once. Place Option Explicit in General_Declarations as well as at the very
beginning of any external files. This is a VB function that assures explicit variable
declaration. VB and VBA both support the use of $, %, and # as String, Integer, and
Double variable types respectively.
You do not need to explicitly set custom fields to "" (NULL) under program control.
By declaring two global variables as shown in the type structure examples, you simply
need to set bRecord = nRecord to null out the record or bRecord.FieldName =
nRecord.FieldName to null out a particular field.

Including External Files

When creating any customization that requires VBA code, the Customization Manager
module automatically adds the following module to the project:
VBTools_VBA (VBTVBA.BAS)
The VBTools_VBA module is in the Solomon VBA modules directory
(CU\VBA\Modules). This directory contains global declarations of structures and
variables that can be used in a VBA program. These are provided so that return values
for functions, for example, need not be declared explicitly by the VBA program (serr=,
serr1=, etc.).
The VBTools_VBA module also contains declarations of the functions and subroutines
in the Solomon Kernel (Swimapi.dll) that can be used in a VBA program. All standard
VB functions and routines (Format$, Trim$, etc.) which are documented in the Visual
Basic for Applications Help and those functions explicitly declared in the
VBTools_VBA module can be used in a VBA program. Note that the declarations of
the functions and subroutines in the VBTools_VBA module provide syntax on the
function or the subroutine’s usage. Questions on the usage syntax of any Solomon API
function and the specific constants defined are answered by referencing
VBTools_VBA module or by use of VBA’s IntelliSense feature.
An external file can be created that contains application-specific functions, constants,
and subroutines (in text format) and added in the same fashion as the VBTools_VBA
module. You may also create your own functions in a .dll and declare them in the same
manner as Solomon API functions in the VBTools_VBA module. If you know the
Solomon object name, you need not add any code in the event window for the Solomon
object. For example, if you have created a routine that you want to have called by
ccustid_Chk, you can name this routine ccustid_Chk. When you include this file, this
routine is automatically called. The only two exceptions to this are that you cannot
have Update nor Delete as a Sub name. These are VB reserved words. In these two
cases, you would need to have coded in the screen call your external routines.
18 Customization Manager Reference Visual Basic for Applications

Levels and Events

Any time a new field is inserted onto a form, you must specify the level associated
with that field. A level identifies the logical association of the records and fields that
are maintained by a particular application. For example, the Journal Entry (01.010.00)
window has two distinct levels: batch and detail. The batch level contains the fields
associated with the batch table while the detail level contains fields associated with the
GLTran (General Ledger Transactions) table. These levels are numbered starting at
zero (0). Therefore, Batch is Level 0 and Transaction is Level 1.
These level numbers are very important any time the database is updated. The
Solomon Kernel executes the appropriate OnUpdate event (Save, OnFinish, OnInsert,
OnDelete) for as many times as there are levels for the particular application. In the
example noted above (Journal Entry) the appropriate OnUpdate event executes twice,
once for the Batch (Level 0) and once for the GLTran (Level 1) if fields in both levels
require updating/inserting.
When attaching VBA code to the OnUpdate event, you must determine which level
number you wish to associate your code. Typically, placing a Select Case Level at the
beginning of the appropriate event performs this. For example, the following code in
01.010 executes upon the appropriate level in the OnUpdate event:
Select Case Level
Case 0 'Batch
Call MessBox("Batch Updated", MB_OK, "Message")
Case 1 'Transaction
Call MessBox("Grid Updated", MB_OK, "Message")
End Select

Message Functions
There are several message functions that a VBA program can reference. Use of these
functions eliminates the necessity of declaring variables for holding message strings.
For example, in standard VB, you must declare three variables for holding the message
string, type, and title. You can create a message, assign it a Msg_ID and Msg_Type of
1, and add it to the Solomon message table. This way, you can eliminate the need to
declare these extra variables and reference the message number in the mess statement
call. This is also very handy when you need to use the same message in multiple
programs or routines.
Note that you can also use any of the existing Solomon messages with type Msg_Type
= 1 as long as you provide the appropriate message number and applicable substitution
string(s).
Make sure that if you do create a new message, you assign a very high number to it so
that Microsoft Business Solutions does not override it in the future. The Msg_Id field
in this table is an integer, so you may start messages in the 30000 range and probably
be safe. You can also pass additional substitution parameters to messages.
 VBA Programming in Solomon 19

Sample Date Functions

This sample routine sets an existing date field to the system date:
Sub setdate_Click()
Dim NewDate as Sdate
Dim NewStrDate$
Call GetSysDate(NewDate)
NewStrDate = DateToStr(NewDate)
serr1 = SetObjectValue("cpaydate", NewStrDate)
Call DispFields("Form1","cpaydate")
End Sub
This example compares two dates. Note that you must include the .Val in the variable
names where appropriate:
Sub Test_Click()
Dim TestDate1 As Sdate
Dim TestDate2 As Sdate
TestDate1.Val = GetObjectValue("cinvcdate")
TestDate2.Val = GetObjectValue("cdocdate")
serr1 = DateCmp(TestDate1, TestDate2)
If serr1 = 0 Then
Call MessBox("Dates are equal", MB_OK, "Message")
ElseIf serr1 > 0 Then
Call MessBox("invdate greater", MB_OK, "Message")
ElseIf serr1 < 0 Then
Call MessBox("docdate greater", MB_OK, "Message")
End If
End Sub
20 Customization Manager Reference Visual Basic for Applications

This sample uses the BSL WeekDay function:

Dim TestDate1 As Sdate
TestDate1.Val = GetObjectValue("cinvcdate")
serr1 = WeekDay(TestDate1.Val)
Select Case serr1
Case 1
Call MessBox( "Sunday", MB_OK, "Message")
Case 2
Call MessBox( "Monday", MB_OK, "Message")
Case 3
Call MessBox( "Tuesday", MB_OK, "Message")
Case 4
Call MessBox( "Wednesday", MB_OK, "Message")
Case 5
Call MessBox( "Thursday", MB_OK, "Message")
Case 6
Call MessBox( "Friday", MB_OK, "Message")
Case 7
Call MessBox( "Saturday", MB_OK, "Message")
End Select
 VBA Programming in Solomon 21

Structures
You cannot simply declare a variable, issue an SQL statement, and fetch the result of
the SQL statement into this variable. You must declare a structure for any results of an
SQL statement (including aggregate functions). If you create special structures for
aggregate functions or special select statements – select fld1, fld2 from record) (not
recommended) – you must include all fields in the select statement and any fields in
the restriction not included in the select list.
For example, the following select statement:
Select CustId, Name, Zip From Customer Where
City = 'Findlay' and Zip = '45840' and CurrBal > 0;
would require the following structure definition:
Type Result
CustId As String * 10
NameAs String * 30
ZipAs String * 10
CityAs String * 30
CurrBal As Double
End Type
Global bCustResult As Result, nCustResult As Result
bCustResult is used in all sfetch calls.
The following aggregate function:
Select CustId, Sum(OrigDocAmt) From ARDoc
Group By CustId;
would require the following structure definition:
Type SumResult
CustId As String * 10
Amount As Double
End Type
Global bSumResult As SumResult
When using aggregate SQL functions as used in the second example above, you must
use the sgroupfetch SQL functions.
22 Customization Manager Reference Visual Basic for Applications

Transactional Flow of User Fields

User fields in Solomon transaction detail tables automatically carry into the General
Ledger if you post in detail. For example if you place ARTran.User1 in the detail area
of Hand Prepared Invoices (08.010.00), the corresponding GLTran.User1 field is set to
this same value at release time. This way, custom fields can be reported on in General
Ledger transaction reports.

Treating Character Fields like Date Fields

Even though string and float fields are the only user field types, you can still make a
character field behave like a date field. When you insert either the User1 or User2 field
onto a form, size it accordingly, then set the Mask property to 99/99/99. To handle
error checking the following code must then be inserted.
To default the field to the current system date, the following default event must exist:
Sub cuser1_Default(newvalue$, retval%)
Dim GetDate As Sdate
Call GetSysDate(GetDate)
newvalue = Mid$(datetostr(getdate), 1, 4) +
Mid$(datetostr(getdate), 7, 2)
End Sub
This default event must be explicitly forced to execute by the following (Note that this
would typically be placed in a preceding chk event):
serr = setdefaults("Form1", "cuser1")
To perform error checking on this field, place the following in its chk event:
Sub cuser1_Chk(chkstrg$, retval%)
serr = DateCheck(chkstrg)
If serr = -1 Then
' Invalid Day
Call Messbox("Invalid day, please re-enter", MB_OK, ↵
"Message")
retval = errnomess
ElseIf serr = -2 Then
'Invalid Month
Call Messbox("Invalid month, please re-enter", MB_OK, ↵
"Message")
retval = errnomess
End If
End Sub
 VBA Programming in Solomon 23

Using SQL Statements

Using VBA requires knowledge of the SQL syntax and its usage in the Solomon SQL
database and Solomon Kernel. For SQL Statement creation and syntax, refer to the
appropriate SQL database documentation that is provided with your SQL software.
There are two methods for retrieving records using the Solomon API sqlfetch()
functions. You may declare a string variable that stores the SQL statement and use this
variable in the sqlfetch call, or you can create an SQL stored procedure and reference
the stored procedure name in the sqlfetch call. Using a stored procedure is much
simpler because it minimizes the amount of VBA code and makes maintaining the
SQL statement much easier if you want to use the same SQL statement in several
places. To do this, you only need to change the stored procedure and not the VBA
code. For example, the following two uses of sqlfetch1 accomplish identical tasks but
the latter uses much less code.
Without stored procedure:
Dim SqlStr$
SqlStr = "Select * from Customer where CustId =" + sparm(chkstrg) ↵
+ "Order By CustId"
serr1 = sqlfetch1(c1, SqlStrg, bCustomer, Len(bCustomer))
With stored procedure:
Create Procedure GetCustomer @parm1 AS
Select * from Customer where CustId = @parm1 Order By CustId;
In Code:
serr1 = sqlfetch1(c1, "GetCustomer" + sparm(chkstrg), ↵
bCustomer, Len(bCustomer))
You may also use stored procedures for executing INSERT, DELETE, and UPDATE
statements with parameters.
24 Customization Manager Reference Visual Basic for Applications

Working with Grids

You can add additional functionality to the grid object. The Spread1 object has the
LineGotFocus and LineChk events exposed. You can evaluate under program control
what happens when the row receives focus (LineGotFocus) and when the user leaves
the row (LineChk). Following are some VBA examples:
This customization was designed for 01.010 but should work with any grid screen for
which you want to default a value in the grid to the value of the same field of the
previous line.
(general) Declarations
Global PriorValue$

Sub Insert(level%, retval%)

If Level = 0 Then
PriorValue = ""
End If
End Sub

Sub cuser1_Chk(chkstrg$, retval%)

PriorValue = chkstrg
End Sub

Sub cuser1_Default(newvalue$, retval%)

If Trim$(PriorValue) <> "" Then
newvalue = PriorValue
End If
End Sub

Sub spread1_LineGotFocus(maintflg%, retval%)

Dim CheckedValue$
If maintflg = INSERTED Then
CheckedValue = GetObjectValue("cuser1")
If Trim$(CheckedValue) = "" Then
serr1 = setdefaults("Form1", "cuser1")
End If
End If
End Sub
 VBA Programming in Solomon 25

This example uses 01.010 to automatically create an auto-balancing Journal entry.

Place Batch.User3 on bottom of Form. This is used to store the plug amount.
General Declarations
Global Diff#

Sub CreatePlug()
CrTotal = Val(GetObjectValue ("ccrtot"))
DrTotal = Val(GetObjectValue ("cdrtot"))
Diff = FPSub(DrTotal, CrTotal, 2)
serr1 = SetObjectValue ("cuser3", Str$(Diff))
End Sub

Sub cdramt_Chk(chkstrg$, retval%)

Call CreatePlug
End Sub

Sub ccramt_Chk(chkstrg$, retval%)

Call CreatePlug
End Sub

Sub spread1_LineChk(action%, maintflg%, retval%)

Call CreatePlug
End Sub

Sub cacct_Chk(chkstrg$, retval%)

Dim PlugAmount As Double
If Trim$(chkstrg) = "0000" Then
' Plug the Offset
PlugAmount = GetObjectValue ("cuser3")
If PlugAmount > 0 Then
Serr1 = SetObjectValue ("ccramt", Str$(PlugAmount))
ElseIf PlugAmount < 0 Then
Serr1 = SetObjectValue ("cdramt",
Str$(-1 * PlugAmount))
End If
End If
End Sub
26 Customization Manager Reference Visual Basic for Applications

This example accumulates the total transaction amount in Voucher and Adjustment
Entry (03.010.00) and defaults the transaction amount for each line to the amount
required to “balance” the document to the details. Place the following three lines in
General_Declarations:
Dim Original#
Dim Sum#
Dim LineAmount#

Sub spread1_linegotfocus(maintflg%, retval%)

Original = Val (GetObjectValue ("cOrigDocAmt"))
If maintflg = INSERTED and Original <> 0 Then
Sum = Val (GetObjectValue ("cDocBal"))
LineAmount = FPSub (Original, Sum, 2)
Serr1 = SetObjectValue ("cTranAmt", Str$(LineAmount))
End If
End Sub
 Solomon Properties 27

Solomon Properties

BlankErr Property
Determines whether or not a valid value must be entered or defaulted for the field.
Remarks
A setting of True indicates that the field requires a value. A setting of False indicates
the field is optional. Disabled and/or invisible fields should not be required unless they
are automatically defaulted with a valid value. If a control is marked as required by the
application then it cannot be marked as optional using the Customization Manager.
However if a control is marked as optional by the application then it can be marked as
required by the Customization Manager.
To modify the value of the BlankErr property at runtime, the SetProp statement
should be used rather than modifying the property directly in VB code. Usage of
SetProp allows the system to track changes to property values so as to avoid conflicts
with customizations.
See Also
Enabled Property, MSetProp Statement, SetProp Statement, Visible Property
28 Customization Manager Reference Visual Basic for Applications

Enabled Property
Determines whether or not the user can modify the contents of the control.
Remarks
A value of True indicates that the control is enabled whereas a value of False causes
the control to be disabled. Required fields should not be disabled unless they are
automatically defaulted with a valid value.
To modify the value of the Enabled property at runtime, the SetProp statement should
be used rather than modifying the property directly in VB code. Usage of SetProp
allows the system to track changes to property values so as to avoid conflicts with
customizations and / or other API’s such as the DisplayMode statement.
If a control is disabled by the application then it cannot be enabled using the
Customization Manager. However if a control is enabled by the application then it can
be disabled by the Customization Manager. The value of the Enabled property can be
narrowed at runtime but not expanded, depending on the level at which the changes are
being made (All User, One User, etc.). See the “Security” section of the Customization
Manager documentation. The Enabled property should not be used on the SAFGrid
control.
See Also
BlankErr Property, SetProp Statement, Visible Property
 Solomon Properties 29

FieldName Property
Facilitates proper runtime binding between the control and its underlying VB data
variable by operating in conjunction with the SetAddr statement.
Remarks
The data for each individual data entry control is actually stored in an underlying VB
variable. At runtime the control and its associated VB storage variable are bound
together using a combination of the FieldName property of the control and a
corresponding call to the SetAddr statement from within Form1_Load.
The FieldName property contains a Struct.FieldName value along with other more
detailed information such as Field Offset Value, Declare Type and Length. At a
minimum, a value must be entered into the Struct.FieldName field. This value will
normally be in the “bTableName.FieldName” format. The portion of the entry that
identifies the table name MUST correspond precisely to the table name string literal
which is passed in a corresponding call to the SetAddr statement. It is not, however,
required to correspond to the name of an actual table within the database.
The Field Offset Value, Declare Type and Length fields are optional depending on
whether or not the table name referenced by the Struct.FieldName is actually the name
of a table in the database. If the Struct.FieldName does reference a database table then
SWIM can access detailed information relating to each individual field contained
therein using the SQL data dictionary. If the referenced “table name” does not
correspond to the name of a table in the database then values MUST be entered in the
Field Offset Value, Declare Type and Length fields.
The FieldName property can be modified at design time only; it cannot be modified at
runtime.
The following table contains the Declare Type and Length of several standard
datatypes.

SQL Datatype VB Datatype Declare Type Length

Character String 0 Length of String
Integer(2) Integer 1 2
Float Double 2 8
Date SDate 3 4
Logical Integer 7 2

See Also
VBA_SetAddr Statement
30 Customization Manager Reference Visual Basic for Applications

Heading Property
Contains the caption for the corresponding grid column for controls actually associated
with a SAFGrid.
Remarks
Column headings containing more than one line can be implemented by separating the
text for each line with a comma such as “Line One, Line Two”.
To modify the value of the Heading property at runtime, the SetProp statement should
be used rather than modifying the property directly in VB code. Usage of SetProp
allows the system to track changes to property values so as to avoid conflicts with
customizations.
If an option button group appears within a grid, the grid uses the Heading property of
the first option button as the column header.
See Also
MSetProp Statement, SetProp Statement
 Solomon Properties 31

Mask Property
Determines the type and number of characters that can be entered for a particular field.
Remarks
Each character in the Mask property corresponds to one character in the displayed
field. If a particular mask character is one of the supported mask types, then the
corresponding valid values will be permitted for that particular edit position.
Otherwise, the character is considered to be a string literal to be displayed within the
field. These string literals are display only, causing the cursor to automatically “jump”
over them during data entry. Furthermore, the string literals will not be stored in the
resulting value of the underlying data field since they are only for display purposes.
To modify the value of the Mask property at runtime, the SetProp statement should be
used, rather than modifying the property directly in VB code. Usage of SetProp allows
the system to track changes to property values, avoiding conflicts with customizations.
The value of the Mask property can be narrowed at runtime but not expanded,
depending on the level at which the changes are being made (All User, One User, etc.).
See the “Security” section of the Customization Manager documentation.
The following table lists the supported mask types and their corresponding definition:

Mask Character Description

9 Numeric (0-9)
A Alphabetic (A-Z, a-z)
V Alphabetic which is converted to upper case
N Alphanumeric (A-Z, a-z, 0-9)
W Alphanumeric which is converted to upper case
X ASCII 32-127 (space, letters, numbers and special characters except
for * and ?)
L ASCII which is converted to lower case
U ASCII which is converted to upper case
M Mask ASCII (Same as X but includes * and ?. Be careful about using
in key fields where usage of * and ? wildcard characters could affect
usage of the LIKE keyword in SQL statements)
H Hexadecimal (0-9, A-F)

See Also
SetProp Statement
32 Customization Manager Reference Visual Basic for Applications

Max Property
Determines the maximum valid value for the control.
Remarks
To modify the value of the Max property at runtime, the SetProp statement should be
used rather than modifying the property directly in VB code. Usage of SetProp allows
the system to track changes to property values so as to avoid conflicts with
customizations.
The value of the Max property can be customized to a lower value using the
Customization Manager. However, the Max property cannot be customized to a higher
value. See the “Security” section of the Customization Manager documentation.
See Also
Min Property, SetProp Statement
 Solomon Properties 33

Min Property
Determines the minimum valid value for the control.
Remarks
To modify the value of the Min property at runtime, the SetProp statement should be
used rather than modifying the property directly in VB code. Usage of SetProp allows
the system to track changes to property values so as to avoid conflicts with
customizations.
The value of the Min property can be customized to a higher value using the
Customization Manager. However, the Min property cannot be customized to a lower
value. See the “Security” section of the Customization Manager documentation.
See Also
Max Property, SetProp Statement
34 Customization Manager Reference Visual Basic for Applications

TabIndex Property
Determines the logical sequence of controls within their parent form.
Remarks
When the user presses the Tab key, the actual order of progression through the controls
is determined by the value of the TabIndex property specified during program
construction. There are however several exceptions to this general rule. In particular,
focus will skip over the control in the next tab sequence if it is either disabled or
invisible. Furthermore, the design time TabIndex property value can be modified
using the Customization Manager. This allows the logical sequence of data entry for
any particular screen to be customized for unique circumstances.
The TabIndex property is also used by API calls referencing a range of controls such
as: SetDefaults, SetProp and DispFields. These types of API calls allow the
application to specify the first and last control upon which the designated operation
should be performed. All controls having a TabIndex between the TabIndex of the
first control and the TabIndex of the last control will be included in the group of
targeted controls.
This property can be modified at design time only; it cannot be modified at runtime.
See Also
DispField Statement, SetDefaults Statement, SetProp Statement
 Solomon Properties 35

Visible Property
Determines whether or not the control is visible.
Remarks
A value of True indicates that the control is visible whereas a value of False causes the
control to be invisible.
Required fields should not be made invisible unless they are automatically defaulted
with a valid value.
To modify the value of the Visible property at runtime, the SetProp statement should
be used rather than modifying the property directly in VB code. Usage of SetProp
allows the system to track changes to property values so as to avoid conflicts with
customizations.
If a control is made invisible by the application then it cannot be made visible using the
Customization Manager. However if a control is made visible by the application then it
can be made invisible by the Customization Manager.
The following remarks relate to how the Visible property relates to the SAFGrid
control. At runtime, Solomon forces the grid to be visible during initialization. Do not
set this property at design time for the SAFGrid control. Likewise, do not call
SetProp() on a form-view control because that reveals an intent to modify the Visible
property on a row-by-row type of basis, which is not supported.
The only appropriate runtime modification to the visibility of a grid component is to
display or hide an entire column, based on a data-driven rule. For example, suppose the
Application A contains a grid having 10 fields. Let us also suppose that fields 7, 8, 9
and 10 should not be viewable unless Module XYZ is installed and configured. Lastly,
let us assume that Module XYZ is neither installed nor configured. This would mean
that Application A needs to hide fields 7, 8, 9 and 10. Since these fields are associated
with an SAFGrid, we would want to hide the grid columns that correspond to fields 7,
8, 9 and 10. This operation can be performed during Form_Load by calling
MSetProp() for each of the fields to be hidden — each time specifying a value of
False for the Visible property. Note that in the MSetProp() scenario, this call must be
made before the SAFGrid receives focus (such as at screen load, or in a master key
Chk event of a header level). Do not call MSetProp() from within SAFGrid events,
such as LineGotFocus().
To hide an SAFGrid, set the Visible property of the underlying frame to False.
See Also
BlankErr Property, Enabled Property, MSetProp Statement, SetProp Statement
36 Customization Manager Reference Visual Basic for Applications
 Solomon Screen Events 37

Solomon Screen Events

Solomon Control Events

Use the Visual Basic Editor (VBE) to enter VBA code to be associated with an object
or control. Many of the Solomon objects have specific actions that occur during
runtime. These actions are called events.
To enter VBA code for an object, select Visual Basic Editor… from the Customize menu
or right mouse click to open a pop-up menu (also opened by pressing Alt+F11).
Once in the VBE, select the object and event for which you are entering VBA code.
Then, enter the event’s VBA code in the text region underneath the Object and Event
selections.

Note: You can write general-use routines that can be called by other routines or events
in the same screen by selecting the (general) event.

When working with the VBA, it is important to understand the concept of events.
Events are simply actions that occur at a point in time: when you click the mouse,
when the form is loaded, when a record is saved, when you press TAB to move to the
next field in the screen, etc.
You can add VBA code to any of the following events:

Event
Description When Event Occurs (Before/After Underlying Application Event)
Button clicks Before
Field default After
Field chk After
Field PV Before Application’s PV dialog (F3 or right double mouse click)
Grid linegotfocus After
Grid linechk After
Form Load After application’s form load
Form Display After application’s form display
Form Hide Before application closes
Finish After
Insert After application’s New event
Cancel After
Update Before (before the application calls tranend)
Delete Before (before the application calls tranend)
38 Customization Manager Reference Visual Basic for Applications

Chk Event (Solomon Control Object)

Occurs, at a minimum, whenever the data field changes and loses focus.
Syntax
Sub object_Chk ([Index],ChkStrg, retval)
Remarks
Whenever the user modifies the value of a field, the new value often needs to be
validated (e.g. checked for errors). If the new data value is valid then the application
may perform other related operations such as re-default or disable other fields. The
Chk event is where such code normally resides since this event is called any time the
value of the field is changed.
The Chk event can also fire at other times when the user did not directly modify the
value of the control. For example, navigating through existing records on a Normal
level using the First, Last, Prev, and Next toolbar buttons is conceptually equivalent to
the user entering new key field values to bring up different records. Consequently,
when navigating through existing records on a Normal level, the Chk event for each
key field on that Normal level is fired every time the user navigates from one record to
the next – regardless of how the navigation operation was invoked (e.g. data entry or
toolbar navigation). The Chk event can also fire in relation to the Trigger property. For
example using the Trigger property, a relationship between FieldA and FieldB can be
defined such that FieldB should be “re-validated” (e.g. its Chk event should be called)
any time the value of FieldA changes.
The Chk event uses the following arguments:

Argument Type Description

Index Integer Optional argument depending on whether or not the control is
associated with a control array. This value is used to uniquely
identify the control within a control array.
ChkStng string If the user just typed a new value for the field and pressed
Tab, then ChkStrg will correspond to that new data value. If
the Chk event was called for any other reason, such as
navigation, triggers, etc., then the value of ChkStrg is the data
value that will be assigned to the underlying field unless it is
rejected within the Chk event. In this latter case, it is possible
that the value of the field will be unchanged and therefore
ChkStrg will reflect that fact.
retval integer A data value can be rejected simply by modifying the RetVal
parameter which is passed to the Chk event. This parameter is
actually passed by reference which means that any
modifications to RetVal are automatically detected by the
system once program control exits the Chk event.
 Solomon Screen Events 39

The following table outlines the possible values which can be assigned to RetVal and
their corresponding effect on the system once program control exits the Chk event:

RetVal Description
NoAutoChk Suppresses automatic error checking which would normally occur after
the Chk event. It is typically used in the Chk event of key fields when the
result of the PVChkFetch or DBNavFetch is NOTFOUND but the user
should still be able to add new records. Since this return value is designed
to let ChkStrg pass as valid even though a corresponding data item could
not be located within the database, the value of ChkStrg will by definition
be applied as the new value of the field as opposed to being rejected.
A Message Number When RetVal is initialized with a specific message number, the
corresponding message from the Solomon message file will automatically
be displayed after the Chk event. Furthermore, the value of ChkStrg will
be rejected. A common implementation of this type of return value is to
set RetVal to the return value of the PVChkFetch or DBNavFetch call
performed within the Chk event. This is due to the fact that the return
value from these functions in the “not found” scenario corresponds to the
“not found” message number. Setting RetVal to a message number is the
recommended method for providing feedback to the user as to the precise
reason why the value of ChkStrg is being rejected.
ErrNoMess This return value is similar to a message number in the fact that it will
cause the value of ChkStrg to be rejected. However the system will not
display a message since the application should already have done so
during the Chk event. This is useful in cases where the message requires
data values for one or more replacement parameters. Consequently, the
application can use the Messf statement to display the message along with
the required substitution values and then subsequently set RetVal =
ErrNoMess.

Example 1
The following example illustrates the Chk event, on a non-key field control, in which a
record corresponding to the value of ChkStrg must be fetched from the database for use
by the application. If the record cannot be found then it is to be considered an error.
This code snippet was actually taken from the Chk event of the Earnings Type field on
the Timesheet Defaults sub-screen of the Payroll module’s Employee Maintenance
(02.250.00) window. This particular application requires that the default Earnings Type
for all employees must contribute to net pay. Thus it is not enough that the user enters
the ID of just any Earnings Type. Rather, that Earnings Type must also be defined as
contributing to net pay. If the relevant Earnings Type does not contribute to net pay
then it will be rejected simply by setting RetVal to the particular Solomon message
number explaining the nature of the problem.
Message number 260 is the actual message which will be displayed and its associated
text in the Solomon message file reads as follows: “Earnings type must contribute to
net pay, please reenter.”
Sub cDfltEarnType_Chk (chkstrg As String, retval As Integer)
RetVal = PVChkFetch1(CNULL, CSR_EarnType, chkstrg,↵
bEarnType, LenB(bEarnType))
40 Customization Manager Reference Visual Basic for Applications

If (RetVal = 0) Then
If (bEarnType.NetPay <> LTRUE) Then
RetVal = 260
End If
End If
End Sub

Example 2
Sub cFieldA_Chk(chkstrg$, retval%)
' Verify this is what we wanted.
If Trim$( chkstrg$) = "BADVALUE" Then
Retval% = 8033 ' return message number 8033: Invalid data.
Value
End If
End Sub
 Solomon Screen Events 41

Click Event (Solomon Control Object)

Occurs when a command button is pressed.
Syntax
Sub object_Click ([Index])
Remarks
Use this event to trigger actions in response to a button being pressed.
The Click event uses the following arguments:

Argument Type Description

Index Integer Optional argument depending on whether or not the control is
associated with a control array. This value is used to uniquely
identify the control within a control array.

Example
Sub Button1_Click()
'Display new subform
Call DispForm("Form2",True)
End Sub
42 Customization Manager Reference Visual Basic for Applications

Default Event (Solomon Control Object)

Occurs when either a screen load or new entity request refreshes the screen. Occurs
any time the control is being defaulted and a Default property has not been
implemented.
Syntax
Sub object_Default ([Index], OldValue, retval)
Remarks
The default data value for any particular data entry control can be specified via either
the Default property or the Default event. The Default property can be used when the
default value is not contingent upon any the value of any other data item. However, if
the methodology for determining a default value varies depending upon particular
situations, then code should be written for the Default event. If a Default property is
defined then the Default event will not be used.
Within the Default event, referring directly to the VB variable to which the control is
bound sets the default value of the relevant field. For example, if the control is bound
to string field called “bTableA.FieldA” within its FieldName property then within the
Default event the value of the field can be defaulted in a manner such as
bTableA.FieldA = “StringValue.” The default data value for an SAFOption button
group is always derived from the first option button in the group, since by definition
only one option button can be selected within any particular group.
The Default event uses the following arguments:

Argument Type Description

Index Integer Optional argument depending on whether or not the control
is associated with a control array. This value is used to
uniquely identify the control within a control array.
OldValue string Contains the data value that the underlying field had
immediately prior to the Default event. This is required
because the underlying field will already have its value
overwritten when the Default event is called.
retval integer A non-zero positive return value suppresses further default
action – including customization defaults and trigger calls.

Example
If a control (cFieldA) is bound to a string field called “bTableA.FieldA” within its
FieldName property, then within the Default event the value of the field can be
defaulted in a manner such as bTableA.FieldA = “StringValue”.
Sub cFieldA_Default(newvalue$, retval%)
'Default this field to 'String Value'
Call SetBufferValue("bTableA.FieldA", "StringValue")
End Sub
 Solomon Screen Events 43

OnDelete Event (Solomon Control Object)

Occurs during the series of actions/events initiated by a DELETE operation.
Syntax
Sub object_OnDelete (Level, InsertFlg, LevelsDone, LevelsLeft, RetVal)
Remarks
To understand when the OnDelete event occurs, a developer must first understand the
higher level concept of what is referred to here as a DELETE operation. The operation
is differentiated from the event in the fact that the OnDelete event comprises only a
segment of a series of events implied by a DELETE operation.
A DELETE operation is initiated when the user clicks on the Delete button on the
Solomon toolbar. The only exception is when the user deletes a detail line from a
Solomon Grid in which case the LineChk event is called.
A DELETE operation is comprised of the following series of actions and/or events. If
the application contains more than one Normal level then the user will be prompted as
to which of the Normal level records is being deleted. Processing will begin with the
level the user selects and continue for each non-Lookup level in order from LEVEL0 to
LEVELn.
• The OnDelete event is called for the level. If this is the first level to be processed
than a database transaction has not yet been initiated. Consequently the application
must call TranBeg if it needs to perform database update/delete operations during
the first pass through the OnDelete event.
• If the application did not modify the value of RetVal in the preceding step then the
master table for the level is deleted. The master table for any particular level is the
table identified by the VBA_SetAddr call for that particular level.
Once all levels that had previously been modified have been successfully updated, the
database transaction is ended and a NEW operation is automatically initiated to prepare
the application for data entry.
If any errors occur during the delete of any level then the entire operation is aborted –
including the database transaction.
44 Customization Manager Reference Visual Basic for Applications

The OnDelete event uses the following arguments:

Argument Type Description

Level integer Current level being processed.
LevelsDone integer Number of levels already processed within the context of
the current DELETE operation.
retval integer The automatic deletion of the master table for the current
level, which occurs after the OnDelete event for that
particular level, can be suppressed by setting RetVal to the
NoAction symbolic constant defined in the VBTools_VBA
module. The entire DELETE operation can be aborted by
setting RetVal either to a Solomon message number or the
ErrNoMess symbolic constant defined in the
VBTools_VBA module.
 Solomon Screen Events 45

PV Event (Solomon Control Object)

Occurs when the Inquiry key (F3) is pressed or a right mouse double click occurs.
Syntax
Sub object_PV ([Index], FieldValue, Action)
Remarks
PV event flow will process the highest macro level (self, 500) first followed by each
lower macro level until the action parameter has been set to something other then the
default (no action). If all macro calls have been made and the default action is still set
then the underlying application PV dialog will be called (if it exists).
If the PV event passes a value back other then the accepted values an error message
will occur and the event will be treated as a no action value.
The PV event is for setting the value of the field only. It does not check the field for
validity. That will occur afterwards in the field’s check events (for each corresponding
level). This event is intended to allow Customizers to develop inquiry dialogs.
The PV event uses the following arguments:

Argument Type Description

Index Integer Optional argument depending on whether or not the control
is associated with a control array. This value is used to
uniquely identify the control within a control array.
FieldValue string This parameter holds the current field string value when
called and is used as the resulting accepted value to be
error checked before applying to the field (control).
Action integer This parameter is used to hold the action to take after the
PV event was called. By default the action is to continue
processing PV dialogs. The other two actions are Accept
and Cancel.
The follow are valid values for the Action argument:

RetVal Description
Accept Indicates no further PV event processing will take place and the field
string value will be used in error checking. If error checking accepts the
value then focus will move on to the next field (specified in the error
checking logic).
Cancel Indicates that the dialog has been canceled and focus is left on the
calling field (control). No further processing occurs.
No Action Continues processing PV dialogs.

Example
Global PVAction As Integer
Sub cFieldA_PV(fieldstrg$, action%)
Dim Result As String
46 Customization Manager Reference Visual Basic for Applications

' Setup Choices in sub-form combo box for user to choose PV.
Call SetProp( "cPvListCombo", "List", "A;Asset Account,E;Expense
Account,L;Liability Account")

PVAction = Cancel
'Display the PV form.
Call DispForm( "Form2", True)

' If the OK button was pressed on the sub-form then PVAction was
set to Accept
If PVAction = Accept Then
Result = GetObjectValue( "cPVListCombo")
If Trim(Result) = "A" Then
' Default Asset Account used.
Fieldstrg$ = "1030"
ElseIf Trim(Result) = "E" Then
'Default Expense Account
Fieldstrg$ = "7200"
Else
'Default Liability Account
Fieldstrg$ = "2070"
End If

End If
action = PVAction

End Sub
 Solomon Screen Events 47

OnUpdate Event (Solomon Control Object)

Occurs during the series of actions/events initiated by a SAVE operation.
Syntax
Sub object_OnUpdate (Level, InsertFlg, LevelsDone, LevelsLeft, RetVal)
Remarks
To understand when the OnUpdate event occurs, a developer must first understand the
higher level concept of what is referred to here as a SAVE operation. The operation is
differentiated from the event in the fact that the OnUpdate event comprises only a
segment of a series of events implied by a SAVE operation.
Any one of the following occurrences initiates a SAVE operation:
• When the user clicks on the Save button on the Solomon toolbar.
• When the user clicks on the Finish button on the Solomon toolbar.
• When the user answers “Yes” in response to the “Do you want to save your
outstanding changes?” prompt. This prompt occurs any time the user has modified
data and then attempts to either enter a new item, navigate to a different item or
close the screen without first saving his/her changes.
A SAVE operation is comprised of the following series of actions and/or events for
each level which has been changed in order from LEVEL0 to LEVELn. For example if
the only information that changed resides on LEVEL0 then only LEVEL0 will be
processed during the SAVE operation. A database transaction is started before any
levels are processed.
The OnUpdate event is called for the level.

Note: TranEnd should absolutely never be called by the application within the
OnUpdate event since the system will then be unable to rollback the entire SAVE
operation!

• If the application did not modify the value of RetVal in the preceding step then the
master table for the level is updated. The master table for any particular level is the
table identified by the VBA_SetAddr call for that particular level.
Once all levels that had previously been modified have been successfully updated, the
database transaction is ended. The OnUpdate event is then called one additional time.
The Level parameter will have a value corresponding to the Finished symbolic constant
defined in the VBTools_VBA module. At this point the level status for all levels
should have a value of NOTCHANGED. Furthermore, the line status of each
individual detail line within any grids should also have a value of NOTCHANGED.
If any errors occur during the update of any level then the entire operation is aborted –
including the database transaction.
48 Customization Manager Reference Visual Basic for Applications

The OnUpdate event uses the following arguments:

Argument Type Description

Level integer Current level being processed.
InsertFlg integer True indicates a new record is being inserted. False
indicates that an existing record is being updated.
LevelsDone integer Number of levels already processed within the context of
the current SAVE operation.
LevelsLeft integer Number of levels yet to be processed within the context of
the current SAVE operation. This count does not include
the Finished pass through the OnUpdate event.
retval integer The automatic updating of the master table for the current
level, which occurs after the OnUpdate event for that
particular level, can be suppressed by setting RetVal to the
NoAction symbolic constant defined in the VBTools_VBA
module. The entire SAVE operation can be aborted by
setting RetVal either to a Solomon message number or the
ErrNoMess symbolic constant defined in the
VBTools_VBA module.

Example
Global GridHandle%
Sub OnUpdate(level%, insertflg%, retval%)
Dim MaintFlag%

If Level = 0 Then
' Call is made so that if any changes are made that would
affect grid currency,
' the MsetRowNum function will reset it.
If serr1 = 0 Then
Row = mgetrownum(GridHandle%)
End If
' Move to top of array
err1 = mfirst(GridHandle%, MaintFlag%)
While serr1 = 0
serr2 = sqlfetch1(c1, "XnewTable.Key" +
sparm(GetObjectValue("ckey")), _
bXNewTable, Len(bXNewTable))
Select Case MaintFlag%
Case Updated 'Existing line is updated
Call supdate1(c1, "XNewTable", bXNewTable,
Len(bXNewTable))
Case Inserted 'Existing line is new inserted one.
Call sinsert1(c1, "XNewTable", bXNewTable,
Len(bXNewTable))
 Solomon Screen Events 49

Case Deleted 'Existing line was deleted.

Call sdelete1(c1, "XNewTable")
End Select
err1 = mnext(GridHandle%, MaintFlag%)
Wend
' reset memory array currency, then re-display grid
Call MsetRowNum(GridHandle%, Row)
Call Mdisplay(GridHandle%)
End If
End Sub
50 Customization Manager Reference Visual Basic for Applications

Display Event (Solomon Form Object)

Occurs when a form is loaded.
Syntax
Sub object_Display ()
Remarks
This event occurs after an application screen form is displayed (painted on the screen).

Note: When you create procedures for related events, such as Activate, GotFocus,
Paint, and Resize, be sure that their actions don’t conflict and that they don’t cause
recursive events.

Example
Global GridHandle%
Sub Form1_Display()

' Extend the current grid with the new table.

GridHandle = GetGridHandle("Spread1")
serr1 = VBA_MExtend(GridHandle, bXNewTable, Len(bXNewTable))

Call DisplayGrid
End Sub
 Solomon Screen Events 51

Hide Event (Solomon Form Object)

Occurs when a form is loaded.
Syntax
Sub object_Hide ()
Remarks
This event occurs after an application screen form is hidden (no longer displayed).
Note: When you create procedures for related events, such as Activate, GotFocus,
Paint, and Resize, be sure that their actions don’t conflict and that they don’t cause
recursive events.
52 Customization Manager Reference Visual Basic for Applications

Load Event (Solomon Form Object)

Occurs when a form is loaded.
Syntax
Sub object_Load ()
Remarks
This event occurs for all forms for an application while the screen is loading.

Note: When you create procedures for related events, such as Activate, GotFocus,
Paint, and Resize, be sure that their actions don’t conflict and that they don’t cause
recursive events.

Example
Sub Form1_Load()

' Allocate buffer and cursor for custom table containing additional
fields.

Call SetAddr("bxNewTable", bxNewTable, nxNewTable, Len(bxNewTable))

Call SQLCursor(c1, NOLEVEL + SQLUpdate)
End Sub
 Solomon Screen Events 53

LineChk Event (Solomon Grid Object)

Occurs whenever a detail line within a Solomon Grid control is either inserted, updated
or deleted.
Syntax
Sub object_ LineChk (Action, RecMaintFlg, RetVal)
Remarks
Any time the user inserts, updates or deletes a detail line in an SAFGrid control, the
LineChk event fires. In the insert and update cases, the event does not actually execute
until the user actually leaves the detail line.
This event is most often used to perform special delete logic for detail lines that the
user is attempting to delete. For example, the General Ledger Chart of Accounts
Maintenance screen contains a grid displaying all records from the Account table.
Users can delete Account records provided that the corresponding account number is
not used on any setup screens among other areas. This is actually implemented via the
use of logic within the LineChk event.
Deleted records are copied from the underlying memory array to a temporary “deleted
record” memory array. The resource handle to that memory array can be obtained
using the MGetDelHandle function.
The LineChk event uses the following arguments:

Argument Type Description

Action integer Action being performed on the detail line.
RecMaintFlg integer Current status of the detail line.
RetVal integer The application can prevent record deletions by simply
setting RetVal to either a valid message number or the
ErrNoMess symbolic constant defined in the
VBTools_VBA module.
The VBTools_VBA module contains the following symbolic constants defining
possible Action values:

RetVal Description
INSERTED A new detail line is being inserted.
UPDATED An existing detail line is being updated.
DELETED An existing detail line is being deleted.
ABANDONED An existing detail line was never created and is being abandoned.
54 Customization Manager Reference Visual Basic for Applications

The VBTools_VBA module contains the following symbolic constants defining

possible RecMaintFlg values:

RetVal Description
NEWROW Indicates that the user is beginning the insertion of a new detail line.
The status of the detail line will be changed to INSERTED after all
fields have been error checked and no errors occur during the LineChk
event.
INSERTED The current detail line was successfully added after the Solomon Grid
was loaded and has not been saved to the database.
UPDATED The current detail line was initially loaded into the Solomon Grid but
has been subsequently modified. Furthermore, the modifications to the
current detail line have not yet been saved.
NOTCHANGED The current detail line was initially loaded into the Solomon Grid and
has not been subsequently modified. Note: Records marked as
INSERTED and UPDATED will automatically be assigned the
NOTCHANGED status after the next successful Save operation.

Example

Sub Spread1_LineChk(action%, maintflg%, retval%)

Dim FieldValue As String * 20

Dim Dvalue As Double

If action% = INSERTED Or action% = UPDATED Then

Call GetBufferValue("bTableA.FieldA",FieldValue)
Dvalue = GetObjectValue("cqty")

If Trim$(FieldValue) = "" And Dvalue > 0.0 Then

retval = 2 ' Must set the Field Value if a Quantity
exist.
Call ApplSetfocus("cqty")
End If
End If
End Sub
 Solomon Screen Events 55

LineGotFocus Event (Solomon Grid Object)

Occurs whenever a detail line within a Solomon Grid control receives focus.
Syntax
Sub object_ LineGotFocus (RecMaintFlg, RetVal)
Remarks
Any time the user moves to or inserts a detail line within a Solomon Grid control, the
LineGotFocus event is called immediately.
The RecMaintFlg parameter can subsequently be evaluated to determine whether or
not the user is actually adding a new detail line. In such a case, default values can be
explicitly assigned to fields within the detail record for which no corresponding control
exist. For example, assume TableA is a header table and TableB is a detail record. In
this case, each unique TableA record could have many unique TableB records
displayed within the SAFGrid. However, the primary point to make here is that the first
segment of the unique key for TableB would have to include a field that relates directly
to TableA (e.g. the join field). This type of field is a prime candidate to be defaulted in
the LineGotFocus event since it will always have the same value (e.g. the value of
TableA.KeyField) and therefore creating an invisible control with a Default property is
not really necessary.
The LineGotFocus event uses the following arguments:

Argument Type Description

RecMaintFlg integer Status of the detail line.
RetVal integer The application can prevent all of the corresponding detail
level controls from being automatically defaulted when a
new record is being inserted by simply setting RetVal to
NoAction (which is a symbolic constant defined in the
VBTools_VBA module).
56 Customization Manager Reference Visual Basic for Applications

The VBTools_VBA module contains the following symbolic constants defining

possible RecMaintFlg values:

RetVal Description
NEWROW Indicates that the user is beginning the insertion of a new detail line. The
status of the detail line will be changed to INSERTED after all fields have
been error checked and no errors occur during the LineChk event.
INSERTED The current detail line was successfully added after the Solomon Grid was
loaded and has not been saved to the database.
UPDATED The current detail line was initially loaded into the Solomon Grid but has
been subsequently modified. Furthermore, the modifications to the current
detail line have not yet been saved.
NOTCHANGED The current detail line was initially loaded into the Solomon Grid and has
not been subsequently modified. Note: Records marked as INSERTED and
UPDATED will automatically be assigned the NOTCHANGED status after
the next successful Save operation.

Example 1
The following example is taken from the Payroll module’s Earnings Type Maintenance
(02.270.00) window. This screen is a header/detail type of screen having the EarnType
table as the header table and two detail records in the grid – namely ValEarnDed and
Deduction. ValEarnDed is the master table for the detail level and the Deduction table
is only joined in for a description. At any rate, notice the test for NEWROW and the
corresponding work that is only performed for new detail lines.
Sub Spread_ValEarnDed_LineGotFocus (maintflg%, retval%)
If (maintflg = NEWROW) Then

'Null out secondary records on the detail line

bDeduction = nDeduction

'Initialize the master detail record with the key field ↵

ID from the
'header record
bValEarnDed.EarnTypeId = bEarnType.Id
End If
End Sub

Example 2
Sub Spread1_LineGotFocus(action%, maintflg%, retval%)
If maintflg% = NEWROW Then
' Default current line field.
Dim FieldValue As String * 20
Call GetBufferValue("bTableA.FieldA",FieldValue)
Call SetBufferValue("bTableB.FieldA", FieldValue)
End If
End Sub
 Solomon Screen Events 57

OnCancel Event (Solomon Update Object)

Occurs when the user clicks the Cancel button (or Escape key) on the Solomon toolbar.
Syntax
Sub object_ OnCancel (Level, RetVal)
Remarks
When the user clicks the Cancel button on the Solomon toolbar, the OnCancel event is
called once for each level in order from LEVEL0 to LEVELn.
This event is normally used on single Constant level applications, such as Setup
screens. These types of applications do not have key fields that can be re-executed in
order to re-fetch the currently displayed information. Consequently, the OnCancel
event provides the application with an opportunity to re-fetch the Constant level record
(e.g. for example the setup record).
The OnCancel event uses the following arguments:

Argument Type Description

Level integer Current level being processed.
retval integer The corresponding Solomon message will be displayed if
RetVal is modified to anything other than the ErrNoMess
symbolic constant defined in the VBTools_VBA module.

Example 1
The following code snippet was taken from the Payroll Employee Maintenance screen.
Sub OnCancel (level%, retval%)

Dim PRSetup_Fetch As Integer

'Initialize bPRSetup
PRSetup_Fetch = SqlFetch1(CSR_PRSetup, "PRSetup_All", bPRSetup, ↵
LenB(bPRSetup))

If (PRSetup_Fetch = 0) Then
'Display fields from existing PRSetup record
Call DispFields(PNULL, PNULL, PNULL)
Else
'Default all controls for insert mode
Call SetDefaults(PNULL, PNULL, PNULL)
End If
End Sub

Example 2
Global GridHandle%
58 Customization Manager Reference Visual Basic for Applications

Sub OnCancel(level%, retval%)

' Null out the New Description Column and re-display it since it
will be reloaded
Call Mset("cdescr1", nXTablet.Descr)
Call Mdisplay(GridHandle)

' Change to not changed since NULLing out changes status

Call SetLevelChg(Level0, NOTCHANGED)

' Reload the grid

Call DisplayGrid

End Sub
 Solomon Screen Events 59

OnFinish Event (Solomon Update Object)

Occurs when the user indicates he/she is finished with the information currently
displayed on the screen.
Syntax
Sub object_ OnFinish (Level, Updated, RetVal)
Remarks
The OnFinish event is called when the user is finished with the currently displayed
information so as to allow the application an opportunity to perform specific operations
on or related to the data before it “leaves the user’s screen.” For example, assume the
user just entered some sort of financial information and now he/she is simply going to
close the application since they have completed their original task. At that point the
application could warn the user that the information is out of balance and ask whether
or not they want to remedy the problem. Without such a warning, the user may not
notice the error until it subsequently causes some other problem.
The user is considered “finished” with the currently displayed information when they
perform any one of the following operations:
• When the user clicks on the Finish button on the Solomon toolbar. In this case, the
OnFinish event actually fires after the OnUpdate event – if a save operation is
even necessary (e.g. if any information changed).
• When the user attempts to either enter a new item, navigate to a different item or
close the screen. If information has been changed then the user will first be
prompted as to whether or not they want to save their outstanding changes. If not
then the screen will be refreshed with the information as it exists in the database so
that accurate data is readily available when the OnFinish event is called.
The OnFinish event is called once for each level in order from LEVELn to LEVEL0.
Notice that this event is called in reverse order as compared to the NewLevel,
OnUpdate, OnDelete and OnCancel events. This reverse order allows the application to
report problems with the data at the most granular level first.
The application can abort the OnFinish event by merely changing the RetVal
parameter. In this case, the users action is also aborted. For example, assume the user
has RecordA on the screen and then clicks the Next button on the Solomon toolbar.
Clearly this indicates that the user is finished viewing RecordA and now wants to view
the next record – presumably RecordB. Consequently, the OnFinish event is called just
prior to navigating to RecordB. If the application sets RetVal, say to a Solomon
message number, then the corresponding message will be displayed when the OnFinish
event for the current level exits and the navigate operation will be aborted. Since the
navigation operation was aborted, the user will still be able to view RecordA.
60 Customization Manager Reference Visual Basic for Applications

The OnFinish event uses the following arguments:

Argument Type Description

Level integer Current level being processed. The OnFinish event is called
beginning with LEVELn (i.e. the last level on the screen)
and counting backwards to LEVEL0.
Updated integer Currently not used.
retval integer The OnFinish event can be aborted by simply setting
RetVal to either a valid message number or the ErrNoMess
symbolic constant defined in the VBTools_VBA module.
 Solomon Screen Events 61

OnInsert Event (Solomon Update Object)

Occurs during the series of actions/events initiated by an Insert operation.
Syntax
Sub object_ OnInsert (Level, RetVal)
Remarks
To understand when the NewLevel event occurs, a developer must first understand the
higher level concept of what is referred to here as an Insert operation. The operation is
differentiated from the event in the fact that the NewLevel event comprises only a
segment of a series of events implied by a Insert operation.
Any one of the following occurrences initiates an Insert operation:
• When ScreenInit is called from within Form1_Load.
• When the user clicks on the New button on the Solomon toolbar.
• When the user clicks on the Finish button on the Solomon toolbar. In this case, the
NewLevel event actually fires after the OnUpdate and OnFinish events complete
successfully.
• When the user clicks on the Delete button on the Solomon toolbar. After the record
is successfully deleted in the OnDelete event, the application prepares itself to
receive new information by automatically initiating an Insert operation.
• When the user navigates either prior to the first record or past the last record in a
table using either the Prev or Next buttons on the Solomon toolbar.
• When the user enters a value that does not already exist in the database for one or
more key fields. For example if an application contains three key fields then an
Insert operation will be initiated if the combination of all three key field values
does not already exist in the database.
An Insert operation is comprised of the following series of actions and/or events for
each non-detail level – beginning with the level on which the new operation was
initiated. For example, if the Insert operation is initiated on LEVEL0, the levels will be
processed in order from LEVEL0 to LEVELn.
• The master table for the level is blanked out. The master table for any particular
level is the table identified by the VBA_SetAddr call for that particular level.
• The NewLevel event is called for the level.
• All controls on the level are defaulted.
Since defaulting for new detail level records within a Solomon Grid control is
performed within the LineGotFocus event, the NewLevel event is not called for detail
levels.
62 Customization Manager Reference Visual Basic for Applications

The OnInsert event uses the following arguments:

Argument Type Description

Level integer Current level being processed.
retval integer The automatic defaulting of all controls on the current level
which occurs after the NewLevel event for that particular
level can be suppressed by setting RetVal to the NoAction
symbolic constant defined in the VBTools_VBA module.

Example
The following code snippet was taken from the Payroll Employee Maintenance screen.
Sub OnInsert (level%, retval%)
If (level = LEVEL0) Then
'Force ALL default values to be applied to EMPLOYEE level ↵
BEFORE
'Evaluate_Properties() is called.
Call Level_SetDefaults(PNULL, PNULL, PNULL, LEVEL0)
bEmployee.CalQtr = bPRSetup.CurrCalQtr
bEmployee.CalYr = bPRSetup.CurrCalYr
'Re-evaluate the properties of all controls whose ↵
property settings
'depend upon data values.
Call Evaluate_Properties(FLD_ALL)
'Set retval to keep Swim from defaulting LEVEL0 controls ↵
again.
RetVal = NoAction
End If
End Sub
 Solomon API Function Calls 63

Solomon API Function Calls

Solomon API Reference Summary

The following is a list of the Solomon API functions available in the Visual Basic for
Applications Language and a brief summary of their purpose.

Function/Statement Action
AliasConstant Statement Aliases certain Solomon constants used specifically by
Transaction Import.
ApplGetParms Function Retrieves a command line parameter passed by another
Solomon application.
ApplGetParmValue Function Retrieves a parameter passed by another application.
ApplSetFocus Statement Sets focus to a designated object.
ApplSetParmValue Statement Adds a parameter to the list of all parameters which
will be sent to a calling application.
CallChks Function Executes Chk event of the specified object.
DateCheck Function Validates a date.
DateCmp Function Compares two dates.
DateMinusDate Function Returns the number of days between two dates.
DatePlusDays Statement Adds a specified number of days to a date.
DatePlusMonthSetDay Statement Adds a specified number of months to a date and sets
to a valid day.
DateToIntlStr Function Converts a date into the Windows short date style.
DateToStr Function Converts a date to a string.
DateToStrSep Function Converts a date to a string and includes separators.
DBNavFetch Functions Retrieves a composite record from the database using
an SQL statement.
DispFields Statement Displays the contents of a field structure.
DispForm Statement Displays a specified form object.
DParm Function Convert a date into an SQL parameter string.
Edit_Cancel Statement Executes the Cancel toolbar button.
Edit_Close Statement Executes the Close toolbar button.
Edit_Delete Function Executes the Delete toolbar button.
Edit_Finish Function Executes the Finish toolbar button.
Edit_First Function Executes the First toolbar button.
Edit_Last Function Executes the Last toolbar button.
Edit_New Function Executes the New toolbar button.
64 Customization Manager Reference Visual Basic for Applications

Function/Statement Action
Edit_Next Function Executes the Next toolbar button.
Edit_Prev Function Executes the Previous toolbar button.
Edit_Save Statement Executes the Save toolbar button.
FPAdd Function Floating point Add function.
FParm Function Formatting function for a float field passed to an SQL
function.
FPDiv Function Floating point Divide function.
FPMult Function Floating point Multiply function.
FPRnd Function Floating point Rounding function.
FPSub Function Floating point Subtraction function.
GetBufferValue Statement Obtains buffer value for a specified field.
GetDelGridHandle Function Returns the resource handle of the memory array used
to temporarily hold detail lines deleted from the
designated SAFGrid control.
GetGridHandle Function Obtains a grid handle for a spreadsheet object.
GetObjectValue Function Obtains the field value of a specified object.
GetProp Function Obtains a property for the specified object.
GetSqlType Function Determine which type of database server is being used.
GetSysDate Statement Obtains the current system date.
GetSysTime Statement Obtains the current system time.
HideForm Statement Hides specified form object.
IncrStrg Statement Increments a string value.
IntlStrToDate Statement Converts date string from Windows short date style
into SQL database date format.
IParm Function Formatting function for an integer field passed to an
SQL function.
Is_TI function Returns whether or not the Solomon application is in
Transaction Import mode.
Launch Function Launches another executable program.
MCallchks Function Perform error checking on a specific grid object’s
column.
MClear Statement Delete all records from the designated memory array.
MClose Statement Close an existing memory array.
MDelete Function Delete the current record from the designated memory
array.
MDisplay Statement Display the current contents of the designated memory
array in its corresponding spreadsheet control.
Mess Statement Displays the specified Solomon message number.
 Solomon API Function Calls 65

Function/Statement Action
Messbox Statement Displays a message box with parameters provided.
Messf Statement Displays the specified Solomon message number with
substitution variables.
MessResponse Function Obtains user response from a message box.
MFindControlName Function Returns a list of control names present in the current
application.
MFirst Function Move to the first record in a designated memory array.
MGetLineStatus Function Returns the line status of the current record in the
designated memory array.
MGetRowNum Function Returns the row/record number of the current record in
the designated memory array.
MInsert Statement Inserts a new record into a designated memory array.
MKey Statement Defines a key field for a previously opened memory
array.
MKeyFind Function Finds a specific record within a sorted memory array
based on designated key field values.
MKeyFld Statement Defines a key field for a previously opened memory
array.
MKeyOffset Statement Defines a key field for a previously opened memory
array.
MLast Function Moves to the last record in a designated memory array.
MLoad Statement Loads a memory array with all records returned from
the database by an SQL statement.
MNext Function Moves to the next record in a designated memory
array.
MPrev Function Moves to the previous record in a designated memory
array.
MRowCnt Function Returns the number of records in a designated memory
array.
MSet Statement Sets a grid column to specified value.
MSetLineStatus Function Sets the line status of the current record in the
designated memory array.
MSetProp Statement Sets the properties of a grid column at runtime.
MSetRowNum Statement Sets the current row / record number of a designated
memory array.
Msort Statement Sort data contained within an existing memory array
based upon predefined key fields.
MUpdate Statement Updates the current memory array record of a
designated memory array with new data values.
NameAltDisplay Function Displays the name field with swap character
suppressed.
66 Customization Manager Reference Visual Basic for Applications

Function/Statement Action
PasteTemplate Function Pastes information from the designated template into
the current application.
PeriodCheck Function Performs period number validation on current field.
PeriodMinusPeriod Function Determines the difference between two period
numbers.
PeriodPlusPerNum Function Adds a number of periods to a period.
PVChkFetch Functions Retrieves a composite record from the database using
an SQL statement from the PV property of an
SAFMaskedText control.
SaveTemplate Statement Saves information from the current application to a
designated template.
Sdelete Function Deletes the current record in view.
SdeleteAll Function Deletes all records from a table in the view.
SetBufferValue Statement Sets an underlying Solomon application’s data buffer
field to a specified value.
SetDefaults Function Displays the default value for the specified object.
SetLevelChg Statement Sets a certain level number to a different status.
SetObjectValue Function Sets a specified object field’s value.
SetProp Statement Sets properties of objects at runtime.
SetStatusBarText Statement Display text in the Application Status Bar.
SFetch Functions Fetches the next record into view.
SGroupFetch Functions Group fetches the next aggregate value into view.
SInsert Statements Inserts the structure from the current view into a table.
Sparm Function Formatting function for a string field passed to an SQL
function.
Sql Statement Executes the specified SQL statement.
SqlCursor Statement Allocates an SQL cursor for a view of a table.
SqlCursorEx Allocate a new database cursor.
SqlErr Function Obtains the return value of the specified SQL function.
SqlErrException Statement Allows an application to trap certain SQL errors.
SqlExec Statement Executes the specified SQL statement after passing
variables.
SqlFetch Functions Executes the SQL statement and fetches the first record
into view.
SqlFree Statement Frees a cursor.
SqlSubst Statement Substitutes variables into an SQL statement.
StrToDate Statement Converts a string to a date field type.
StrToTime Statement Converts a string to a time field type.
 Solomon API Function Calls 67

Function/Statement Action
SUpdate Statements Updates the current view.
TestLevelChg Function Determines whether or not a specified level has
changed.
TimeToStr Function Converts time to a string.
TranAbort Statement Aborts the current transaction.
TranBeg Statement Begins a database transaction.
TranEnd Statement Ends a database transaction.
TranStatus Function Returns the current SQL database transaction status.
VBA_MExtend Function Extend the grid of an application so that another table’s
structure can be added to the grid.
VBA_MOpen Functions Open a new memory array and return a corresponding
unique memory array number.
VBA_SetAddr Statement Allocates a structure for a specified database table.

Note: In the following sections, some example code may exceed one line. In this case,
the symbol ↵ indicates a line continuation character. The entire line must be on a single
line in the event code window.
68 Customization Manager Reference Visual Basic for Applications

AliasConstant Statement
Use this function to alias certain Solomon constants used specifically by Transaction
Import. This can be helpful if you are using a different language (the English words
like Comment, Insert, and Change could be replaced by the other language’s
alternative words). The possible values are listed below.
Syntax
Call AliasConstant(Constant, Alias )
Remarks
Constants that can be redefined using the AliasConstant function include:
• Comment
• Insert
• Delete
• Change
• Processed
• Separator
• Delimiter
• LevelN (where N is 0 to 9)
• Checked
• Unchecked
• Press
Example
Call AliasConstant("Change", "Update")
Call AliasConstant("Delimiter", ";")
Call AliasConstant("Separator", "!")
Call AliasConstant("Level0", "Batch")
Call AliasConstant("Level1", "Detail")
 Solomon API Function Calls 69

ApplGetParms Function
Retrieve a parameter passed by another Solomon Tools for Visual Basic® application.
Syntax
ParmValue = ApplGetParms()
Remarks
The ApplGetParms statement can be used to retrieve parameters, which were
originally passed by another Solomon Tools for Visual Basic application using the
Launch function. Making successive calls to ApplGetParms can retrieve multiple
parameters.
If the calling application passed parameters via named parameter sections, using the
ApplSetParmValue statement in conjunction with the Launch function, then
ApplGetParms will only be able to retrieve parameters from the default Solomon
section. The ApplGetParmValue function is the only means by which the called
application can retrieve parameters from any named parameter section other than the
default Solomon section.
The ApplGetParms function uses the following argument:

Argument Type Description

ParmValue String The actual value of the next parameter to be retrieved

Example
Following code for 03.270.00 (the launched application):
Sub Form1_Load
' Variable to store the passed Parameter to this screen
' Under RDT scenario, this code would be in Form_Load.
Dim VendorParm$
VendorParm = ApplGetParms()
If Trim$(VendorParm) <> "" Then
' Screen was called from another application.
' Set the value of the ID field to what was
' passed in by Launch() function
serr1 = SetObjectValue("cvendid", VendorParm)
End If
End Sub

See Also
ApplGetParmValue Function, ApplSetParmValue Statement, Launch Function
70 Customization Manager Reference Visual Basic for Applications

ApplGetParmValue Function
Retrieve a parameter passed by another Solomon Tools for Visual Basic application.
Syntax
ParmValue = ApplGetParmValue(ParmSection, ParmName)
Remarks
Parameters passed to a Solomon Tools for Visual Basic application can be retrieved via
one of two different methods: ApplGetParms and ApplGetParmValue. These
functions differ in that ApplGetParms does not support multiple parameter sections
whereas ApplGetParmValue does provide this more sophisticated functionality.
Consequently, ApplGetParmValue is the only means by which the called application
can retrieve parameters from any named parameter section other than the default
Solomon section. For example, if the calling application sends a parameter specifically
designated as a VBA parameter, only the ApplGetParmValue function can be used to
retrieve that particular parameter since the VBA section name can be explicitly queried
via the ParmSection argument.
Named parameter sections facilitate the elimination of conflicts which can occur in the
destination program when the application itself as well as custom VBA code added via
the Customization Manager are both attempting to receive different parameters. For
example, in Solomon, the Accounts Payable module’s Document Maintenance
(03.250.00) window can optionally receive two parameters that facilitate drill-down
functionality: Reference Number and Vendor ID. The Form_Load event always calls
ApplGetParms once to determine if any parameters have been passed to the
application. If even one parameter exists it is assumed that it is the Reference Number
and therefore the application calls ApplGetParms again expecting the next parameter
to be the Vendor ID. If adding calls to ApplGetParms using VBA code subsequently
customizes this screen, an operational conflict will occur. If such an application were
to be called with only one parameter, designed to be received by the custom VBA
code, it would instead be received by the call to ApplGetParms performed by the
underlying application. Consequently the call to ApplGetParms in VBA code would
not return any parameter value at all.
ApplSetParmValue and ApplGetParmValue overcome this operational conflict by
facilitating the usage of named parameter sections. Using this more sophisticated
method, parameters can be passed directly to the application itself and to custom VBA
code using the two standard section names declared in the VBTools_VBA module (i.e.,
PRMSECTION_VBRDT and PRMSECTION_BSL). Parameter sections are not,
however, limited to these two standard section names. Thus for example “[XYZ
Section]” is a valid section name. The brackets are required since parameter sections
themselves are handled similar to section names within an .INI file. In the previously
mentioned example, a custom parameter could be sent to the Accounts Payable
Document Maintenance screen in the VBA parameter section such that only calls to
ApplGetParmValue specifically requesting VBA parameters would retrieve the
parameter.
 Solomon API Function Calls 71

The ApplGetParmValue statement uses the following arguments:

Argument Type Description

ParmValue String The actual value of the parameter being retrieved.
ParmSection String Name of the section within the temporary parameter file
from which the parameter should be retrieved. Any section
name can be used such as “XYZ Section” – provided the
calling application utilized a so named parameter section.
The VBTools_VBA module contains three symbolic
constants defining standard section names:
PRMSECTION_VBRDT, PRMSECTION_BSL and
PRMSECTION_TI. PRMSECTION_TI is reserved for
usage in conjunction with Transaction Import. By default,
the parameter will be retrieved from the section represented
by PRMSECTION_VBRDT if this argument is left blank.
ParmName String Logical name of the parameter being retrieved. By default,
parameter names are sequentially numbered (i.e., PRM01,
PRM02....PRM99) if they were not explicitly named by the
call to ApplSetParmValue in the calling application.

Example
The following example will illustrate how to pass parameters to a Solomon Tools for
Visual Basic application and custom VBA code at the same time – and avoid conflicts
between the two.
Code in the calling application:
Call ApplSetParmValue(PRMSECTION_VBRDT, "Batch Nbr", "000001")
Call ApplSetParmValue(PRMSECTION_VBRDT, "Document Nbr", "123456")
Call ApplSetParmValue(PRMSECTION_BSL, "Example Parm", "Example ↵
Parameter To VBA or BSL Code")
'Call another Solomon application
Launch( "SOLOMONAPP", "")
Code in the standard Solomon Tools for Visual Basic application (i.e., non
customization code) receiving the standard parameters.
Dim Parm_BatchNbr As String
Dim Parm_DocumentNbr As String
Parm_BatchNbr = ApplGetParmValue(PRMSECTION_VBRDT, "Batch Nbr"
Parm_DocumentNbr = ApplGetParmValue(PRMSECTION_VBRDT, "Document Nbr")
Basic Script code, overlaying the standard Solomon Tools for Visual Basic application,
designed to retrieve custom parameters:
Dim Parm_CustomParm As String

Parm_CustomParm = ApplGetParmValue(PRMSECTION_BSL, "Example Parm")

See Also
ApplGetParms Function, ApplSetParmValue Statement, Launch Function
72 Customization Manager Reference Visual Basic for Applications

ApplGetReturnParms Function
Retrieve a parameter returned from a now terminated secondary application.
Syntax
ParmValue = ApplGetReturnParms()
Remarks
If a Solomon Tools for Visual Basic application needs to pass parameters back to the
program from which it was originally called it can do so using one of the parameters to
ScreenExit. When control subsequently returns to the calling application, it can issue
one or more calls to ApplGetReturnParms to successively retrieve each individual
parameter.
The ApplGetReturnParms function has the following arguments:

Argument Type Description

ParmValue String The actual value of the parameter being retrieved from a
now terminated secondary program.

See Also
ScreenExit Statement
 Solomon API Function Calls 73

ApplSetFocus Statement
Set focus to a designated control.
Syntax
Call ApplSetFocus( TargetCtrl)
Remarks
ApplSetFocus is the preferred method to explicitly set focus to a target control. Usage
of the Visual Basic SetFocus method will cause a fatal VB error if the target control is
disabled or invisible. Developers must always remember that the design time property
setting of the target control cannot be guaranteed to always retain the same value at
runtime. For example, the target control may be both visible and enabled in the
standard application and therefore the .SetFocus will appear to work properly during
testing. However, the end user may subsequently apply a customization which among
other things disables the target control – thereby uncovering a subtle flaw in the
underlying application with regards to its usage of the .SetFocus method.
The ApplSetFocus statement uses the following arguments:

Argument Type Description

TargetCtrl string Control to which focus should be moved

Example
Call ApplSetFocus("cDiscBal")
74 Customization Manager Reference Visual Basic for Applications

ApplSetParmValue Statement
Add one additional parameter to the list of all parameters which will be sent to the next
application called by the Launch function.
Syntax
Call ApplSetParmValue(ParmSection, ParmName, ParmValue)
Remarks
Solomon Tools for Visual Basic uses the Launch function to start another application.
There are two different methods for the calling program to pass parameters to the
called program.
The first method is to pass the parameters to the called program using the argument to
Launch specifically designed for this purpose. Parameters passed via this method are
all grouped together and passed directly to the called application via the physical
command line itself. Consequently, under this method the size and/or number of
parameters is limited to the maximum command line length less the number of bytes
used by Solomon for internal requirements, which can vary based on the situation.
A more robust method of passing parameters is to use the ApplSetParmValue
statement in conjunction with the Launch function. The principle advantage of using
this method is that it allows the calling application to group parameters into named
sections and explicitly label individual parameters using unique parameter names.
Grouping parameters into named sections eliminates conflicts that will occur in the
called program when the application itself as well as custom VBA code added via the
Customization Manager are both attempting to receive different parameters. See the
ApplGetParmValue function for a more detailed explanation of these potential
conflicts.
The first call to ApplSetParmValue will create a temporary destination parameter file
and place the first parameter in that file. By default, this temporary file will be created
in the WINDOWS directory. This default can be overridden using the TempDirectory
entry in the [Miscellaneous] section of the Solomon.ini file. Following is an example
of the C:\TEMP directory specified as the parameter file directory in Solomon.ini:
[Miscellaneous]
TempDirectory=C:\TEMP
Subsequent calls to ApplSetParmValue will write additional parameters to the same
temporary destination parameter file. The fully qualified filename of the completed
parameter file will then be passed to the called program by the Launch function. Once
the called program has successfully loaded, it can call either ApplGetParms or
ApplGetParmValue to retrieve the various parameters passed from the calling
program. When the called program terminates execution, the temporary destination
parameter file will automatically be deleted. ApplSetParmValue is only designed to
facilitate parameter passing to other applications developed with Solomon Tools for
Visual Basic.
 Solomon API Function Calls 75

The ApplSetParmValue statement uses the following arguments:

Argument Type Description

ParmSection String Name of the section within the temporary parameter file to
which the new parameter should be added. Any section
name can be used such as “XYZ Section.” The
VBTools_VBA module contains three symbolic constants
defining standard section names: PRMSECTION_VBRDT,
PRMSECTION_BSL and PRMSECTION_TI.
PRMSECTION_TI is reserved for usage in conjunction
with Transaction Import. By default, the new parameter
will added to the section represented by
PRMSECTION_VBRDT if this argument is left blank.
ParmName String Name assigned to the new parameter. Any name can be
assigned to a parameter such as “Batch Number.” By
default, the new parameter will be assigned the next
sequentially numbered parameter name (i.e., PRM01,
PRM02....PRM99) if this argument is left blank.
ParmValue String The actual value of the new parameter.

Example
The following example will illustrate two different methods of calling ROI to display
the Vendor List report on the screen for all Vendors having a balance greater than zero.
Pass parameters to ROI via one large parameter argument to Launch. This method will
not work with a large WHERE clause since the entire contents of ParmStr must fit on
the physical command line.
Dim ParmStr As String

ParmStr = "03670/RUN" + PRMSEP

ParmStr = ParmStr + "03670S/FORMAT" + PRMSEP
ParmStr = ParmStr + "Vendor.CurrBal > 0/WHERE" + PRMSEP
ParmStr = ParmStr + "/PSCRN"
Call Launch("ROI", ParmStr)
Pass parameters to ROI using ApplSetParmValue in conjunction with Launch. Using
this method, the report will run properly regardless of the length of the WHERE clause.
Call ApplSetParmValue(PRMSECTION_VBRDT, "", "03670/RUN")
Call ApplSetParmValue(PRMSECTION_VBRDT, "", "03670S/FORMAT")
Call ApplSetParmValue(PRMSECTION_VBRDT, "", "Vendor.CurrBal > 0/WHERE")
Call ApplSetParmValue(PRMSECTION_VBRDT, "", "/PSCRN")
Call Launch("ROI", "")

See Also
ApplGetParms Function, ApplGetParmValue Function, Launch Function
76 Customization Manager Reference Visual Basic for Applications

CallChks Function
Perform error checking on a specific object’s Chk event.
Syntax
IntVar = CallChks (formctl$, ctl$)
Remarks
This function is useful when you want to manually execute error checking on a specific
object because another object’s value has been changed. This allows you to “trigger”
another Chk event under program control.
The CallChks function uses the following arguments:

Argument Type Description

IntVar Integer Any integer variable (serr, serr1 – serr12 declared in the
VBTools_VBA module are reserved for this use)
formctl String Form object name
ctl String Control object name to execute Chk event

Example
'Object 1 Chk event
Dim Result#, DrAmt#, CrAmt#

DrAmt = GetObjectValue("cdramt")
CrAmt = GetObjectValue("ccramt")
Result = FPAdd(DrAmt, CrAmt, MONEY)
If Result < 0 Then
Call MessBox("Negative Entry", MB_OK, "Message")
End If

'Object 2 Chk event (contains ccramt)

serr1 = CallChks("Form1", "object1")

See Also
GetObjectValue Function, SetObjectValue Function
 Solomon API Function Calls 77

DateCheck Function
Verify whether or not a date string in MMDDYYYY format represents a valid date.
Syntax
RetVal = DateCheck(DateString)
Remarks
The DateCheck function uses the following arguments:

Argument Type Description

RetVal Integer 0 if the date string represents a valid date. -1 indicates an invalid
day. -2 indicates an invalid month.
DateString String Date string to be verified. Must be in MMDDYYYY format.

Example
datestr = "02291991"
serr = DateCheck(datestr)
If serr = -1 Then
'Invalid day
Else If serr = -2 Then
'Invalid month
End If
Example performs error checking on a string field that is formatted as a date. The
following in its chk event:
Sub cuser1_Chk(chkstrg$, retval%)
serr = DateCheck(chkstrg)
If serr = -1 Then
' Invalid Day
Call Messbox("Invalid day, please re-enter", MB_OK, "Message")
retval = errnomess
ElseIf serr = -2 Then
' Invalid Month
Call Messbox("Invalid month, please re-enter", MB_OK,
"Message")
retval = errnomess
End If
End Sub

See Also
StrToDate Statement
78 Customization Manager Reference Visual Basic for Applications

DateCmp Function
Compare two date values.
Syntax
Cmp = DateCmp(Date1, Date2)
Remarks
To determine whether or not a date value is null use DateCmp (Date, NULLDATE).
NULLDATE is global variable declared in the VBTools_VBA module that is properly
initialized by the system at the start of all Solomon Tools for Visual Basic applications.
The DateCmp function uses the following arguments:

Argument Type Description

Cmp Integer <0 if Date1 < Date2
0 if the two dates are equal.
>0 if Date1 > Date2
Date1 SDate user-defined First date value
datatype (declared in the
VBTools_VBA module)
Date2 SDate user-defined Second date value
datatype (declared in the
VBTools_VBA module)

Example
Dim TestDate1 As Sdate
Dim TestDate2 As Sdate
TestDate1.Val = GetObjectValue("cinvcdate")
TestDate2.Val = GetObjectValue("cdocdate")
serr1 = DateCmp(TestDate1, TestDate2)
If serr1 = 0 Then
Call MessBox("Dates are equal", MB_OK, "Message")
ElseIf serr1 > 0 Then
Call MessBox("invdate greater", MB_OK, "Message")
ElseIf serr1 < 0 Then
Call MessBox("docdate greater", MB_OK, "Message")
End If
 Solomon API Function Calls 79

DateMinusDate Function
Return the number of days between two dates.
Syntax
NbrDays = DateMinusDate(Date1, Date2)
Remarks
The DateMinusDate function uses the following arguments:

Argument Type Description

NbrDays Long Number of days between Date1 and Date2
including the ending date. If Date1 > Date2 then
the number of days between the two dates will be
a negative value.
Date1 SDate user-defined Beginning date
datatype (declared in the
VBTools_VBA module)
Date2 SDate user-defined Ending date
datatype (declared in the
VBTools_VBA module)

Example
Dim Date1 As Sdate
Dim Date2 As Sdate

Date1.Val = GetObjectValue("cdate1")
Date2.Val = GetObjectValue("cdate2")

serr1 = DateMinusDate(Date1, Date2)

Call MessBox("Number of Days is " + Str$(serr1), MB_OK, "Message")

See Also
DatePlusDays Statement, DatePlusMonthSetDay Statement
80 Customization Manager Reference Visual Basic for Applications

DatePlusDays Statement
Add a designated number of days to an existing date.
Syntax
Call DatePlusDays(CurrDate, NbrDaysToAdd, ResultingDate)
Remarks
The DatePlusDays statement uses the following arguments:

Argument Type Description

CurrDate SDate user-defined Starting date value.
datatype (declared in the
VBTools_VBA module)
NbrDaysToAdd Integer Number of days to add to CurrDate.
Negative values are supported.
ResultingDate SDate user-defined Result of CurrDate + NbrDaysToAdd.
datatype (declared in the
VBTools_VBA module)

Example
Dim OldDate As Sdate
Dim NewDate As Sdate
Dim DaysToAdd%

OldDate.Val = GetObjectValue("cdocdate")
DaysToAdd = 30

Call DatePlusDays(OldDate, DaysToAdd, NewDate)

Call MessBox("New Date is " + DateToStrSep(NewDate), MB_OK, "Message")

See Also
DateMinusDate Function, DatePlusMonthSetDay Statement
 Solomon API Function Calls 81

DatePlusMonthSetDay Statement
Add a designated number of months to an existing date and set the day portion of the
resulting date to a specific day of the month.
Syntax
Call DatePlusMonthSetDay(CurrDate, NbrMthsToAdd, SetSpecificDay,
ResultingDate)
Remarks
The DatePlusMonthSetDay statement uses the following arguments:

Argument Type Description

CurrDate SDate user-defined Starting date value.
datatype (declared in the
VBTools_VBA module)
NbrMthsToAdd Integer Number of months to add to CurrDate.
Negative values are supported.
SetSpecificDay Integer Desired value for the day portion of the
resulting date. In cases where
SetSpecificDay is beyond the last valid day
for the relevant month, the system will
automatically set the actual day value equal
to the last valid day of that month.
ResultingDate SDate user-defined Resulting date.
datatype (declared in the
VBTools_VBA module)

Example
Dim OldDate As Sdate
Dim NewDate As Sdate
Dim DayOfMonth%
Dim MonthsToAdd%

DayOfMonth = 30
MonthsToAdd = 3
Call StrToDate("11211992", OldDate)

Call DatePlusMonthSetDay (OldDate, MonthsToAdd, DayOfMonth, NewDate)

'NewDate will be 02/28/1993 even though the DayOfMonth is 30

Call MessBox("New Date is " + DateToStrSep(NewDate), MB_OK, "Message")

See Also
DateMinusDate Function, DatePlusDays Statement
82 Customization Manager Reference Visual Basic for Applications

DateToIntlStr Function
Convert a specified date into the Windows short date style.
Syntax
ShortDateStr = DateToIntlStr(DateToConvert)
Remarks
DateToIntlStr will convert a date from an SQL database format into a format
governed by the Windows short date style.
DateToIntlStr uses the following arguments:

Argument Type Description

ShortDateStr String String containing the value of
DateToConvert in a Windows short
date style
DateToConvert SDate user-defined datatype Date value to be converted
(declared in Applic.DH)

See Also
DateToStr Function, DateToStrSep Function, IntlStrToDate Statement, StrToDate
Statement
 Solomon API Function Calls 83

DateToStr Function
Convert a date value from an SQL date format into a string in MMDDYYYY format.
Syntax
DateString = DateToStr(DateToConvert)
Remarks
The DateToStr function uses the following arguments:

Argument Type Description

DateString String DateToConvert converted to a string in
MMDDYYYY format
DateToConvert SDate user-defined Date value to be converted
datatype (declared in the
VBTools_VBA module)

Example
'Example sets a field to current system date
Dim NewDate as Sdate
Dim NewStrDate$
Call GetSysDate(NewDate)
NewStrDate = DateToStr(NewDate)
serr1 = SetObjectValue("cpaydate", NewStrDate)

See Also
DateToStr Function, DateToStrSep Function, IntlStrToDate Statement, StrToDate
Statement
84 Customization Manager Reference Visual Basic for Applications

DateToStrSep Function
Convert a date value from an SQL date format into a string in MM/DD/YYYY format.
Syntax
DateString = DateToStrSep(DateToConvert)
Remarks
The DateToStrSep and DateToStr functions differ only in the fact that
DateToStrSep inserts a single character separator between the month, day and year
portions of the string.
The DateToStrSep function uses the following arguments:

Argument Type Description

DateString String DateToConvert converted to a string in
MM/DD/YYYY format
DateToConvert SDate user-defined Date value to be converted
datatype (declared in the
VBTools_VBA module)

Example
Dim TodaysDate As Sdate
Call GetSysDate(TodaysDate)
Call MessBox("Current Date is " + DateToStrSep(TodaysDate), ↵
MB_OK, "Message")

See Also
DateToStr Function, DateToStrSep Function, IntlStrToDate Statement, StrToDate
Statement
 Solomon API Function Calls 85

DBNavFetch Functions
Retrieve a composite record from the database using an SQL statement from the
DBNav property of an SAFMaskedText control.
Syntax
RetVal = DBNavFetch1(Ctrl, Cursor, SQLParmValue, bTable1, bTable1Length)
RetVal = DBNavFetch4(Ctrl, Cursor, SQLParmValue, bTable1, bTable1Length,
bTable2, bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length)
RetVal = DBNavFetch8(Ctrl, Cursor, SQLParmValue, bTable1, bTable1Length,
bTable2, bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length, bTable5,
bTable5Length, bTable6, bTable6Length, bTable7, bTable7Length, bTable8,
bTable8Length)
Remarks
DBNavFetch1, DBNavFetch4 and DBNavFetch8 can be used to fetch a composite
record based on the SQL text from the DBNav property of the SAFMaskedText control
specified in the Ctrl parameter. These functions are not applicable if the DBNav
property does not contain either an SQL statement or stored procedure name.
All SAFMaskedText controls have both a PV and a DBNav property each of which
can contain an SQL statement. The DBNavFetch1 and PVChkFetch1 functions are
similar except that they use SQL statements from two different properties, namely the
DBNav and PV properties. Normally the PVChkFetch1 function will be used in
conjunction with the PV property to facilitate both a Possible Values window as well
as the actual fetch of a record. If the program requirements specify the need to fetch a
record but not supply a Possible Values window then DBNavFetch1 will need to be
used in conjunction with the DBNav property. This situation can arise on screens
containing multiple key fields where the last key field does not need a Possible Value
window. An example of such a case is Employee W2 History (02.260) which has two
key fields: Employee ID and Calendar Year. The requirements for the screen are that
the user be forced to enter a valid Employee ID based on the Employee table which
should be viewable via a Possible Values window. However no table exists in the
Solomon system to define a valid Calendar Year and therefore a Possible Values
window is not applicable since any numeric value is valid. Once the last key field has
been entered a unique record corresponding to both key fields needs to be fetched from
the database. Since Calendar Year is the last key field, and a Possible Value window is
not required for that field, the DBNavFetch1 function was used in conjunction with the
DBNav property of the Calendar Year control.
DBNavFetch1 is designed for SQL statements returning data from a single table. For
more advanced SQL statements having one or more table joins either DBNavFetch4 or
DBNavFetch8 can be used.
86 Customization Manager Reference Visual Basic for Applications

DBNavFetch1, DBNavFetch4 and DBNavFetch8 are all designed to fetch a single

composite record. For example if an SQL statement contains eight table joins,
DBNavFetch8 does not return eight records from a single table. On the contrary it
returns a single record from each of the eight tables. Consequently these functions are
not used in conjunction with the DBNav property of the SAFGrid control. The
DetailLoad statement uses the DBNav property of the SAFGrid control to load the
grid with multiple records from one or more tables.
The DBNavFetch1 function uses the following arguments (DBNavFetch4 and
DBNavFetch8 respectively have four and eight table structures and corresponding
lengths. PNULL should be passed for unused table structure parameters as well as a
corresponding length of zero such as PNULL, 0)

Argument Type Description

RetVal Integer 0 if a record is successfully fetched.
NOTFOUND is returned if no records match
the restriction clause of the DBNav SQL
statement.
Ctrl Control containing the DBNav property to be
used as the SQL statement. Can optionally be
PNULL if the call is made within the Chk
event of the control whose DBNav property is
being used.
Cursor Integer SQL database cursor.
SQLParmValue String Key value passed as the last parameter to the
restriction clause of the DBNav SQL
statement.
bTable1 User-defined datatype Table structure corresponding to the primary
table in the DBNav SQL statement.
bTable1Length Integer Size of first table structure. For example,
LenB(bTable1). Note: It is critical to use
LenB() instead of Len() for all non-null “table
length” parameters.

Example
Sub cCalYr_Chk (chkstrg As String, retval As Integer)
Dim W2Federal_Fetch As Integer

W2Federal_Fetch = DBNavFetch1(PNULL, CSR_W2Federal, chkstrg, ↵

bW2Federal, LenB(bW2Federal))

End Sub

See Also
PVChkFetch Functions
 Solomon API Function Calls 87

DispFields Statement
Display the value of the underlying data field(s) corresponding to the designated
control(s).
Syntax
Call DispFields(Form, Control)
Remarks
Each Solomon data control is associated with an underlying Visual Basic variable via a
combination of its FieldName property and an associated VBA_SetAddr call. The
system will automatically redisplay the new value of relevant controls any time the
system is the entity modifying the value of the underlying VB variable, such as when a
new record is loaded. However, when the application directly modifies the value of a
VB variable underlying an Solomon data control, then it may also need to call the
DispFields statement to display the new value in the relevant control.
DispFields can be used to display a range of controls based on their TabIndex
property order.
The DispFields statement uses the following arguments:

Argument Type Description

Form Control Form containing all controls used in DispFields().
PNULL can be passed to include all loaded forms.
Control Control The control (or control range) that’s underlying data
value is to be displayed. PNULL can be passed to include
all controls on the designated Form. To use a control
range, separate the control names in the string with a
dash (i.e., “cuser1 – cuser8”).
88 Customization Manager Reference Visual Basic for Applications

Example
The following code snippet from the Payroll module’s Earnings Type Maintenance
(02.270.00) window illustrates how the DispFields statement should be used after the
VB variable underlying a particular data control has been modified programmatically.
The code is from the Chk event of the Earnings Type combo box control.
'Displaying all fields on a form
If Level = 0 Then
'Set defaults for all objects on NewInfo subform
'then re-display the results
serr1 = SetDefaults("NewInfo", "")
Call DispFields("NewInfo", "")
End If

'Displaying one field on a form

Dim NewDate as Sdate
Dim NewStrDate$
Call GetSysDate(NewDate)
NewStrDate = DateToStr(NewDate)
serr1 = SetObjectValue("cpaydate", NewStrDate)
Call DispFields("Form1", "cpaydate")

See Also
FieldName Property, MDisplay Statement, TabIndex Property, VBA_SetAddr
Statement
 Solomon API Function Calls 89

DispForm Statement
Display a designated subform.
Syntax
Call DispForm(SubFormName, CenterIt)
Remarks
DispForm will cause the designated subform to be displayed modally, meaning that no
other form from the same application can receive focus until the subform is hidden via
a call to HideForm.
Form1 is always displayed automatically by the system. Consequently, this call is only
necessary for subforms.
The DispForm statement uses the following arguments:

Argument Type Description

SubFormName String Form to be displayed modally.
CenterIt Integer TRUE is the subform is to be centered on the screen.
FALSE if the form should be displayed at its design
time coordinates.

Example
'Display new subform
Call DispForm("NewForm", True)

See Also
HideForm Statement
90 Customization Manager Reference Visual Basic for Applications

DParm Function
Convert a date into an SQL parameter string.
Syntax
SQLParmStr = DParm(DateToConvert)
Remarks
The DParm function uses the following arguments:

Argument Type Description

SQLParmStr String DateToConvert converted into an SQL
parameter string
DateToConvert SDate user-defined Date value to convert
datatype (declared in the
VBTools_VBA module)

Example
'Example retrieves the last voucher date for
'current vendor and selects a count of all documents
'less than the last voucher date

Dim SqlStr$
Dim CountDoc As Long
Dim DateComp As Sdate

DateComp.Val = GetObjectValue("clastvodate")

SqlStr = "Select Count(*) from APDoc Where DocDate < "

+ Dparm(DateComp)

Call Sql(c1, SqlStr)

serr1 = sgroupfetch1(c1, CountDoc, Len(CountDoc))

Call MessBox("Number of Documents: " + str$(CountDoc), MB_OK, "Message")

See Also
FParm Function, IParm Function, SParm Function
 Solomon API Function Calls 91

Edit_Cancel Statement
Executes the Cancel toolbar button.
Syntax
Call Edit_Cancel
Remarks
This function corresponds to the Cancel selection on the Solomon Edit menu and
toolbar. Use of this function allows you to execute Solomon’s Cancel function from a
VBA program.
Example
Example used on push button to perform Cancel function
Sub Cancel_Click()
Call Edit_Cancel
End Sub

See Also
Edit_Close Statement, Edit_Finish Function
92 Customization Manager Reference Visual Basic for Applications

Edit_Close Statement
Executes the Close toolbar button.
Syntax
Call Edit_Close
Remarks
This function corresponds to the Close selection on the Solomon Edit menu and
toolbar. Use of this function allows you to execute Solomon’s Close function from a
VBA program.
Example
Example used on push button to perform close function
Sub Close_Click()
Call Edit_Close
End Sub

See Also
Edit_Next Function, Edit_Last Function
 Solomon API Function Calls 93

Edit_Delete Function
Executes the Delete toolbar button.
Syntax
RetVal = Edit_Delete (LevelNumber)
Remarks
This function corresponds to the Delete selection on the Solomon Edit menu and
toolbar. Use of this function allows you to execute Solomon’s Delete function on the
specified Level% from a VBA program.
The Edit_Delete function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for this
use)
LevelNumber Integer Level number to perform operation

Example
Example navigates to 4th row in Journal entry screen, then deletes the row.
Dim LvlStr$, Lvl%, I%
serr1 = GetProp("cacct", PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)
serr1 = Edit_First(Lvl)

'Already on first row, go down 3 more

For I = 1 To 3
serr1 = Edit_Next(Lvl)
Next I
'Delete existing row
serr1 = Edit_Delete(Lvl)

See Also
Edit_New Function, Edit_Save Statement
94 Customization Manager Reference Visual Basic for Applications

Edit_Finish Function
Executes the Finish toolbar button.
Syntax
RetVal=Edit_Finish(LevelNumber)
Remarks
This function corresponds to the Finish selection on the Solomon Edit menu and
toolbar. Use of this function allows you to execute Solomon’s Finish function from a
VBA program.
The Edit_Finish function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use)
LevelNumber Integer Level number to perform operation

Example
Example performs Finish in a push button
serr1=Edit_Finish

See Also
Edit_Cancel Statement, Edit_Save Statement
 Solomon API Function Calls 95

Edit_First Function
Executes the First toolbar button.
Syntax
RetVal = Edit_First (LevelNumber)
Remarks
This function corresponds to the First selection on the Solomon Edit menu and toolbar.
Use of this function allows you to execute Solomon’s First database navigation
function on the specified Level% from a VBA program.
The Edit_First function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use)
LevelNumber Integer Level number to perform operation

Example
Example navigates through detail lines of an existing journal entry. It goes to the first
line first, then goes to the next line until done.
Sub NavToEndOfList_Click()
Dim LvlStr$, Lvl%
serr1 = GetProp("cacct", PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)
serr1 = Edit_First(Lvl)
While serr1 <> NotFound
serr1 = Edit_Next(Lvl)
Wend
End Sub

See Also
Edit_Next Function, Edit_Last Function
96 Customization Manager Reference Visual Basic for Applications

Edit_Last Function
Executes the Last toolbar button.
Syntax
RetVal = Edit_Last (LevelNumber)
Remarks
This function corresponds to the Last selection on the Solomon Edit menu and toolbar.
Use of this function allows you to execute Solomon’s Last database navigation
function on the specified Level% from a VBA program.
The Edit_Last function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use)
LevelNumber Integer Level number to perform operation

Example
Example navigates through detail lines of an existing journal entry. It goes to the last
line first, then goes to the previous line until done.
Sub NavToTopOfList_Click()
Dim LvlStr$, Lvl%
serr1 = GetProp("cacct", PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)
serr = Edit_Last(Lvl)
While serr = 0
serr = Edit_Prev(Lvl)
Wend
End Sub

See Also
Edit_Next Function, Edit_First Function
 Solomon API Function Calls 97

Edit_New Function
Executes the New toolbar button.
Syntax
RetVal = Edit_New (LevelNumber)
Remarks
This function corresponds to the New selection on the Solomon Edit menu and toolbar.
Use of this function allows you to execute Solomon’s New function on the specified
Level% from a VBA program.
The Edit_New function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use)
LevelNumber Integer Level number to perform operation

Example
Example inserts a new document under program control:
Dim LvlStr$, Lvl%
serr1 = GetProp("crefnbr", PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)
serr1 = Edit_New(Lvl)

See Also
Edit_Save Statement, Edit_Delete Function
98 Customization Manager Reference Visual Basic for Applications

Edit_Next Function
Executes the Next toolbar button.
Syntax
RetVal = Edit_Next (LevelNumber)
Remarks
This function corresponds to the Next selection on the Solomon Edit menu and toolbar.
Use of this function allows you to execute Solomon’s Next database navigation
function on the specified Level% from a VBA program.
The Edit_Next function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use)
LevelNumber Integer Level number to perform operation

Example
Example navigates through detail lines of an existing journal entry. It goes to the first
line first, then goes to the next line until done.
Sub NavToEndOfList_Click()
Dim LvlStr$, Lvl%
serr1 = GetProp("cacct", PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)
serr1 = Edit_First(Lvl)
While serr1 <> NotFound
serr1 = Edit_Next(Lvl)
Wend
End Sub

Example inserts a new row into row 6 of an existing

GL Journal entry

Sub InsertAtRowSix_Click()
Dim Cntr As Integer
Dim Dval As Double
Dim Ivis As String
Dim Lvl As Integer

serr = GetProp("cacct", PROP_VISIBLE, Ivis)

serr = GetProp("cacct", PROP_LEVEL, Lvl)

Cntr = 1
serr = Edit_First(Lvl)
 Solomon API Function Calls 99

While serr = 0 And Cntr < 8

If cntr <> 6 Then
serr = Edit_Next(Lvl)
ElseIf Cntr = 6 Then
serr = Edit_New(Lvl)
If serr = 0 Then
serr = SetObjectValue("cacct","3080")
serr = SetObjectValue("csub","03000AA00001")
serr = ↵
SetObjectValue("ctrandate","09071994")
serr = SetObjectValue("ctrandesc",Ivis)
serr = SetObjectValue("cdramt", "100")
serr = SetObjectValue("ccramt",".00000000")
End If
End If
Cntr = Cntr + 1
Wend
End Sub

See Also
Edit_Prev Function, Edit_Last Function
100 Customization Manager Reference Visual Basic for Applications

Edit_Prev Function
Executes the Prev toolbar button.
Syntax
RetVal = Edit_Prev (LevelNumber)
Remarks
This function corresponds to the Previous selection on the Solomon Edit menu and
toolbar. Use of this function allows you to execute Solomon’s Previous database
navigation function on the specified Level% from a VBA program.
The Edit_Prev function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use)
LevelNumber Integer Level number to perform operation

Example
Example navigates through detail lines of an existing journal entry. It goes to the last
line first, then goes to previous line until done.

Sub NavToTopOfList_Click()
Dim LvlStr$, Lvl%
serr1 = GetProp("cacct", PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)
serr1 = Edit_Last(Lvl)
While serr1 = 0
serr1 = Edit_Prev(Lvl)
Wend
End Sub

See Also
Edit_Next Function, Edit_First Function
 Solomon API Function Calls 101

Edit_Save Statement
Executes the Save toolbar button.
Syntax
Call Edit_Save
Remarks
This function corresponds to the Save selection on the Solomon Edit menu and toolbar.
Use of this function allows you to execute Solomon’s Save database function from a
VBA program.
Example
Example performs the Solomon save function:
Dim TimeOfDay As Stime
Call GetSysTime(TimeOfDay)
serr1 = SetObjectValue("cuser1", TimeOfDay)
Call Edit_Save

See Also
Edit_New Function, Edit_Delete Function
102 Customization Manager Reference Visual Basic for Applications

FPAdd Function
Add two double-precision floating-point values together with a designated rounding
precision.
Syntax
Result = FPAdd(Dbl1, Dbl2, Precision)
Remarks
Error conditions occurring during the addition operation, such as an overflow error,
will be handled automatically by the system. These types of errors will cause the
appropriate error message to be either displayed on the screen or written to the process
status log depending on the context in which the error occurred. After an error
condition has been properly reported, the application will be terminated.
The FPAdd function uses the following arguments:

Argument Type Description

Result Double Return value
Dbl1 Double First double value
Dbl2 Double Second double value
Precision Integer Rounding precision

Note: The precision parameter can be an explicit precision value as well as one of the
following symbolic constants defined in the VBTools_VBA module:

• MONEY - Monetary value

• INV_UNIT_QTY – Inventory unit quantity
• UNITS – Work units such as hours worked in Payroll
• INV_UNIT_PRICE – Inventory unit price
• PERCENT – Percentage value
Example
'Add the current to future balance for a total balance

Dim CurrentBalance#
Dim FutureBalance#
Dim TotalBal#

CurrentBalance = GetObjectValue("ccurrbal")
FutureBalance = GetObjectValue("cfuturebal")
TotalBal = FPAdd(CurrentBalance, FutureBalance, MONEY)
Call MessBox(Str$(TotalBal), MB_OK, "Message")

See Also
FPDiv Function, FPMult Function, FPRnd Function, FPSub Function
 Solomon API Function Calls 103

FParm Function
Convert a double-precision floating-point value into an SQL parameter string.
Syntax
SQLParmStr = FParm(DblToConvert)
Remarks
The FParm function uses the following arguments:

Argument Type Description

SQLParmStr String DblToConvert converted into an SQL parameter string
DblToConvert Double Double-precision floating-point value to convert

Example
Dim MaxAmount#
Dim SqlStr$
Dim CountDoc As Long

'Obtain documents with balance over MaxAmount

MaxAmount = 1000
SqlStr = "Select Count(*) From ARDoc Where DocBal > "
SqlStr = SqlStr + FParm(MaxAmount)
Call Sql(c1, SqlStr)
serr1 = sgroupfetch1(c1, CountDoc, Len(CountDoc))

Call MessBox ("Documents over Max: " + Str$(CountDoc), MB_OK, "Message")

See Also
DParm Function, IParm Function, SParm Function
104 Customization Manager Reference Visual Basic for Applications

FPDiv Function
Divide one double-precision floating-point value by another with a designated
rounding precision.
Syntax
Result = FPDiv(Dbl1, Dbl2, Precision)
Remarks
This function will divide the value of Dbl1 by Dbl2 and return the result.
Error conditions occurring during the division operation, such as division by zero, will
be handled automatically by the system. These types of errors will cause the
appropriate error message to be either displayed on the screen or written to the process
status log depending on the context in which the error occurred. After an error
condition has been properly reported, the application will be terminated.
The FPDiv function uses the following arguments:

Argument Type Description

Result Double Return value
Dbl1 Double First double value
Dbl2 Double Second double value
Precision Integer Rounding precision

Note: The precision parameter can be an explicit precision value as well as one of the
following symbolic constants defined in the VBTools_VBA module:

• MONEY - Monetary value

• INV_UNIT_QTY – Inventory unit quantity
• UNITS – Work units such as hours worked in Payroll
• INV_UNIT_PRICE – Inventory unit price
• PERCENT – Percentage value
Example
Dim Var1#, Var2#, Result#

Var1 = 100
Var2 = 10
Result = FPDiv(Var1, Var2, MONEY)

'Result is 10
Call MessBox(Str$(Result), MB_OK, "Message")

See Also
FPAdd Function, FPMult Function, FPRnd Function, FPSub Function
 Solomon API Function Calls 105

FPMult Function
Multiply two double-precision floating-point values together to a designated rounding
precision.
Syntax
Result = FPMult(Dbl1, Dbl2, Precision)
Remarks
Error conditions occurring during the multiplication operation, such as an overflow
error, will be handled automatically by the system. These types of errors will cause the
appropriate error message to be either displayed on the screen or written to the process
status log depending on the context in which the error occurred. After an error
condition has been properly reported, the application will be terminated.
The FPMult function uses the following arguments:

Argument Type Description

Result Double Return value
Dbl1 Double First double value
Dbl2 Double Second double value
Precision Integer Rounding precision

Note: The precision parameter can be an explicit precision value as well as one of the
following symbolic constants defined in the VBTools_VBA module:

• MONEY - Monetary value

• INV_UNIT_QTY – Inventory unit quantity
• UNITS – Work units such as hours worked in Payroll
• INV_UNIT_PRICE – Inventory unit price
• PERCENT – Percentage value
Example
Dim Var1#, Var2#, Result#

Var1 = 100
Var2 = 10
Result = FPMult(Var1, Var2, MONEY)

'Result is 1000
Call MessBox(Str$(Result), MB_OK, "Message")

See Also
FPAdd Function, FPDiv Function, FPRnd Function, FPSub Function
106 Customization Manager Reference Visual Basic for Applications

FPRnd Function
Round a double-precision floating-point value to a designated rounding precision.
Syntax
Result = FPRnd(DblToRound, Precision)
Remarks
Error conditions occurring during the rounding operation, such as an overflow error,
are handled automatically by the system. These types of errors will cause the
appropriate error message to be either displayed on the screen or written to the process
status log depending on the context in which the error occurred. After an error
condition has been properly reported, the application will be terminated.
The FPRnd function uses the following arguments:

Argument Type Description

Result Double Return value
DblToRound Double Value to be rounded
Precision Integer Rounding precision

Note: The precision parameter can be an explicit precision value as well as one of the
following symbolic constants defined in the VBTools_VBA module:

• MONEY - Monetary value

• INV_UNIT_QTY – Inventory unit quantity
• UNITS – Work units such as hours worked in Payroll
• INV_UNIT_PRICE – Inventory unit price
• PERCENT – Percentage value
Example
Example issues an SQL statement to retrieve a Sum of total documents. Displays the
results in a message box and formats the number.
Dim SqlStr$
Dim Result#

SqlStr = "Select Sum(OrigDocAmt) From ARDoc"

Call Sql(C1, SqlStr)
serr1 = sgroupfetch1(C1, Result, Len(Result))

Call MessBox(Format$ (FPRnd(Result, MONEY) , "$###,###,###.00"), ↵

MB_OK, "Message")

See Also
FPAdd Function, FPDiv Function, FPMult Function, FPSub Function
 Solomon API Function Calls 107

FPSub Function
Subtract one double-precision floating-point value from another with a designated
rounding precision.
Syntax
Result = FPSub(Dbl1, Dbl2, Precision)
Remarks
This function will subtract the value of Dbl2 from Dbl1 and return the result.
Error conditions occurring during the subtraction operation, such as an overflow error,
will be handled automatically by the system. These types of errors will cause the
appropriate error message to be either displayed on the screen or written to the process
status log depending on the context in which the error occurred. After an error
condition has been properly reported, the application will be terminated.
The FPSub function uses the following arguments:

Argument Type Description

Result Double Return value
Dbl1 Double First double value
Dbl2 Double Second double value
Precision Integer Rounding precision

Note: The precision parameter can be an explicit precision value as well as one of the
following symbolic constants defined in the VBTools_VBA module:

• MONEY - Monetary value

• INV_UNIT_QTY – Inventory unit quantity
• UNITS – Work units such as hours worked in Payroll
• INV_UNIT_PRICE – Inventory unit price
• PERCENT – Percentage value
Example
Dim Var1#, Var2#, Result#

Var1 = 1000
Var2 = 300

Result = FPSub(Var1, Var2, MONEY)

'Result will be 700.00

Call MessBox(Format$(Result, "####.00"), MB_OK, "Message")

See Also
FPAdd Function, FPDiv Function, FPMult Function, FPRnd Function
108 Customization Manager Reference Visual Basic for Applications

GetBufferValue Statement
Obtains an underlying Solomon application’s data buffer field value.
Syntax
Call GetBufferValue(bTable.FieldName, Str)
Remarks
If a VBA application issues its own VBA_SetAddr calls it can then reference any of
these structures from within code. However, if the underlying Solomon application’s
structures need to be referenced and these fields are not represented as objects on the
form, this statement allows the VBA application to obtain these values. If the fields
were objects on the form, the VBA application can simply issue GetObjectValue
instead.
The GetBufferValue statement uses the following arguments:

Argument Type Description

bTable.FieldName String SQL Table.FieldName that you wish to retrieve
Str String String variable in which to store the contents of the
buffer’s field value

Example
' get account number from gltran record
Dim AccountValue As String * 10
Call GetBufferValue("bgltran.acct",AccountValue)

See Also
SetBufferValue Statement
 Solomon API Function Calls 109

GetDelGridHandle Function
Returns the resource handle of the memory array used to temporarily hold detail lines
deleted from the designated SAFGrid control.
Syntax
DelMemHandle = GetDelGridHandle( SpreadSheetObj)
Remarks
Each SAFGrid control is associated with two underlying memory arrays that the
system opens automatically during Form Load. The primary memory array holds the
records that are actually visible in the grid. The resource handle to this primary
memory array is actually returned by the GetGridHandle function. However another
array is also created to temporarily hold user-deleted records until a save operation is
performed and the deletions are actually committed to the database. The resource
handle to this memory array can be retrieved using the GetDelGridHandle function.
Once the resource handle for the deleted record memory array has been retrieved, the
application can use it to loop through user-deleted records using calls such as MFirst
and MNext.
The GetDelGridHandle function uses the following arguments:

Argument Type Description

DelMemHandle Integer Resource handle for the memory array holding records
deleted from the designated SpreadSheet
SpreadSheetObj String SpreadSheet object name

Example
serr1 = GetDelGridHandle("Spread1")

See Also
GetGridHandle Function
110 Customization Manager Reference Visual Basic for Applications

GetGridHandle Function
Obtains the grid handle for a Spreadsheet object.
Syntax
IntVar = GetGridHandle (SpreadControlName$)
Remarks
Returns the memory array handle for the specified spreadsheet object. Useful if the
application wants to use memory array functions to navigate through a spreadsheet
object. Should be used with extreme caution since the underlying application may
override memory array assumptions performed in the VBA program.
The GetGridHandle function uses the following arguments:

Argument Type Description

IntVar Integer Any integer variable (serr, serr1 – serr12 declared
in the VBTools_VBA module are reserved for this
use)
SpreadControlName String Object name of the spreadsheet object

Example
Dim MemHandle As Integer
MemHandle = GetGridHandle("Spread1")

See Also
MSet Statement
 Solomon API Function Calls 111

GetObjectValue Function
Obtains the value of a specified object on the form.
Syntax
RetVal = GetObjectValue(“ControlName”)
Remarks
Whenever a VBA application needs to obtain data values from any of the controls on
the form, this function is used.
The GetObjectValue function uses the following arguments:

Argument Type Description

RetVal User-Defined Any variable type. Must match database field type of the
ControlName.
ControlName String Name of the control whose field value you want to obtain.

Example
Dim TestDate1 As Sdate
TestDate1.Val = GetObjectValue("cinvcdate")

'Double field example

Dim CrTotal#
CrTotal = Val(GetObjectValue ("ccrtot"))

'Logical field example

'Note that an integer variable type is declared
Dim Var1%
Var1 = GetObjectValue("cmultichk")

If Var1 = 0 Then
Call MessBox("Value is UnChecked or False", MB_OK, "Message")
ElseIf Var1 = 1 Then
Call MessBox("Value is Checked or True", MB_OK, "Message")
End If

'Integer field example

Dim CycleCount%
CycleCount = GetObjectValue("ccycle")

'String field example

Dim DispCountry As String
DispCountry = GetObjectValue("ccountry")

See Also
SetObjectValue Function
112 Customization Manager Reference Visual Basic for Applications

GetProp Function
Obtains a property value for a specified object.
Syntax
RetVal = GetProp(ObjectName, PropName, PropValue)
Remarks
This function allows the VBA application to obtain a property value of any object on
the screen. In addition to the property value, the application can also obtain the level
associated with the particular object. This function is useful in the Edit_ functions as
well as the SetProp functions because you can check the value of the property before
setting it.
The GetProp function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 are reserved for
this use).
ObjectName String Object name.
PropName String Property name you want the value of. Note: Any native
property name that is available for the object may be
specified.
PropValue User Defined Variable to retrieve the property value into.
The following values for the PropertyName argument are defined as symbolic
constants in the VBTools_VBA module:

Symbolic Constant Valid Datatype Valid Data Values

PROP_BLANKERR Integer TRUE / FALSE
(required)
PROP_CAPTION String
PROP_CUSTLIST String
PROP_ENABLED Integer TRUE / FALSE
PROP_HEADING String
PROP_LEVEL String
PROP_MASK String
PROP_MIN String
PROP_MAX String
PROP_TABSTOP Integer TRUE / FALSE
PROP_VISIBLE Integer TRUE / FALSE
 Solomon API Function Calls 113

Example
Example navigates through batches in Journal Entry screen:
Sub NavThruBatches_Click()
Dim Lvl As Integer
Dim LvlStr As String * 1

' Since cbatnbrh is a key field, level will be

' returned as "0,k" not "0"
' So declare lvlstr as a one-character string, so
' we get back only "0", and then manually convert it
' for use in Edit calls
serr = GetProp("cbatnbrh",PROP_LEVEL, LvlStr)
Lvl = Val(LvlStr)

'Perform navigation to first batch

serr = Edit_First(Lvl)
While serr <> NotFound
DoEvents
serr = Edit_Next(Lvl)
Wend
End Sub

See Also
SetProp Statement, Edit_Next Function
114 Customization Manager Reference Visual Basic for Applications

GetSqlType Function
Determine which type of database server is being utilized.
Syntax
SqlType = GetSqlType()
Remarks
™
Solomon currently supports one type of SQL database: Microsoft® SQL Server . This
is an old API that used to support multiple database types. For backward compatibility
it has been preserved.
The GetSqlType function returns one of the following integer global constants
declared in the VBTools_VBA module:

Return Value Description

MSSqlType Microsoft SQL Server database is being utilized

Example
Dim SqlDatabaseBeingUtilized As Integer

SqlDatabaseBeingUtilized = GetSqlType()
 Solomon API Function Calls 115

GetSysDate Statement
Retrieve the current system date.
Syntax
Call GetSysDate(Date)
Remarks
The GetSysDate statement uses the following arguments:

Argument Type Description

Date SDate user-defined Date variable to be initialized to the current
datatype (declared in the system date
VBTools_VBA module)

Example
This sample routine sets an existing date field to the system date.
Sub setdate_Click()
Dim NewDate as Sdate
Dim NewStrDate$

Call GetSysDate(NewDate)
NewStrDate = DateToStr(NewDate)

serr1 = SetObjectValue("cpaydate", NewStrDate)

Call DispFields("Form1","cpaydate")
End Sub

See Also
GetSysTime Statement
116 Customization Manager Reference Visual Basic for Applications

GetSysTime Statement
Retrieve the current system time.
Syntax
Call GetSysTime(Time)
Remarks
The GetSysTime statement uses the following arguments:

Argument Type Description

Time STime user-defined Time variable to be initialized to the current
datatype (declared in the system time
VBTools_VBA module)

Example
'Obtain current system time
Dim SystemTime As Stime
Call GetSysTime(SystemTime)
Call MsgBox("Current Time is: " + TimeToStr(SystemTime), ↵
MB_OK, "Message")

See Also
GetSysDate Statement
 Solomon API Function Calls 117

HideForm Statement
Hide a designated subform previously displayed via a call to DispForm.
Syntax
Call HideForm(SubFormName)
Remarks
This function is typically used in the click event of the OK or Cancel button of the
designated subform.
The HideForm statement uses the following arguments:

Argument Type Description

SubFormName String Form to be hidden

Example
Sub OkButton_Click()
Call HideForm("NewForm")
End Sub

See Also
DispForm Statement
118 Customization Manager Reference Visual Basic for Applications

IncrStrg Statement
Increment a string representation of a whole number value.
Syntax
Call IncrStrg(StringNbr, Length, Increment)
Remarks
The IncrStrg statement uses the following arguments:

Argument Type Description

StringNbr String String whose current whole number is to be incremented.
Length Integer Size of StringNbr. It is not required that this value equal
the full size of StringNbr. For example if the string can
actually hold 10 bytes but currently the developer only
desires to use 6 byte values then a value of 6 can be passed.
Increment Integer Amount by which StringNbr is to be incremented.

Example
Dim BatNbrLength As Integer

BatNbrLength = LenB(Trim$(bGLSetup.LastBatNbr))

'Increment last batch number to the next sequential value (within the
'size of batch numbers actually being used - i.e., BatNbrLength).
Call IncrStrg(bGLSetup.LastBatNbr, BatNbrLength, 1)
 Solomon API Function Calls 119

IntlStrToDate Statement
Convert a date string from the Windows short date style into an SQL database date
format.
Syntax
Call IntlStrToDate(DateStrToConvert, SQLDate)
Remarks
IntlStrToDate can be used to convert a string formatted according to the Windows
short date style into a format suitable for storage in a date field within the SQL
database.
The IntlStrToDate statement uses the following arguments:

Argument Type Description

DateStrToConvert String Date string to be converted. This string
must be in the Windows short date format.
SQLDate SDate user-defined Converted date value.
datatype (declared in
Applic.DH)

See Also
DateToIntlStr Function, DateToStr Function, DateToStrSep Function, StrToDate
Statement
120 Customization Manager Reference Visual Basic for Applications

IParm Function
Convert an integer into an SQL parameter string.
Syntax
SQLParmStr = IParm(IntToConvert)
Remarks
The IParm function uses the following arguments:

Argument Type Description

SQLParmStr String IntToConvert converted into an SQL parameter string.
IntToConvert Integer Integer value to convert. Note: INTMIN and INTMAX are
global constants available that may optionally be used.
These represent –32768 and 32767 respectively, which are
the minimum and maximum small integer range values.

Example
These examples assume the following SQL statement was used to create a stored
procedure called GLTran_Module_BatNbr_LineNbr
Select * from GLTran
where Module = @parm1
and BatNbr = @parm2
and LineNbr between @parm3beg and @parm3end
order by Module, BatNbr, LineNbr;
This code snippet illustrates how the previously defined stored procedure can be used
to fetch a single transaction having a LineNbr of 84 in GL Batch #000123.
SqlStr = " GLTran_Module_BatNbr_LineNbr" + SParm("GL") + ↵
SParm("000123") + IParm(84) + IParm(84)
GLTran_Fetch = SqlFetch1(CSR_GLTran, SqlStr, bGLTran, LenB(bGLTran))
This code snippet illustrates the previously defined stored procedure can be used to
fetch all transactions in GL Batch #000123.
SqlStr = " GLTran_Module_BatNbr_LineNbr" + SParm("GL") + ↵
SParm("000123") + IParm(INTMIN) + IParm(INTMAX)
GLTran_Fetch = SqlFetch1(CSR_GLTran, SqlStr, bGLTran, LenB(bGLTran))

While ( GLTran_Fetch = 0)
GLTran_Fetch = SFetch1( CSR_GLTran, bGLTran, LenB(bGLTran))
Wend

See Also
DParm Function, FParm Function, SParm Function
 Solomon API Function Calls 121

Is_TI Function
Returns whether or not the Solomon application is in Transaction Import mode.
Syntax
IntVar = Is_TI()
Remarks
This function is useful when you want to suppress user-responses and/or dialogs when
the application is running in Transaction Import mode.
The Is_TI function returns the following:
True — Application is running in Transaction Import mode.
False — Application is not running in Transaction Import mode.
Example
Following example determines whether the application is in Transaction Import mode:
If Is_TI = False Then
'Perform logic or routine only desired in standard mode. ↵
(not Transaction Import mode)
End If

See Also
AliasConstant Statement
122 Customization Manager Reference Visual Basic for Applications

Launch Function
Launches another executable program.
Syntax
RetVal = Launch (CommandLine, SAFApp, WaitFlag, WindowFlag)
Remarks
Allows you to launch any Solomon window (or any other Windows application) from
any other Solomon window. You can also pass parameters to the Solomon windows
and use the ApplGetParms function in the Launched application to retrieve the
parameters.
The Launch function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 declared in the
VBTools_VBA module are reserved for this use).
CommandLine String The command line required to execute the application
(parameters included separated by PRMSEP constant
declared in the VBTools_VBA module).
SAFApp Integer Whether or not the application is a Solomon application
(True or False).
WaitFlag Integer Whether or not the launched application is modal. When the
launched application is modal, no other form is able to be
clicked until the application is closed. When this parm is
True and the application being launched is another
application, then the launched application shares the same
SQL session with the application that launched it. Therefore,
an extra session is not used. This exhibits the same behavior
as Solomon’s Quick Maintenance.
WindowFlag Integer State of the launched application. The VBTools_VBA
module has two constants declared for this purpose:
LaunchMaximize or LaunchMinimize. Zero launches the
application in its normal state.
 Solomon API Function Calls 123

To launch a Solomon report, you must launch the ROI application with the appropriate
parameters. The following are the available parameters (and their descriptions) which
you can pass to ROI:

Parameter Description
/RUN Follows the report number you wish to execute.
/WHERE Follows the SQL where clause restrictions.
/DEBUG Creates a text file called RSWRUN.? in the Solomon Program
directory. This TXT file contains all of the parameters passed to the
report. (Only useful for debugging purposes)
/FORMAT Follows the format name or number of the particular report.
/PSCRN Prints the report to screen if specified. (Default is current printer).
/TEMPLATE Follows the Report Template name that you wish to load for the
report.

Example
Following code for 03.270.00 (the launched application):
Sub Form1_Load
' Variable to store the passed Parameter to this screen
Dim VendorParm$

VendorParm = ApplGetParms()

If Trim$(VendorParm) <> "" Then

' Screen was called from another application.
' Set the value of the ID field to what was
' passed in by Launch() function
serr1 = SetObjectValue("cvendid", VendorParm)
End If
End Sub

See Also
ApplGetParms Function, ApplGetParmValue Function, ApplSetParmValue Statement
124 Customization Manager Reference Visual Basic for Applications

The following code is for the Accounts Payable module’s Voucher and Adjustment
Entry (03.010.00) window (the launching application). Even though this example uses
a push button, it could be placed in the Chk event of a particular control. The syntax
would be very similar except that chkstrg is evaluated and passed to the Launch( )
function:
Sub VendorScrn_Click()
' Obtain the Current ID in this screen and pass
' as a parameter to other EXE

Dim CmdLine$ 'Stores the command line string for Launch()

Dim VendParm$ 'Stores the current ID from screen

VendParm = GetObjectValue("cvendid")

If Trim$(VendParm) <> "" Then

' Note that VendParm is passed twice with a PRMSEP between
' Also note the space following 0327000. This is also
' required.
CmdLine = "0327000 " + VendParm + PRMSEP + VendParm

' The third parm indicates Wait = True. This will allow
' the Launched application to share the same SQL session,
' therefore, an extra session is not used. This exhibits the
' same behavior from a shared session perspective as Quick
' Maintenance.
serr1 = Launch(CmdLine, True, True, 0)
End If
End Sub

Launching ROI
The following example will print the Vendor Trial Balance (03.650.00) for the current
vendor in the Vendor Maintenance (03.270.00) window. This code is placed in the
click event of a push button. Note that you must have one space following ROI.EXE in
the first parameter:
Dim VendorId$, ParmStr$

VendorId = GetObjectValue("cvendid")
ParmStr = "ROI.EXE " + PRMSEP + "03650/RUN" + PRMSEP + "03650C/FORMAT"
+ PRMSEP + "Vendor.VendId =" + sparm(VendorID) + "/WHERE"
+ PRMSEP + "/PSCRN"
serr1 = Launch(ParmStr, True, True, 0)
 Solomon API Function Calls 125

MCallChks Function
Perform error checking on a specific grid object’s column.
Syntax
IntVar = (gridhandle%, ctlbeg$, ctrlend$)
Remarks
This function is useful when you want to manually execute error checking on a grid
object column because another object’s value has been changed. This allows you to
“trigger” the Chk event under program control.
The MCallChks function uses the following arguments:

Argument Type Description

IntVar Integer Any integer variable (serr, serr1 – serr12 declared in the
VBTools_VBA module are reserved for this use).
gridhandle Integer Grid object handle.
ctlbeg String Beginning control object name to execute Chk event.
ctlend String Ending control object name to execute Chk event.

See Also
CallChks Function, GetGridHandle Function
126 Customization Manager Reference Visual Basic for Applications

MClear Statement
Delete all records from the designated memory array.
Syntax
Call MClear(MemHandle)
Remarks
The MClear statement can be used to clear an existing memory array of its contents.
The array will stay allocated and can be subsequently re-used.
The MClear statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle.

See Also
VBA_MOpen Functions
 Solomon API Function Calls 127

MClose Statement
Close an existing memory array.
Syntax
Call MClose(MemHandle)
Remarks
MClose can be used to close a memory array previously opened using one of the
VBA_MOpen functions.
The MClose statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle.

Example
Illustrates how to close a memory array no longer needed by the application.
Dim Mem_Account As Integer
Dim CSR_Account As Integer
Dim SqlStr As String
Dim Account_Fetch As Integer
'Open memory array to hold Chart of Accounts
Mem_Account = VBA_MOpen( TRUE, bAccount, Len(bAccount), "", 0, "", 0, ↵
¿ "", 0)
'Allocate cursor
Call SqlCursor( CSR_Account, NOLEVEL)
'Initialize cursor with a SQL statement and immediately fetch ↵
first record
SqlStr = "Select * from Account order by Acct"
Account_Fetch = SqlFetch1(CSR_Account, SqlStr, bAccount, ↵
Len(bAccount))
'Read through all subsequent Account records, inserting each one into the
'memory array.
While( Account_Fetch = 0)
'Insert current Account record into the memory array
Call MInsert( Mem_Account)
'Fetch the next Account record
Account_Fetch = SFetch1(CSR_Account, bAccount, ↵
Len(bAccount))
Wend
'Close the memory array
Call MClose( Mem_Account)

See Also
VBA_MOpen Functions
128 Customization Manager Reference Visual Basic for Applications

MDelete Function
Delete the current record from the designated memory array.
Syntax
RecFetch = MDelete(MemHandle, RecMaintFlg)
Remarks
The current record in a memory array can be deleted by using the MDelete function.
After the record is deleted, the system will automatically navigate to the next memory
array record since there must always be a current record in memory arrays, assuming
of course that one or more records exist. Consequently, the return value and
corresponding record status apply to the next record after the deleted record.
When this call is used on a memory array associated with an SAFGrid control, an
MDisplay call will be necessitated to properly synchronize the SAFGrid appearance
with the memory array.
The MDelete function uses the following arguments:

Argument Type Description

RecFetch Integer 0 if the next record is successfully fetched. NOTFOUND is
returned if no subsequent records exist in the specified
memory array (i.e., when the last record itself is deleted).
This does not mean that no additional records exist in the
memory array. Rather it simply means that no records exist
after the record just deleted.
MemHandle Integer Memory array resource handle.
RecMaintFlg Integer Status of the memory array record (assuming it was
successfully fetched). the VBTools_VBA module contains
the following symbolic constants defining possible
memory array record status values: INSERTED,
UPDATED and NOTCHANGED

See Also
MDisplay Statement, MInsert Statement, MUpdate Statement
 Solomon API Function Calls 129

MDisplay Statement
Display the current contents of the designated memory array in its corresponding
SAFGrid control.
Syntax
Call MDisplay(MemHandle)
Remarks
Each SAFGrid control is associated with an underlying memory array that is opened
automatically. Any time data within this memory array is modified directly by the
application, as opposed to by the user, the SAFGrid control must be subsequently
redisplayed.
When MDisplay is called, the current memory array record will be displayed at the top
of the SAFGrid control. Thus, for example, if the application wants the first memory
array record to display at the top of the SAFGrid control it should initially call MFirst
to move to the first record and then call MDisplay.
The MDisplay statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle. This memory array must be
associated with an SAFGrid control.
130 Customization Manager Reference Visual Basic for Applications

Example
Sub cBegProcessing_Click ()
Dim RecFound As Integer
Dim MemMaintFlg As Integer
Dim Nbr_Of_Batches_Processed As Integer

'Explicitly initialize processing counter to zero BEFORE calling

'ProcValidBatch() for the FIRST time.
Nbr_Of_Batches_Processed = 0

RecFound = MFirst(MemHandle, MemMaintFlg)

While (RecFound = 0)

If (bCurrBatchSelected = True) Then

'Process the selected batch
Call
ProcValidBatch(Nbr_Of_Batches_Processed)

'Delete current and get next memory array batch ↵

record
RecFound = MDelete(MemHandle, MemMaintFlg)

Else
'Current batch is not selected so get the next ↵
batch from the
'memory array.
RecFound = MNext(MemHandle, MemMaintFlg)

End If

Wend

'Redisplay the grid with the modified contents of the memory array.
RecFound = MFirst(MemHandle, MemMaintFlg)
Call MDisplay(MemHandle)

End Sub
 Solomon API Function Calls 131

Mess Statement
Displays a message from the Solomon message file and waits for the user to choose a
button.
Syntax
Call Mess(MsgNumber)
Remarks
When Solomon is installed, an ASCII text file called Messages.csv is copied to the
Solomon Program directory. This file contains all messages relating to the Solomon
product — including all independently developed applications created with Solomon
Tools for Visual Basic. Each message has, among other things, a message number. A
particular message can be displayed to the screen by merely passing its associated
message number to the Mess statement.
The Messf statement should be used if the actual text of the message contains
replaceable parameters.
The MessResponse function can be used to determine which button was chosen by the
user to close the message box.
The standard VB MsgBox statement should not be used in applications developed with
Solomon Tools for Visual Basic in order to avoid conflicts with other Solomon
Utilities such as Cut/Copy/Paste and Transaction Import. These utilities have built-in
sophistication to respond to messages from the underlying application during the
particular operation being performed such as paste or import. However, this automated
functionality does not apply to messages displayed using the standard VB MsgBox
statement. The MessBox statement has been provided to facilitate similar functionality
to the standard VB MsgBox statement with the exception that MessBox does not
conflict with other Solomon Utilities.
The Mess statement uses the following arguments:

Argument Type Description

MsgNumber Integer Number of the message from the Solomon message file
that is to be displayed.
132 Customization Manager Reference Visual Basic for Applications

Each record (i.e., message) contained within the Messages.csv file contains the
following fields separated by a comma:

Field Name Comments

Message Number Message number which is required by most of the message
API’s such as Mess.
Category 0 for all Solomon messages. All independently developed
applications must also use 0.
Language 0 for English.
Type For future use. Currently set the field to 0.
Box Type See detailed explanation of Box Type values below.
Record Type S for messages created and maintained by Microsoft Business
Solutions. Independent developers should not use S for their
new messages since they could be deleted or modified by
Microsoft Business Solutions.
Unattended Default Button This value is used by Transaction Import to respond to
messages displayed by the underlying application during the
import operation.
Message Text Actual text of the message. Replaceable parameters appear as
“%s.” For example: My first name is %s and my last name is
%s.
The Box Type field within the Messages.csv file can have the following values:

Box Type Value Icon Buttons Default Button

0 None OK OK
16 Stop OK OK
48 Exclamation OK OK
64 Information OK OK
36 Question Yes / No Yes
292 Question Yes / No No
33 Question OK / Cancel OK
 Solomon API Function Calls 133

Example
The Payroll module’s Employee Maintenance (02.250.00) window allows the user to
enter the number of personal exemptions claimed by any particular employee on the
Miscellaneous Information subscreen. Any time this value is changed the user is
prompted, via a message, as to whether or not the new total number of personal
exemptions is to be utilized by each individual deduction for calculation purposes.
Message number 739 is the actual message displayed and its associated text in the
Solomon message file reads as follows:
“Do you want to update the employee’s deductions with the new exemption value?”
This particular message also displays two buttons in the message box – a Yes button
and a No button. The MessResponse function is subsequently called to determine
which of these two buttons the user actually selected to close the message box.
Sub cDfltPersExmpt_Chk (chkstrg As String, retval As Integer)
Dim MemArray_NbrRecs As Integer

MemArray_NbrRecs = MRowCnt(MemArray_EmpDeduction)

'If the memory array has any records in it then prompt the user
'whether or not he/she wants to update the number of PERSONAL
'EXEMPTIONS on ALL existing employee deductions.

If (MemArray_NbrRecs > 0) Then

Call Mess( 739)

If (MessResponse() = IDYES) Then

Call MSet(F0225004.cNbrPersExmpt, chkstrg)
Call MDisplay(MemArray_EmpDeduction)
End If

End If

End Sub
Example calls an existing message in the Messages table.
The message type is an OK Button.

' Warning - Qty in warehouse location will go negative

Call mess(578)

See Also
MessBox Statement, Messf Statement, MessResponse Function
134 Customization Manager Reference Visual Basic for Applications

MessBox Statement
Displays a message and waits for the user to choose a button.
Syntax
Call MessBox(Msg, Type, Title)
Remarks
The standard VB MsgBox statement should not be used in applications developed with
Solomon Tools for Visual Basic in order to avoid conflicts with other Solomon
Utilities such as Cut/Copy/Paste and Transaction Import. These utilities have built-in
sophistication to respond to messages from the underlying application during the
particular operation being performed such as paste or import. However, this automated
functionality does not apply to messages displayed using the standard VB MsgBox
statement. The MessBox statement has been provided to facilitate similar functionality
to the standard VB MsgBox statement with the exception that MessBox does not
conflict with other Solomon Utilities.
The MessResponse function can be used to determine which button was chosen by the
user to close the message box.
The MessBox statement uses the following arguments:

Argument Type Description

Msg String Message text to be displayed
Type Integer Numeric value controlling the icon style, buttons to be
displayed as well as which button is the default button
Title String Text to display in the title bar of the message dialog box

Example
Dim FactAmt#
FactAmt = GetObjectValue("cannmemo2")

If FactAmt <> 0 Then

Call MessBox("Display Excel During Execution?", MB_YESNO, ↵
" Message")
End If

See Also
Mess Statement, Messf Statement, MessResponse Function
 Solomon API Function Calls 135

Messf Statement
Formats a message from the Solomon message file with replaceable parameters and
then displays it and waits for the user to choose a button.
Syntax
Call Messf(MsgNumber, Parm1Str, Parm2Str, Parm3Str, Parm4Str, Parm5Str,
Parm6Str)
Remarks
When Solomon is installed, an ASCII text file called Messages.csv is copied to the
Solomon program directory. This file contains all messages relating to the Solomon
product – including all independently developed applications created with Solomon
Tools for Visual Basic. Each message has, among other things, a message number. The
message can also contain up to six replaceable parameters by placing a %s at the
appropriate point(s) within the actual message text. A particular message can be
subsequently displayed to the screen by merely passing its associated message number
to the Messf statement along with data values for each replaceable parameter.
The Mess statement should be used if the actual text of the message does not contain
replaceable parameters.
The MessResponse function can be used to determine which button was chosen by the
user to close the message box.
The standard VB MsgBox statement should not be used in applications developed with
Solomon Tools for Visual Basic in order to avoid conflicts with other Solomon
Utilities such as Cut/Copy/Paste and Transaction Import. These utilities have built-in
sophistication to respond to messages from the underlying application during the
particular operation being performed such as paste or import. However, this automated
functionality does not apply to messages displayed using the standard VB MsgBox
statement. The MessBox statement has been provided to facilitate similar functionality
to the standard VB MsgBox statement with the exception that MessBox does not
conflict with other Solomon Utilities.
136 Customization Manager Reference Visual Basic for Applications

The Messf statement uses the following arguments:

Argument Type Description

MsgNumber Integer Number of the message from the Solomon message file that
is to be displayed.
Parm1Str String Data value for the first replaceable parameter.
Parm2Str String Data value for the second replaceable parameter. Blank if
the message text contains only one replaceable parameter.
Parm3Str String Data value for the third replaceable parameter. Blank if the
message text contains less than three replaceable parameters.
Parm4Str String Data value for the fourth replaceable parameter. Blank if the
message text contains less than four replaceable parameters.
Parm5Str String Data value for the fifth replaceable parameter. Blank if the
message text contains less than five replaceable parameters.
Parm6Str String Data value for the sixth replaceable parameter. Blank if the
message text contains less than six replaceable parameters.
Each record (i.e., message) contained within the Messages.csv file contains the
following fields separated by a comma:

Field Name Comments

Message Number Message number which is required by most of the message
API’s such as Messf.
Category 0 for all Solomon messages. All independently developed
applications must also use 0.
Language 0 for English.
Type For future use. Currently set the field to 0.
Box Type See detailed explanation of Box Type values below.
Record Type S for messages created and maintained by Microsoft Business
Solutions. Independent developers should not use S for their
new messages since they could be deleted or modified by
Microsoft Business Solutions.
Unattended Default Button This value is used by Transaction Import to respond to messages
displayed by the underlying application during the import
operation.
Message Text Actual text of the message. Replaceable parameters appear as
“%s.” For example: My first name is %s and my last name is
%s.
 Solomon API Function Calls 137

The Box Type field within the MESSAGES.CSV file can have the following values:

Box Type Value Icon Buttons Default Button

0 None OK OK
16 Stop OK OK
48 Exclamation OK OK
64 Information OK OK
36 Question Yes / No Yes
292 Question Yes / No No
33 Question OK / Cancel OK

Example
The Payroll module’s Manual Check Entry (02.040.00) window uses the following
code to warn the user of the fact that a Batch is out of balance.
Message number 818 is the actual message displayed and its associated text in the
Solomon message file reads as follows:
“Batch is out of balance by %s. Do you want to edit?”
This particular message also displays two buttons in the message box – a Yes button
and a No button. The MessResponse function is subsequently called to determine
which of these two buttons the user actually selected to close the message box.
'Make sure that the batch itself is in balance with the documents.
Batch_Out_Of_Bal_Amt = FPSub(bBatch.CtrlTot, bBatch.DrTot, MONEY)

If (Batch_Out_Of_Bal_Amt <> 0#) Then

Call Messf( 818, Str$(Batch_Out_Of_Bal_Amt), "", "", "", ↵

"", "")

If (MessResponse() = IDYES) Then

'User decided to edit the batch - so abort the
Finish
retval = ErrNoMess
'Set focus on the Batch Control Total field
Call ApplSetFocus(cCtrlTot)
End If

End If

See Also
Mess Statement, MessBox Statement, MessResponse Function
138 Customization Manager Reference Visual Basic for Applications

MessResponse Function
Returns the button chosen by the user to close the last message box displayed using the
Mess, Messf or MessBox statements.
Syntax
ButtonId = MessResponse()
Remarks
The MessResponse function returns one of the following symbolic constants declared
in the VBTools_VBA module:

Return Value Description

IDOK OK button selected
IDYES Yes button selected
IDNO No button selected
IDCANCEL Cancel button selected
IDABORT Abort button selected
IDRETRY Retry button selected
IDIGNORE Ignore button selected

Example
Dim Response%
Dim WSheet As Object

Call MessBox("Display Excel During Execution?", MB_YESNO, " Message")

Response = MessResponse()

DoEvents

'Start Microsoft Excel and create the object.

Set WSheet = CreateObject("Excel.Sheet")
'Make Excel Visible for Demo purposes

If Response = IDYES Then

WSheet.Application.Visible = True
End If

See Also
Mess Statement, Messf Statement
 Solomon API Function Calls 139

mFindControlName Function
Returns a list of control names present in the current application.
Syntax
ControlName = mFindControlName(FirstFlag)
Remarks
The mFindControlName function is used to return the first and subsequent control
names in tab index order. This function is useful in cases where you wish to write code
that is “generic” but needs to rely on specific control names. By writing generic versus
screen specific code, you can re-use it more often. This function would most often be
used in cases where you wish to programmatically cycle through all controls within a
screen and set specific properties based on certain characteristics (such as background
color or tool tip text).

Note: On controls that are added by Customization Manager, the Tab Index property is
set to 900. This value may optionally be changed and would be desirable to assure
expected tab order results. If, however, there are inserted controls that have identical
tab index orders, mFindControlName finds these controls in the order that they were
created.

The mFindControlName function uses the following arguments:

Argument Type Description

ControlName String The name property of the control
FirstFlag Integer 1 = Indicates finding the first control (i.e., the control
whose Tab Index property is zero)
0 = Indicates finding the next control in Tab Index order

Example
This example cycles through all controls to determine which ones have a PV property.
If a control has a PV property, its ToolTipText property is set to indicate that F3
lookup is available:
Dim CtlName As String, SResult As String
' Find the first control on the screen
CtlName = mFindControlName(1)
While (Trim$(CtlName) <> "")
' Get the PV property to determine F3 (inquiry)
serr1 = GetProp(CtlName, "PV", SResult)
If serr1 = 0 And Trim(SResult) <> "" Then
' A PV property exists
serr1 = GetProp(CtlName, "ToolTipText", SResult)
If serr1 = 0 And Trim(SResult) = "" Then
' Set the tooltiptext property if it is not in use
140 Customization Manager Reference Visual Basic for Applications

SResult = "Press F3 for list of Possible Values."

Call SetProp(CtlName, "ToolTipText", SResult)
End If
End If
' Find the next control
CtlName = mFindControlName(0)
Wend
This example cycles through all controls to determine which ones have a blankerr
property of True. These would be required fields. If a control has a blankerr property of
True, its background color is set to blue to provide a visual indication that it is
required:
Dim CtlName As String, SResult As String
' Find the first control on the screen
CtlName = mFindControlName(1)
While (Trim$(CtlName) <> "")
' Get the 'blankerr' property to determine required controls.
serr1 = GetProp(CtlName, "Blankerr", iresult)
If serr1 = 0 And iresult = True Then
' Blankerr property found and control is required.
serr1 = GetProp(CtlName, "BackColor", SResult)
If serr1 = 0 Then
lresult = &HFFFF80
Call SetProp(CtlName, "BackColor", SResult)
End If
End If
CtlName = mFindControlName(0) ' Find the next control
Wend
 Solomon API Function Calls 141

MFirst Function
Move to the first record in a designated memory array.
Syntax
RecFetch = MFirst(MemHandle, RecMaintFlg)
Remarks
MFirst moves to the first record of a specified memory array and copies the contents
of the array record into the data structure(s) previously specified in the VBA_MOpen
function call used to originally open the relevant memory array.
When this call is used on a memory array associated with an SAFGrid control (i.e.,
memory arrays opened automatically), an MDisplay call will be necessitated to
properly synchronize the SAFGrid appearance with the memory array.
The MFirst function uses the following arguments:

Argument Type Description

RecFetch Integer 0 if a record is successfully fetched. NOTFOUND is
returned if no records exist in the specified memory array.
MemHandle Integer Memory array resource handle.
RecMaintFlg Integer Status of the memory array record (assuming it was
successfully fetched). the VBTools_VBA module contains
the following symbolic constants defining possible
memory array record status values: INSERTED,
UPDATED and NOTCHANGED

See Also
MLast Function, MNext Function, MPrev Function
142 Customization Manager Reference Visual Basic for Applications

MGetLineStatus Function
Returns the line status of the current record in the designated memory array.
Syntax
RecMaintFlg = MGetLineStatus(MemHandle)
Remarks
The MGetLineStatus function allows the application to retrieve the status of the
current memory array record at any time.
The MGetLineStatus function uses the following arguments:

Argument Type Description

RecMaintFlg Integer Status of the current memory array record. the
VBTools_VBA module contains the following symbolic
constants defining possible memory array record status
values: INSERTED, UPDATED and NOTCHANGED
MemHandle Integer Memory array resource handle.

See Also
MSetLineStatus Function
 Solomon API Function Calls 143

MGetRowNum Function
Returns the row/record number of the current record in the designated memory array.
Syntax
CurrRecNbr = MGetRowNum(MemHandle)
Remarks
The MGetRowNum function uses the following arguments:

Argument Type Description

CurrRecNbr Integer Ro /record number of the current record
MemHandle Integer Memory array resource handle

See Also
MRowCnt Function, MSetRowNum Statement
144 Customization Manager Reference Visual Basic for Applications

MInsert Statement
Insert a new record into a designated memory array.
Syntax
Call Minsert(MemHandle)
Remarks
MInsert is used to add a new record to a memory array. This is accomplished by
copying the contents of all data structures previously associated with the designated
memory array into a new memory array record. Data structures are associated with a
memory array in the VBA_MOpen function call used to originally open the relevant
memory array. The new memory array record will have a line status of INSERTED.
When this call is used on a memory array associated with an SAFGrid control (i.e.,
memory arrays opened automatically), an MDisplay call will be necessitated to
properly synchronize the SAFGrid appearance with the memory array.
The MInsert statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle
 Solomon API Function Calls 145

Example
This example illustrates how records can be inserted into a memory array under
program control.
Dim Mem_Account As Integer
Dim CSR_Account As Integer
Dim SqlStr As String
Dim Account_Fetch As Integer

'Open memory array to hold Chart of Accounts

Mem_Account = VBA_MOpen( TRUE, bAccount, Len(bAccount), "", 0, ↵
"", 0,"", 0)

'Allocate cursor
Call SqlCursor( CSR_Account, NOLEVEL)

'Initialize cursor with a SQL statement and immediately fetch ↵

first record
SqlStr = "Select * from Account order by Acct"
Account_Fetch = SqlFetch1(CSR_Account, SqlStr, bAccount, ↵
Len(bAccount))

'Read through all subsequent Account records, inserting each one into
'the memory array.
While( Account_Fetch = 0)

'Insert current Account record into the memory array

Call MInsert( Mem_Account)

'Fetch the next Account record

Account_Fetch = SFetch1(CSR_Account, bAccount,
Len(bAccount))

Wend

See Also
MDelete Function, MSetLineStatus Function, MUpdate Statement, VBA_MOpen
Functions
146 Customization Manager Reference Visual Basic for Applications

MKey Statement
Define a key field for a previously opened memory array.
Syntax
Call MKey(MemHandle, KeySegmentNbr, TableDotFieldName, Ascending)
Remarks
Occasionally a program will need the ability to easily locate a particular record within
a memory array based on one or more key field values. The MKeyFind function can
be used to accomplish this goal assuming the sort order for the memory array has been
previously defined. Memory arrays associated with an SAFGrid control automatically
have their sort order initialized based on the key field control(s) contained within the
grid (i.e., notated by a “,k” in the levels property of the controls). All other memory
arrays must have their sort order explicitly defined via one of several different
methods. Each of the methods to define a key field, such as MKey, MKeyFld,
MKeyOffset, and MSetRowNum, vary primarily in the way they acquire detailed
information on a key field such as datatype, size and byte offset within a user-defined
datatype.
The MKey statement is the simplest and most common of all these methods to define a
memory array key field. MKey is so simple because the system will automatically
determine the requisite key field information for the TableDotFieldName based both
on the VBA_SetAddr call for the relevant table and its corresponding data dictionary
information in the database. The two restrictions of the MKey method are that it can
only be used for fields whose table exists in the database (i.e., as opposed to a memory
variable existing only within VB code) and a VBA_SetAddr call must have already
been issued for the relevant table.
Multi-segment keys can be defined by successive calls to MKey with different
KeySegmentNbr argument values.
The MKey statement uses the following arguments:

Argument Type Description

MemHandle Integer Unique handle to a previously opened memory array.
KeySegmentNbr Integer Memory array key segment whose key field is being
defined. The first key segment number is always
zero. Multi-segment keys must have contiguous key
segment values such as 0 and 1 as opposed to 0 and
3. The maximum allowable number of key segments
is five.
TableDotFieldName String Name of the designated key field in a
Table.FieldName format such as “Account.Acct.”
Ascending Integer True if the key segment should be sorted ascending.
False to implement a descending sort sequence for
the key segment currently being defined.
 Solomon API Function Calls 147

Example
This example illustrates how to open a memory array and define multiple key fields.
Dim Mem_ValEarnDed As Integer

Call VBA_SetAddr(NOLEVEL, "bValEarnDed", bValEarnDed, ↵

nValEarnDed, Len(bValEarnDed))

Mem_ValEarnDed = VBA_MOpen(True, bValEarnDed, Len(bValEarnDed), "", 0,

"", 0, ¿
"", 0)

'Set up use of MKeyFind() for memory array

Call MKey(Mem_ValEarnDed, 0, "bValEarnDed.EarnTypeId", True)
Call MKey(Mem_ValEarnDed, 1, "bValEarnDed.DedId", True)

See Also
MKeyFind Function, MKeyFld Statement, MKeyOffset Statement, MSetRowNum
Statement, MSort Statement, VBA_MOpen Functions
148 Customization Manager Reference Visual Basic for Applications

MKeyFind Function
Find a specific record in a sorted memory array based on designated key field values.
Syntax
RecFetch = MKeyFind(MemHandle, KeySeg1Val, KeySeg2Val, KeySeg3Val,
KeySeg4Val, KeySeg5Val)
Remarks
Occasionally a program will need the ability to easily locate a particular record within
a memory array based on one or more key field values. The MKeyFind function can
be used to accomplish this goal assuming the sort order for the memory array has been
previously defined. Memory arrays associated with an SAFGrid control automatically
have their sort order initialized based on the key field control(s) contained within the
grid (i.e., notated by a “,k” in the levels property of the controls). All other memory
arrays must have their sort order explicitly defined via one of several different
methods. Each of the methods to define a key field, such as MKey, MKeyFld,
MKeyOffset, and MSetRowNum, vary primarily in the way they acquire detailed
information on a key field such as datatype, size and byte offset within a user-defined
datatype.
If a record whose key fields exactly match the KeySeg?Val arguments does not exist,
the system positions to the closest match. It will however still return a NOTFOUND to
the application.
The MKeyFind function uses the following arguments:

Argument Type Description

RecFetch Integer 0 if a record is successfully fetched. NOTFOUND is
returned if an exact match cannot be located.
MemHandle Integer Memory array resource handle.
KeySeg1Val Integer, Double Desired value for the first key segment.
or String
KeySeg2Val Integer, Double Desired value for the second key segment. PNULL if the
or String memory array only has one key segment.
KeySeg3Val Integer, Double Desired value for the third key segment. PNULL if the
or String memory array has less than three key segments.
KeySeg4Val Integer, Double Desired value for the fourth key segment. PNULL if the
or String memory array has less than four key segments.
KeySeg5Val Integer, Double Desired value for the fifth key segment. PNULL if the
or String memory array has less than five key segments.
 Solomon API Function Calls 149

Example
This example illustrates how to open a memory array and load the entire Solomon
Chart of Accounts into the newly created array and then find a specific account record.

Dim Mem_Account As Integer

Dim CSR_Account As Integer
Dim SqlStr As String
Dim Account_Fetch As Integer

'Open memory array to hold Chart of Accounts

Mem_Account = VBA_MOpen( TRUE, bAccount, Len(bAccount), "", 0, ↵
"", 0, "", 0)

'Set up use of MKeyFind() for memory array

Call MKey(Mem_Account, 0, "bAccount.Acct", True)

'Allocate cursor
Call SqlCursor( CSR_Account, NOLEVEL)

'Initialize cursor with a SQL statement and immediately fetch first

record
SqlStr = "Select * from Account order by Acct"
Account_Fetch = SqlFetch1(CSR_Account, SqlStr, bAccount, ↵
Len(bAccount))

'Read through all subsequent Account records, inserting each one into
'the memory array.
While( Account_Fetch = 0)

'Insert current Account record into the memory array

Call MInsert( Mem_Account)

'Fetch the next Account record

Account_Fetch = SFetch1(CSR_Account, bAccount, ↵
Len(bAccount))

Wend

'Find the memory array record for a specific account

Account_Fetch = MKeyFind( Mem_Account, "2020", "", "", "", "")

See Also
MKey Statement, MKeyFld Statement, MKeyOffset Statement, MSetRow Statement,
MSetRowNum Statement, MSort Statement, VBA_MOpen Functions
150 Customization Manager Reference Visual Basic for Applications

MKeyFld Statement
Define a key field for a previously opened memory array.
Syntax
Call MKeyFld(MemHandle, KeySegmentNbr, TableDotFieldName, bTable,
Ascending)
Remarks
Occasionally a program will need the ability to easily locate a particular record within
a memory array based on one or more key field values. The MKeyFind function can
be used to accomplish this goal assuming the sort order for the memory array has been
previously defined. Memory arrays associated with an SAFGrid control automatically
have their sort order initialized based on the key field control(s) contained within the
grid (i.e., notated by a “,k” in the levels property of the controls). All other memory
arrays must have their sort order explicitly defined via one of several different
methods. Each of the methods to define a key field, such as MKey, MKeyFld,
MKeyOffset, and MSetRowNum, vary primarily in the way they acquire detailed
information on a key field such as datatype, size and byte offset within a user-defined
datatype.
The MKeyFld method is similar to the MKey method except that it does not require a
VBA_SetAddr call for the relevant table.
Multi-segment keys can be defined by successive calls to MKeyFld with different
KeySegmentNbr argument values.
The MKeyFld statement uses the following arguments:

Argument Type Description

MemHandle Integer Unique handle to a previously opened memory
array.
KeySegmentNbr Integer Memory array key segment whose key field is
being defined. The first key segment number is
always zero. Multi-segment keys must have
contiguous key segment values such as 0 and 1 as
opposed to 0 and 3. The maximum allowable
number of key segments is five.
TableDotFieldName String Name of the designated key field in a
Table.FieldName format such as “Account.Acct.”
bTable User-defined Memory array table structure containing the
datatype designated key field. This table structure must also
have been previously passed to the VBA_MOpen
call.
Ascending Integer True if the key segment should be sorted ascending.
False to implement a descending sort sequence for
the key segment currently being defined.
 Solomon API Function Calls 151

Example
This example illustrates how to open a memory array and define multiple key fields.
Dim Mem_ValEarnDed As Integer

Mem_ValEarnDed = VBA_MOpen(True, bValEarnDed, Len(bValEarnDed), "", ↵

0, "", 0,"", 0)

'Set up use of MKeyFind() for memory array

Call MKeyFld(Mem_ValEarnDed, 0, "bValEarnDed.EarnTypeId", ↵
bValEarnDed, True)
Call MKeyFld(Mem_ValEarnDed, 1, "bValEarnDed.DedId", bValEarnDed,
↵ True)

See Also
MKey Statement, MKeyFind Function, MKeyOffset Statement, MSetRowNum
Statement, MSort Statement, VBA_MOpen Functions
152 Customization Manager Reference Visual Basic for Applications

MKeyOffset Statement
Define a key field for a previously opened memory array.
Syntax
Call MKeyOffset(MemHandle, KeySegmentNbr, bTable, KeyFldByteOffset,
KeyFldDataType, KeyFldDataLength, Ascending)
Remarks
Occasionally a program will need the ability to easily locate a particular record within
a memory array based on one or more key field values. The MKeyFind function can
be used to accomplish this goal assuming the sort order for the memory array has been
previously defined. Memory arrays associated with an SAFGrid control automatically
have their sort order initialized based on the key field control(s) contained within the
grid (i.e., notated by a “,k” in the levels property of the controls). All other memory
arrays must have their sort order explicitly defined via one of several different
methods. Each of the methods to define a key field, such as MKey, MKeyFld,
MKeyOffset, and MSetRowNum, vary primarily in the way they acquire detailed
information on a key field such as datatype, size and byte offset within a user-defined
datatype.
The MKeyOffset method is the most flexible method of defining memory array key
fields but it is also the most detailed to code. It is designed to facilitate the definition of
a key field that does not exist in the database and therefore has no correlated data
dictionary information in the database. This situation can occur if one of the user-
defined datatypes in a memory array is only declared within VB and does not exist
within the database. In such a case, the system has no way of determining the byte
offset from the beginning of the structure for any particular field, the field datatype nor
the length of the field. The MKeyOffset statement allows the developer to explicitly
pass all of this detailed information relating to the designated key field since it does not
exist in the SQL data dictionary.
Multi-segment keys can be defined by successive calls to MKeyOffset with different
KeySegmentNbr argument values.
 Solomon API Function Calls 153

The MKeyOffset statement uses the following arguments:

Argument Type Description

MemHandle Integer Unique handle to a previously opened memory
array.
KeySegmentNbr Integer Memory array key segment whose key field is
being defined. The first key segment number is
always zero. Multi-segment keys must have
contiguous key segment values such as 0 and 1 as
opposed to 0 and 3. The maximum allowable
number of key segments is five.
bTable User-defined Memory array table structure containing the
datatype designated key field. This table structure must also
have been previously passed to the VBA_MOpen
call.
KeyFldByteOffset Integer This argument is designed to help the system locate
the first byte of the designated key field. The
system will already know the memory location of
the first byte of the entire user-defined datatype via
the bTable argument. The byte offset tells the
system how far the first byte of the designated key
field is offset from the first byte of the entire user-
defined datatype. If the designated key field is the
first field in the user-defined datatype then a value
of zero should be passed.
KeyFldDataType Integer Specifies the datatype of the designated key field.
The following datatype constants are declared in the
VBTools_VBA module:
String
Float
Integer
Date
Time
KeyFldDataLength Integer Size of the designated key field. For example,
LenB(bTable.KeyFld). Note: In Solomon, it is
critical to use LenB() instead of Len() for all non-
null “table length” parameters.
Ascending Integer True if the key segment should be sorted ascending.
False to implement a descending sort sequence for
the key segment currently being defined.
154 Customization Manager Reference Visual Basic for Applications

Example
The following example illustrates a memory array containing only selected fields from
the Employee table that is nevertheless sorted by Employee ID. By only storing
selected Employee fields in the memory array, much less memory will be consumed
for each record within the memory array.
Since not all fields in the Employee database table are contained within the
Employee_SelFld user-defined datatype, the data dictionary information in the SQL
database corresponding to the standard Employee table is not usable by the system for
purposes of determining the required key field information. Consequently,
MKeyOffset must be utilized to implement sorting on the Employee ID key field.
Code to declare the user-defined datatype containing only selected fields from the
Employee table. Notice that the Name field is being deliberately declared before the
EmpId field so as to further illustrate the complete flexibility of MKeyOffset.
Type Employee_SelFld
Name As String * 30
EmpId As String * 10
End Type

Global bEmployee_SelFld As Employee_SelFld

Code to open a memory array for the bEmployee_SelFld user-defined datatype and
define Employee ID as the key field.
Dim Mem_Employee_SelFld As Integer

Mem_Employee_SelFld = VBA_MOpen( TRUE, bEmployee_SelFld, ↵

Len(bEmployee_SelFld), PNULL, 0, PNULL, 0, PNULL, 0)

Call MKeyOffset(Mem_Employee_SelFld, 0, bEmployee_SelFld, 30, ↵

DATA_TYPE_STRING, LenB(bEmployee_SelFld.EmpId), True)
 Solomon API Function Calls 155

Code to load the memory array with relevant selected fields for all employees in the
database. Notice that the order of the fields in the SQL Select statement correspond to
the order of the fields in the Employee_SelFld user-defined datatype.
Dim CSR_Employee_SelFld As Integer
Dim SqlStr As String
Dim Employee_SelFld_Fetch As Integer

'Allocate a cursor
Call SqlCursor(CSR_Employee_SelFld, NOLEVEL)

'Initialize cursor with a SQL statement and immediately fetch

'the first record
SqlStr = "Select Name, EmpId from Employee Order By EmpId"
Employee_SelFld_Fetch = SqlFetch1(CSR_Employee_SelFld, SqlStr, ↵
bEmployee_SelFld, LenB(bEmployee_SelFld))

'Read through all subsequent Employee records, inserting each one into
'the memory array.
While(Employee_SelFld_Fetch = 0)

'Insert current Employee record into the memory array

Call MInsert( Mem_Employee_SelFld)

'Fetch the next Employee record

Employee_SelFld_Fetch = SFetch1(CSR_Employee_SelFld,
bEmployee_SelFld, LenB(bEmployee_SelFld))

Wend

See Also
MKey Statement, MKeyFind Function, MKeyFld Statement, MSetRowNum
Statement, MSort Statement, VBA_MOpen Functions
156 Customization Manager Reference Visual Basic for Applications

MLast Function
Move to the last record in a designated memory array.
Syntax
RecFetch = MLast(MemHandle, RecMaintFlg)
Remarks
MLast moves to the last record of a specified memory array and copies the contents of
the array record into the data structure(s) previously specified in the VBA_MOpen
function call used to originally open the relevant memory array.
When this call is used on a memory array associated with an SAFGrid control (i.e.,
memory arrays opened automatically), an MDisplay call will be needed to properly
synchronize the grid appearance with the memory array.
The MLast function uses the following arguments:

Argument Type Description

RecFetch Integer 0 if a record is successfully fetched. NOTFOUND is
returned if no records exist in the specified memory array.
MemHandle Integer Memory array resource handle.
RecMaintFlg Integer Status of the memory array record (assuming it was
successfully fetched). the VBTools_VBA module contains
the following symbolic constants defining possible
memory array record status values: INSERTED,
UPDATED and NOTCHANGED

See Also
MFirst Function, MNext Function, MPrev Function
 Solomon API Function Calls 157

MLoad Statement
Load a memory array with all records returned from the database by an SQL statement.
Syntax
Call MLoad(MemHandle, Cursor)
Remarks
There are two ways to load data directly from the database into a memory array. The
most obvious method is to insert one record at a time into the memory array until no
additional records are returned from the database. A simpler method is to load the
entire array via a single call to the MLoad statement. The only requirement is that the
Cursor passed as a parameter to the MLoad statement must already be initialized with
an SQL Select statement or stored procedure so it is ready to begin returning data.
Passing the SQL Select statement or stored procedure, along with any necessary
parameters, to the Sql statement can initialize the cursor.
The MLoad statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle.
Cursor Integer SQL database cursor. This cursor must have already been
initialized with an SQL Select statement or stored
procedure.

Example
The following example illustrates a memory array containing only selected fields from
the Employee table that is nevertheless sorted by Employee ID. By only storing
selected Employee fields in the memory array, less memory is consumed for each
record within the memory array.
Since not all fields in the Employee database table are contained within the
Employee_SelFld user-defined datatype, the data dictionary information in the SQL
database corresponding to the standard Employee table is not usable by the system for
purposes of determining the required key field information. Consequently,
MKeyOffset must be utilized to implement sorting on the Employee ID key field.
Code to declare the user-defined datatype containing only selected fields from the
Employee table. Notice that the Name field is being deliberately declared before the
EmpId field so as to further illustrate the complete flexibility of MKeyOffset.

Type Employee_SelFld
Name As String * 30
EmpId As String * 10
End Type

Global bEmployee_SelFld As Employee_SelFld

158 Customization Manager Reference Visual Basic for Applications

Code to open a memory array for the bEmployee_SelFld user-defined datatype and
define Employee ID as the key field.
Dim Mem_Employee_SelFld As Integer

Mem_Employee_SelFld = VBA_MOpen( TRUE, ↵

bEmployee_SelFld,Len(bEmployee_SelFld), "", 0, "", 0, "", 0)

Call MKeyOffset(Mem_Employee_SelFld, 0, bEmployee_SelFld, 30, ↵

DATA_TYPE_STRING, Len(bEmployee_SelFld.EmpId), True)
Code to load the memory array with relevant selected fields for all employees in the
database. Notice that the order of the fields in the SQL Select statement correspond to
the order of the fields in the Employee_SelFld user-defined datatype.
Dim CSR_Employee_SelFld As Integer
Dim SqlStr As String
Dim Employee_SelFld_Fetch As Integer

'Allocate a cursor
Call SqlCursor(CSR_Employee_SelFld, NOLEVEL)

'Initialize cursor with a SQL statement and immediately fetch

'the first record
SqlStr = "Select Name, EmpId from Employee Order By EmpId"
Employee_SelFld_Fetch = SqlFetch1(CSR_Employee_SelFld, SqlStr,
bEmployee_SelFld, Len(bEmployee_SelFld))

'Read through all subsequent Employee records, inserting each one into ↵
the
'memory array.
While(Employee_SelFld_Fetch = 0)

'Insert current Employee record into the memory array

Call MInsert( Mem_Employee_SelFld)

'Fetch the next Employee record

Employee_SelFld_Fetch = SFetch1(CSR_Employee_SelFld,
bEmployee_SelFld, Len(bEmployee_SelFld))

Wend

See Also
Sql Statement
 Solomon API Function Calls 159

MNext Function
Move to the next record in a designated memory array.
Syntax
RecFetch = MNext(MemHandle, RecMaintFlg)
Remarks
MNext moves to the next record of a specified memory array and copies the contents
of the array record into the data structure(s) previously specified in the VBA_MOpen
function call used to originally open the relevant memory array.
When this call is used on a memory array associated with an SAFGrid control (i.e.,
memory arrays opened automatically), an MDisplay call will be necessitated to
properly synchronize the SAFGrid appearance with the memory array.
The MNext function uses the following arguments:

Argument Type Description

RecFetch Integer 0 if a record is successfully fetched. NOTFOUND is
returned if the current record is already the last record in
the specified memory array as well as when no records
exist.
MemHandle Integer Memory array resource handle.
RecMaintFlg Integer Status of the memory array record (assuming it was
successfully fetched). the VBTools_VBA module contains
the following symbolic constants defining possible
memory array record status values: INSERTED,
UPDATED and NOTCHANGED

See Also
MFirst Function, MLast Function, MPrev Function
160 Customization Manager Reference Visual Basic for Applications

MPrev Function
Move to the previous record in a designated memory array.
Syntax
RecFetch = MPrev(MemHandle, RecMaintFlg)
Remarks
MPrev moves to the previous record of a specified memory array and copies the
contents of the array record into the data structure(s) previously specified in the
VBA_MOpen function call used to originally open the relevant memory array.
When this call is used on a memory array associated with an SAFGrid control (i.e.,
memory arrays opened automatically), an MDisplay call will be necessitated to
properly synchronize the SAFGrid appearance with the memory array.
The MPrev function uses the following arguments:

Argument Type Description

RecFetch Integer 0 if a record is successfully fetched. NOTFOUND is
returned if the current record is already the first record in
the specified memory array as well as when no records
exist.
MemHandle Integer Memory array resource handle.
RecMaintFlg Integer Status of the memory array record (assuming it was
successfully fetched). the VBTools_VBA module contains
the following symbolic constants defining possible
memory array record status values: INSERTED,
UPDATED and NOTCHANGED

See Also
MFirst Function, MLast Function, MNext Function
 Solomon API Function Calls 161

MRowCnt Function
Returns the number of records in a designated memory array.
Syntax
NumRecs = MRowCnt( MemHandle)
Remarks
The MRowCnt function uses the following arguments:

Argument Type Description

NumRecs Integer Number of records in the designated memory array
MemHandle Integer Memory array resource handle

Example
Global ArrayHandle%, Rows%
ArrayHandle = GetGridHandle("Spread1")
Rows = MRowCnt(ArrayHandle)

See Also
VBA_MOpen Functions
162 Customization Manager Reference Visual Basic for Applications

MSet Statement
Explicitly set the value of a particular control for every record in its corresponding
SAFGrid control.
Syntax
Call MSet(Control, NewDataValue)
Remarks
The MSet statement uses the following arguments:

Argument Type Description

Control String Control which is bound to the Record.FieldName whose
value is to be changed for every record in the relevant
SAFGrid. Note: This statement is only for use with
controls associated with an SAFGrid control.
NewDataValue String New data value for the Record.FieldName associated
with the designated Control. The data value must be in a
string format.

See Also
MSetProp Statement
 Solomon API Function Calls 163

MSetLineStatus Function
Set the line status of the current record in the designated memory array.
Syntax
RetVal = MSetLineStatus(MemHandle, NewLineStatus)
Remarks
Each record within a memory array has its own line status such as INSERTED,
UPDATED or NOTCHANGED. The system automatically modifies the line status
based on the type of activity last performed on any particular memory array record. For
example if a record is inserted into a memory array using MInsert, then the status of
that new memory array record will automatically be set to INSERTED. Occasionally,
however, the application may need to assign a specific line status to a particular
memory array record. In such cases the MSetLineStatus function can be used to carry
out this task.
One common usage of this function is when a memory array associated with an
SAFGrid control is being loaded from the database under application control. In these
cases records are being inserted into the memory array via successive MInsert calls.
However since the data is in no way modified between the time it is fetched and the
time it is inserted into the memory array the line status of the resultant memory array
record is forced to change from INSERTED to NOTCHANGED.
The MSetLineStatus function uses the following arguments:

Argument Type Description

RetVal Integer -1 if an invalid memory array handle is passed.
MemHandle Integer Memory array resource handle.
RecMaintFlg Integer New status of the current memory array record. the
VBTools_VBA module contains the following symbolic
constants defining possible memory array record status
values: INSERTED, UPDATED and NOTCHANGED.
164 Customization Manager Reference Visual Basic for Applications

Example
This example illustrates how to load a memory array from the database and at the same
time force the line status of all newly inserted memory array records to be
NOTCHANGED.

Dim Mem_Account As Integer

Dim CSR_Account As Integer
Dim SqlStr As String
Dim Account_Fetch As Integer
Dim Retval As Integer

'Open memory array to hold Chart of Accounts

Mem_Account = VBA_MOpen( TRUE, bAccount, Len(bAccount), "", 0, ↵
"", 0,"", 0)

'Allocate cursor
Call SqlCursor( CSR_Account, NOLEVEL)

'Initialize cursor with a SQL statement and immediately fetch first

record
SqlStr = "Select * from Account order by Acct"
Account_Fetch = SqlFetch1(CSR_Account, SqlStr, bAccount, ↵
Len(bAccount))

'Read through all subsequent Account records, inserting each one into
'the memory array.
While( Account_Fetch = 0)

'Insert current Account record into the memory array

Call MInsert( Mem_Account)

'Since the record ALREADY exists in the database, reset ↵

the line
'status of the current memory array record so that the ↵
application
'will be able to detect whether or not any calls to ↵
MUpdate were
'subsequently made for the current record.
Retval = MSetLineStatus(Mem_Account, NOTCHANGED)

'Fetch the next Account record

Account_Fetch = SFetch1(CSR_Account, bAccount, ↵
Len(bAccount))

Wend

See Also
MGetLineStatus Function, MInsert Statement, MUpdate Statement
 Solomon API Function Calls 165

MSetProp Statement
Set the value of a particular property for both the designated form-view control as well
as its associated SAFGrid control.
Syntax
Call MSetProp(Control, PropertyName, NewPropValue)
Remarks
At runtime, each column of an SAFGrid control is associated with an underlying (i.e.,
form-view) Solomon Tools for Visual Basic custom control. The MSetProp statement
can be used to modify a property setting for both the underlying control as well as the
relevant column in the associated grid. For example, an entire column can be disabled
using the MSetProp statement.
If the application wants to modify property values on a line by line basis, as opposed to
an entire column, then it will need to manage the property settings using calls to the
SetProp statement from within the LineGotFocus event of each individual detail line.
The MSetProp statement uses the following arguments:

Argument Type Description

Control String Control whose designated property value is to be
modified both in form-view as well as grid-view.
PropertyName String Name of the property whose value is to be modified.
NewPropValue String or New property value. The actual datatype varies based on
Integer the property being referenced.

Example
'Disable the ExtRefNbr Column
Call MsetProp("cextrefnbr", PROP_ENABLED, False)

'Enable the ExtRefNbr Column

Call MsetProp("cextrefnbr", PROP_ENABLED, True)

See Also
BlankErr Property, Enabled Property, Heading Property, Mask Property, Min Property,
Max Property, SetProp Statement, Visible Property
166 Customization Manager Reference Visual Basic for Applications

MSetRowNum Statement
Set the current row/record number of a designated memory array.
Syntax
Call MSetRowNum( MemHandle, NewCurrRecNbr)
Remarks
An application can jump to a specific memory array record via either the MKeyFind
function or the MSetRowNum statement. MSetRow jumps to a specific record number
whereas MKeyFind locates the record with designated key field values.
The MSetRowNum statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle
NewCurrRecNbr Integer Row/record number of the desired memory array
record

See Also
MGetRowNum Function, MKeyFind Function
 Solomon API Function Calls 167

MSort Statement
Sort data contained within an existing memory array based upon predefined key fields.
Syntax
Call MSort( MemHandle)
Remarks
This statement will sort all existing records within the designated memory array based
upon key fields previously defined using one of the MKey, MKeyFld, MkeyOffset, or
MSetRowNum statements.
If the data within the memory array is initially loaded and maintained in the proper
order, a call to MSort will not be necessary. MSort only needs to be called if one or
more records within the memory array are not in an order consistent with the
previously defined key fields. When the data is out of order, MKeyFind will not work
properly since it assumes that the data within the memory array is consistent with the
predefined sort sequences.
Memory arrays associated with an SAFGrid control require an MDisplay call to
redisplay the grid, subsequent to calling MSort.
See Also
MKey Statement, MKeyFind Function, MKeyOffset Function, MSetRowNum
Statement,VBA_MOpen Functions
168 Customization Manager Reference Visual Basic for Applications

MUpdate Statement
Update the current memory array record of a designated memory array with new data
values.
Syntax
Call MUpdate(MemHandle)
Remarks
MUpdate is used to update an existing record of a specified memory array. This is
accomplished by copying the new contents of all data structures previously associated
with the designated memory array over the existing memory array record. Data
structures are associated with a memory array in the VBA_MOpen function call used
to originally open the relevant memory array. If the memory array record had a line
status of INSERTED prior to the MUpdate call then the line status will remain
INSERTED. In all other cases, the memory array record will have a line status of
UPDATED.
The MUpdate statement uses the following arguments:

Argument Type Description

MemHandle Integer Memory array resource handle

See Also
MDelete Function, MInsert Statement, MSetLineStatus Function, VBA_MOpen
Functions
 Solomon API Function Calls 169

NameAltDisplay Function
Displays a string field with swap character suppressed.
Syntax
StrVar = NameAltDisplay ( FieldName)
Remarks
To accommodate alternate sorting by name, Solomon stores most address and name
fields based on where the “@” is placed in the name. For example, in order for “The
Jones Company” to sort with the Js, this name must be entered as The @Jones
Company. Solomon then stores this entry as Jones Company~The. If you wish to
subsequently retrieve and/or manipulate this field in VBA code, this function “flips”
the name and suppress the ~ and @. In this example, Jones Company~The as stored in
the database is displayed as The Jones Company.
The NameAltDisplay function uses the following arguments:

Argument Type Description

StrVar String Any string variable in which to store the swapped version
of the field
FieldName String Object or Field name

Example
Dim SwapName$, OrigName$

OrigName = GetObjectValue("cname")
Call MessBox(OrigName, MB_OK, "Orig Name")

SwapName = NameAltDisplay(OrigName)
Call MessBox(SwapName, MB_OK, "Swap Name")

See Also
GetObjectValue Function, SetObjectValue Function
170 Customization Manager Reference Visual Basic for Applications

PasteTemplate Function
Paste information from the designated template into the current application.
Syntax
RetVal = PasteTemplate(TemplateID)
Remarks
The Solomon Template feature makes it possible to store data from the current screen
and subsequently paste that data into the same screen at a later time. Templates can be
saved to the database programmatically using the SaveTemplate statement as well as
via the Template menu item on the Edit menu. Once a template has been created it can
be pasted into its source application under program control using the PasteTemplate
function as well as via the Template menu item on the Edit menu.
The PasteTemplate statement uses the following arguments:

Argument Type Description

RetVal Integer Zero if no errors occurred. The NOTFOUND symbolic
constant, declared in the VBTools_VBA module, is
returned if the TemplateID does not exist.
TemplateID String ID of the template whose information is to be pasted into
the current Solomon Tools for Visual Basic® application
screen.

See Also
SaveTemplate Statement
 Solomon API Function Calls 171

PeriodCheck Function
Verify whether or not a period string in YYYYPP format represents a valid fiscal
period.
Syntax
RetVal = PeriodCheck(PeriodString)
Remarks
The PeriodCheck function uses the following arguments:

Argument Type Description

RetVal Integer Value of the period number portion of PeriodString if the
string represents a valid fiscal period. Otherwise a value of
-1 will be returned if the string is invalid. A period string is
invalid if the period portion is less than one or greater than
the number of valid fiscal periods defined in the GLSetup
record.
PeriodString String Period string to be verified. Must be in YYYYPP format.

Example
'Example placed in Chk event of a String user field
'The mask property on this field is Custom mask Type, 99-9999

Dim Year$, Period$

Year = Right$(chkstrg, 4)
Period = Left$(chkstrg, 2)
serr = PeriodCheck(Year + Period)
172 Customization Manager Reference Visual Basic for Applications

PeriodMinusPeriod Function
Return the number of periods between two fiscal periods.
Syntax
NbrPeriods = PeriodMinusPeriod(PerNbr1, PerNbr2)
Remarks
The PeriodMinusPeriod function uses the following arguments:

Argument Type Description

NbrPeriods Integer Number of periods between PerNbr1 and PerNbr2. If
PerNbr1 > PerNbr2 then the number of fiscal periods
between the two periods will be a negative value.
PerNbr1 String Beginning fiscal period. Must be in YYYYPP format.
PerNbr2 String Ending fiscal period. Must be in YYYYPP format.

Note: This function will use the number of periods in a fiscal year, as specified in the
GLSetup record, in order to derive an accurate result.

Example
Dim Period1$, Period2$
Dim NumPers%

Period1 = GetObjectValue("cperpost")
Period2 = "199312"
NumPers = PeriodMinusPeriod(Period1, Period2)

If NumPers < 0 Then

Call MessBox("Cannot post back further than 12-93", MB_OK, ↵
"Solomon Message")
End If

See Also
PeriodPlusPerNum Function
 Solomon API Function Calls 173

PeriodPlusPerNum Function
Add a designated number of periods to an existing fiscal period.
Syntax
ResultingPerNbr = PeriodPlusPerNum(CurrPerNbr, NbrPeriodsToAdd)
Remarks
The PeriodPlusPerNum function uses the following arguments:

Argument Type Description

ResultingPerNbr String Result of CurrPerNbr + NbrPeriodsToAdd.
CurrPerNbr String Starting fiscal period. Must be in YYYYPP format.
NbrPeriodsToAdd Integer Number of fiscal periods to add to CurrPerNbr.
Negative values are supported.

Note: This function will use the number of periods in a fiscal year, as specified in the
GLSetup record, in order to derive an accurate result.

Example
'Increment PerPost to the next fiscal period
Dim NewPeriod$, PeriodToPost$, NumberOfPeriods%

NumberOfPeriods = 1
PeriodToPost = GetObjectValue("cperpost")

NewPeriod = PeriodPlusPerNum(PeriodToPost, NumberOfPeriods)

See Also
PeriodMinusPeriod Function
174 Customization Manager Reference Visual Basic for Applications

PVChkFetch Functions
Retrieve a composite record from the database using an SQL statement from the PV
property of an SAFMaskedText control.
Syntax
RetVal = PVChkFetch1(Ctrl, Cursor, SQLParmValue, bTable1, bTable1Length)
RetVal = PVChkFetch4(Ctrl, Cursor, SQLParmValue, bTable1, bTable1Length,
bTable2, bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length)
RetVal = PVChkFetch8(Ctrl, Cursor, SQLParmValue, bTable1, bTable1Length,
bTable2, bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length, bTable5,
bTable5Length, bTable6, bTable6Length, bTable7, bTable7Length, bTable8,
bTable8Length)
Remarks
Each SAFMaskedText control has a PV property which can contain an SQL statement
or stored procedure name. These functions can be used to fetch a composite record
instance based on the SQL text from the PV property of the control specified in the
Ctrl parameter. These functions are not applicable if the PV property does not contain
either an SQL statement or stored procedure name.
PVChkFetch1 is designed for SQL statements returning data from a single table. For
more advanced SQL statements having one or more table joins either PVChkFetch4 or
PVChkFetch8 can be used.
The PVChkFetch1 function uses the following arguments (PVChkFetch4 and
PVChkFetch8 respectively have four and eight table structures and corresponding
lengths. PNULL should be passed for unused table structure parameters as well as a
corresponding length of zero such as PNULL, 0)

Argument Type Description

RetVal Integer 0 if a record is successfully fetched.
NOTFOUND is returned if no records match
the restriction clause of the PV SQL
statement.
Ctrl Control Control containing the PV property to be used
as the SQL statement. Can optionally be
PNULL if the call is made within the Chk
event of the control whose PV property is
being used.
Cursor Integer SQL database cursor.
SQLParmValue String Key value passed as the last parameter to the
restriction clause of the PV SQL statement.
bTable1 User-defined Table structure corresponding to the primary
datatype table in the PV SQL statement.
 Solomon API Function Calls 175

Argument Type Description

bTable1Length Integer Size of first table structure. For example,
LenB(bTable1). Note: It is critical to use
LenB() instead of Len() for all non-null
“table length” parameters.

Example
The following example illustrates the usage of PVChkFetch1 in the Chk event of a
Payroll Work Location ID control. Since PNULL is passed for the control parameter
the SQL statement in the PV property of the cWrkLocId control itself is used. The ID
entered by the user is passed to the Chk event as chkstrg. By sending this value to
PVChkFetch1 it will be used as the last parameter to the restriction clause of the PV
SQL statement.
Sub cWrkLocId_Chk (chkstrg As String, retval As Integer)
Dim WorkLocation_Fetch As Integer

WorkLocation_Fetch = PVChkFetch1(PNULL, CSR_WorkLocation, chkstrg, ↵

bWorkLoc, LenB(bWorkLoc))

RetVal = NoAction

End Sub

See Also
DBNavFetch Functions
176 Customization Manager Reference Visual Basic for Applications

SaveTemplate Statement
Save information from the current application to a designated template.
Syntax
Call SaveTemplate(TemplateID, Description, AppliesToUserID, IncludeLowerLevels,
StartingLevelNbr)
Remarks
The Solomon Template feature makes it possible to store data from the current screen
and subsequently paste that data into the same screen at a later time. These timesaving
templates can be saved to the database programmatically using the SaveTemplate
statement as well as via the Template menu item on the Edit menu. Each template can
contain complete transactions and entities or individual fields selected by the user.
Relative date and period features allow a template to paste data relative to the current
date and fiscal period. Templates can be designated as private to a specific user or
marked public for availability to all users. Templates are stored in the system database
and therefore they are independent of any particular application database.
Unless otherwise specified, all date and period values pasted from a template will be
equal to the Solomon business date, located on the File menu, and the current period for
the module. To override this default action, the user entering data for the template must
specify a new relative date or period value for each desired field. This is done
immediately before saving a template. Specifying a relative date or period value for a
field contained in grid detail lines will change the template value of that field for all
detail lines. Relative values can be defined by selecting the pertinent date or period
field and pressing F2 to start the Relative Date or Relative Period window – whichever
is appropriate.
 Solomon API Function Calls 177

The SaveTemplate statement uses the following arguments:

Argument Type Description

TemplateID String ID of the template being created or updated. If a
template with the designated TemplateID already
exists, it will be overwritten. The TemplateID can
be up to 30 characters.
Description String Description of the template.
AppliesToUserID String Solomon User ID to which the template applies. By
default, the template will be Public if
AppliesToUserID is left blank.
IncludeLowerLevels Integer False if only data for the StartingLevelNbr is to be
saved to the template. Otherwise data for lower
levels, in addition to StartingLevelNbr, will also be
saved to the template.
StartingLevelNbr Integer Number of the first application level for which data
is to be saved to the template. For example on
Batch/Document/Detail screens, a value of zero
could be passed to start the save with the Batch
level. the VBTools_VBA module contains two
symbolic constants which can also be passed:
CcpSelectedFields – Only those fields currently
highlighted by the user will be saved to the
template.
CcpAllLevels – Data from all application levels will
be saved to the template regardless of the
IncludeLowerLevels argument value.

See Also
PasteTemplate Function
178 Customization Manager Reference Visual Basic for Applications

SDelete Statement
Delete the current record from a designated table within an existing SQL view.
Syntax
Call SDelete(Cursor, TablesDeletingFrom)
Remarks
A value of “*.*“ can be passed as a table name, meaning that all current records in the
existing view will be deleted. Please note that this call requires that the current record
already be fetched via such functions as SqlFetch1 or SFetch1 so that the designated
cursor actually has a current record.
The SDelete statement uses the following arguments:

Argument Type Description

Cursor Integer SQL database cursor.
TablesDeletingFrom String Name of each table, in the specified cursor’s view,
from which the current record is to be deleted.
Commas should separate multiple table names.

Example
'Example is deleting in Solomon's OnDelete event

'Note that the following fetch been has issued in

'a preceding event prior to the delete call
serr1 = SqlFetch1(c1, "XCustInfo_All" +
sparm(chkstrg), bXCustAddlInfo, Len(bXCustAddlInfo))

Sub Delete(level%, retval%)

If Level = 0 Then
serr1 = sdelete(c1, "XCustAddlInfo")
End If
End Sub

See Also
SFetch Functions, SqlFetch Functions
 Solomon API Function Calls 179

SDeleteAll Function
Delete all records from the designated table(s) within a predefined view.
Syntax
RetVal = SDeleteAll(Cursor, TablesDeletingFrom)
Remarks
Deletes records from some or all of the tables in a view based on the current
restrictions. A view must have already been initialized for the specified cursor via
functions such as Sql, SFetch1 or SqlFetch4. If no restriction is specified when the
cursor is initialized, then this call will remove all records from the designated table(s)
in the view.
The SDeleteAll function uses the following arguments:

Argument Type Description

RetVal Integer
Cursor Integer SQL database cursor.
TablesDeletingFrom String Name of each table, in the specified cursor’s view,
from which all records within the current view are
to be deleted. Commas should separate multiple
table names. A value of “*.*” can be used to delete
records from all tables within the view.

Example
Delete all vendors having a zero balance.
Dim SqlStr As String

'Initialize the cursor with a SQL statement

SqlStr = "Select * from Vendor where CurrBal = 0 and FutureBal = 0"
Call Sql(CSR_Vendor_Del, SqlStr)

'Delete all records matching the restriction clause of the SQL statement
'used to initialize the CSR_Vendor_Del cursor.
Call SDeleteAll(CSR_Vendor_Del, "*.*")

See Also
SFetch Functions, Sql Statement, SqlFetch Functions
180 Customization Manager Reference Visual Basic for Applications

SetBufferValue Statement
Sets an underlying Solomon application’s data buffer field to a specified value.
Syntax
Call SetBufferValue(bTable.FieldName, Str)
Remarks
If a VBA application issues its own VBA_SetAddr calls it can then reference any of
these structures from within code. However, if the underlying Solomon application’s
structures need to be referenced and these fields are not represented as objects on the
form, this statement allows the VBA application to obtain these values. If the fields
were objects on the form, the VBA application can simply issue SetObjectValue
instead.
Be aware that usage of this call at times could compromise the underlying Solomon
application functionality, especially if a dependent field is changed. Likewise, the
underlying application may change your value if you have set it too early.
The SetBufferValue statement uses the following arguments:

Argument Type Description

bTable.FieldName String SQL Table.FieldName that you wish to set.
Str String String or string variable that contains the value
that your changing the specific
bTable.FieldName to.

Example
Call SetBufferValue("bGLTran.RefNbr","000099")

See Also
GetBufferValue Statement
 Solomon API Function Calls 181

SetDefaults Statement
Set one or more controls to their default value using either their Default Property or
Default Event code.
Syntax
RetVal = SetDefaults (FormObjectName, FieldObjectName)
Remarks
Each data object has both a Default property as well as a Default event. Any particular
data object can use one of these two methods to define a default data value for itself.
The system uses these methods any time a particular data object is to be initialized to
its default value. An exhaustive discussion of all the times when this occurs is beyond
the scope of the SetDefaults statement. However, one such time an object is set to its
default value is when the application explicitly directs the system to do so via usage of
the SetDefaults statement in reference to the relevant object.
The SetDefaults statement can be used to default all objects in a subform. The
Level_SetDefaults statement is functionally equivalent except it can be used to
explicitly default all objects having a particular level number.
Since SetDefaults implies a change in the data value of the designated object, the
system “marks” the object as requiring error checking. The system does not, however,
immediately perform the requisite error checking (for example, it does not immediately
fire the Chk event). The error checking is nevertheless guaranteed to occur prior to any
updates to the database.
Note that when an application needs to null out a particular field, perhaps because the
field is no longer applicable, it should explicitly do so programmatically and then
redisplay the relevant object using the DispField statement. After the object has been
redisplayed, it can then be disabled using the SetProp statement. The SetDefaults
statement should not be used in these cases even if the relevant control has no Default
Property value and no code within Default Event. A developer may well wonder why
this caution would be expressed since the field is, in fact, nulled out when no Default
Property or Event code exists and, therefore, the application appears to work properly
during testing. The following code conceptually illustrates how to properly null out and
disable a control which is no longer applicable:
Record.Field = NULL (0 for numeric datatypes , "" for string datatype)
Call DispFields("Form1", "cField")
Call SetProp ("cField", PROP_ENABLED, False)
182 Customization Manager Reference Visual Basic for Applications

The SetDefaults function uses the following arguments:

Argument Type Description

RetVal Integer Any integer variable (serr, serr1 – serr12 declared
in the VBTools_VBA module are reserved for this
use).
FormObjectName String Form name. Can be "" to include all forms in
application.
FieldObjectName String Field name. Can be "" to include all objects in a
specific form.

Example
Example fetches from custom table, evaluates the return value and sets up custom form
for entry/edit.
serr1 = sqlfetch1(c1, "XCustAddlInfo_CustId" +
sparm(chkstrg), bXCustAddlInfo, Len(bXCustAddlInfo))

If serr1 = NOTFOUND Then

serr1 = SetDefaults("NewInfo", "")
bXCustAddlInfo.CustId = chkstrg
Found_Cust = "N"
Else
Found_Cust = "Y"
End If

Call DispFields("NewInfo","")

See Also
DispField Statements, SetProp Statement
 Solomon API Function Calls 183

SetLevelChg Statement
Set the update status of a specific level.
Syntax
Call SetLevelChg(LevelNbr, Status)
Remarks
Each update level, as defined by the Levels property of the SAFUpdate control, has a
corresponding level status flag that is automatically maintained by the system. The
purpose of the level status flag is to facilitate the optimization of database updates
performed in response to Parent toolbar buttons. In general, these flags allow the
system to only perform database updates for update levels which have in fact changed.
If no information has changed then no information needs to be saved.
As previously mentioned, these update flags are automatically maintained by the
system. When an existing record is loaded the flag is set to NOTCHANGED. If any
non-key field is subsequently modified then the level status flag for the corresponding
level is set to UPDATED. When a new record is being entered, the level status flag is
set to INSERTED.
The SetLevelChg statement allows the application to override the current value a the
status flag for a particular level. This can be useful if a data value is modified
programmatically and therefore the system needs to be notified that something has
changed so the corresponding information will actually be saved when the user presses
the Save toolbar button.
The SetLevelChg statement uses the following arguments:

Argument Type Description

LevelNbr Integer Level whose status flag is to be explicitly set.
Status Integer Level status flag. The following valid values are defined as
symbolic constants in the VBTools_VBA module:
INSERTED, UPDATED, NOTCHANGED.
184 Customization Manager Reference Visual Basic for Applications

Example
The Payroll module’s Earnings Type Maintenance (02.270.00) window contains a
button to automatically populate the grid with all Deductions. This amounts to
inserting records into the grid (i.e., into its underlying memory array) under program
control. Since the data is not entered via the user interface by the user, the system
needs to be notified that information at the grid level (i.e., LEVEL1 in this case) has
been programmatically updated and therefore needs to be saved. However, such
notification only needs to occur if the system is not already aware that data has
changed.
'If any records were inserted into the memory array then we need to make
'sure that the level status for the detail level is something other than
'NOTCHANGED so the system will know that something needs to be saved.
If (AnyRecsInserted = True) Then

If (TestLevelChg(LEVEL1) = NOTCHANGED) Then

Call SetLevelChg(LEVEL1, UPDATED)
End If

End If

See Also
TestLevelChg Function
 Solomon API Function Calls 185

SetObjectValue Function
Sets a specified object field’s value.
Syntax
IntVar = SetObjectValue( ObjectName, Value)
Remarks
This function allows you to set the value of any bound object on the screen. The object
must be on the form in order to set it. If you wish to set a value of a field that is not on
the form, you can use the SetBufferValue statement instead.
Note that you can use this function to set disabled and invisible objects that you make
invisible or hidden. You cannot set disabled or invisible standard Solomon objects.
The Chk event of the object you set is also executed so that all error checking takes
place.
The SetObjectValue function uses the following arguments:

Argument Type Description

IntVar Integer Any integer variable (serr, serr1 – serr12 declared in the
VBTools_VBA module are reserved for this use).
ObjectName String Name of the object whose value you wish to set.
Value String Value you wish to set ObjectName to.

Example
Dim CommissionAmount As Double
Dim ExtendedAmount As Double

ExtendedAmount = Val (chkstrg$)

If ExtendedAmount <= 1000 Then
CommissionAmount = 1
ElseIf ExtendedAmount <= 2000 then
CommissionAmount = 2
ElseIf ExtendedAmount <= 3000 then
CommissionAmount = 3
Else
CommissionAmount = 4
End If

serr1 = SetObjectValue ("ccmmnpct", Str$(CommissionAmount))

See Also
GetObjectValue Function, SetBufferValue Statement
186 Customization Manager Reference Visual Basic for Applications

SetProp Statement
Sets the properties of objects at runtime.
Syntax
Call SetProp (ObjectName, PropertyName, PropertyValue)
Remarks
Allows the application to set property values at runtime. This function should not be
used to set default properties.
The SetProp statement uses the following arguments:

Argument Type Description

ObjectName String Name of object whose property you wish to change
PropertyName String Property you wish to change
PropertyValue Integer Value to change property to
The following valid values for the PropertyName argument are defined as symbolic
constants in the VBTools_VBA module:

Symbolic Constant Valid Datatype Valid Data Values

PROP_BLANKERR (required) Integer TRUE / FALSE
PROP_CAPTION String
PROP_CUSTLIST String
PROP_ENABLED Integer TRUE / FALSE
PROP_HEADING String
PROP_MASK String
PROP_MIN String
PROP_MAX String
PROP_TABSTOP Integer TRUE / FALSE
PROP_VISIBLE Integer TRUE / FALSE
 Solomon API Function Calls 187

Example
'Enable push button
Call SetProp("OpenButton", PROP_ENABLED, True)

'Disable push button

Call SetProp("OpenButton", PROP_ENABLED, False)

'Make an object invisible

Call SetProp("cname", PROP_VISIBLE, False)

'Example uses a password dialog for setting a field invisible at runtime

Dim PassWord$

PassWord = PasswordBox$("Enter the Password Override","Message")

' Get password (case sensitive)
If Trim$(PassWord) = "SYSADMIN" Then
MsgBox(PassWord)
Call SetProp("clastchkdate", PROP_VISIBLE, True)
End If

See Also
MSetProp Statement, SetDefaults Function
188 Customization Manager Reference Visual Basic for Applications

SetStatusBarText Statement
Display text in the Application Status Bar.
Syntax
Call SetStatusBarText (StatusBarText, ToolTip)
Remarks
This function will allow the customization to set the text of the toolbar. The first
parameter holds the text to be displayed in the toolbar, the second holds the text to be
displayed in the tooltip for the left pane of the toolbar. If an empty string ("") is
specified for the second parameter, the text (first parameter) will be used for the
tooltip.
Example
This example displays the account description in the application status bar in Journal
Entry (01.010).
Sub cacct_Chk(chkstrg$, retval%)

Dim SqlStr as String

Dim xDescr as String
Dim xRetVal as Integer

' Get Account information.

SqlStr = "Select * from account where acct = " & chkstrg
xRetVal = SqlFetch1(xCursor, SqlStr, bAccount, Len(bAccount))
Call SetStatusBarText( bAccount.Descr, "")
End Sub
 Solomon API Function Calls 189

SFetch Functions
Used to retrieve a composite record from the database based on some pre-defined SQL
statement or stored procedure.
Syntax
RetVal = SFetch1(Cursor, bTable1, bTable1Length)
RetVal = SFetch4(Cursor, bTable1, bTable1Length, bTable2, bTable2Length,
bTable3, bTable3Length, bTable4, bTable4Length)
RetVal = SFetch8(Cursor, bTable1, bTable1Length, bTable2, bTable2Length,
bTable3, bTable3Length, bTable4, bTable4Length, bTable5, bTable5Length, bTable6,
bTable6Length, bTable7, bTable7Length, bTable8, bTable8Length)
Remarks
In order to fetch information from the server it must first know what tables, records and
fields are being queried from a particular cursor. Consequently the cursor must first be
initialized with either an SQL statement or stored procedure via the use of the Sql
statement or the SqlFetch1, SqlFetch4 or SqlFetch8 functions. Once the database
view has been established these functions will retrieve the next sequential record in the
view consistent with the Order By clause of the SQL statement used to initialize the
view. After the last record in the view has been returned all subsequent calls to
SFetch1, SFetch4 and SFetch8 will return NOTFOUND.
SFetch1 is designed for SQL statements returning data from a single table. For more
advanced SQL statements having one or more table joins either SFetch4 or SFetch8
can be used.
The SFetch1 function uses the following arguments (SFetch4 and SFetch8
respectively have four and eight table structures and corresponding lengths. PNULL
should be passed for unused table structure parameters as well as a corresponding
length of zero such as PNULL, 0)

Argument Type Description

RetVal Integer 0 if a record is successfully fetched. NOTFOUND is
returned if no additional records exist in the current
view.
Cursor Integer SQL database cursor.
bTable1 User-defined Table structure corresponding to the primary table in the
datatype SQL statement.
bTable1Length Integer Size of first table structure. For example,
LenB(bTable1). Note: In Solomon, it is critical to use
LenB() instead of Len() for all non-null “table length”
parameters.
190 Customization Manager Reference Visual Basic for Applications

Note: SGroupFetch1, SGroupFetch4 or SGroupFetch8 must be used if the SQL

statement used to initialize the cursor contained one or more of the following
components:
• Group aggregate functions (such as Count and Sum)
• DISTINCT keyword
• GROUP BY clause
• HAVING clause
• Subqueries
Example
Example links Inventory table to existing screen for lookup and navigation only.
(general) declarations:
'$include: "inventor.dh"

Form1_Load
Call VBA_SetAddr(c1, "bInventory", bInventory, Len(bInventory))
Call SqlCursor(c1, NOLEVEL)

Dim SqlStmt$

SqlStmt = "Select * from Inventory Where ClassID = 'BOX'Order By ClassID"

Call Sql(c1, SqlStmt)

serr1 = Sfetch1(c1, bInventory, Len(bInventory))
While serr1 <> NOTFOUND
'Check LastCost
If bInventory.LastCost > 0 Then
'Last Cost is positive
End If
serr1 = Sfetch1(c1, bInventory, Len(bInventory))
Wend

See Also
Sql Statement, SqlFetch Functions
 Solomon API Function Calls 191

SGroupFetch Functions
Used to retrieve a composite record from the database based on some pre-defined SQL
statement or stored procedure containing one or more group aggregate functions and/or
clauses.
Syntax
RetVal = SGroupFetch1(Cursor, bTable1, bTable1Length)
RetVal = SGroupFetch4(Cursor, bTable1, bTable1Length, bTable2, bTable2Length,
bTable3, bTable3Length, bTable4, bTable4Length)
RetVal = SGroupFetch8(Cursor, bTable1, bTable1Length, bTable2, bTable2Length,
bTable3, bTable3Length, bTable4, bTable4Length, bTable5, bTable5Length, bTable6,
bTable6Length, bTable7, bTable7Length, bTable8, bTable8Length)
Remarks
In order to fetch information from the server it must first know what tables, records and
fields are being queried from a particular cursor. Consequently the cursor must first be
initialized with either an SQL statement or stored procedure via the use of the Sql
statement. SGroupFetch1, SGroupFetch4 or SGroupFetch8 are only designed for
cases where the SQL statement used to initialize the cursor contains one or more of the
following:
• Group aggregate functions (such as Count and Sum)
• DISTINCT keyword
• GROUP BY clause
• HAVING clause
• Subqueries
The logically equivalent SFetch1, SFetch4 and SFetch8 functions should be used if
the SQL statement does not contain any of the above referenced items.
Once the database view has been established these functions will retrieve the next
sequential record or data value in the view consistent with the Order By or Group By
clause of the SQL statement used to initialize the view. After the last record or data
value in the view has been returned all subsequent calls to SGroupFetch1,
SGroupFetch4 and SGroupFetch8 will return NOTFOUND.
SGroupFetch1 is designed for SQL statements returning data from a single table. For
more advanced SQL statements having one or more table joins either SGroupFetch4
or SGroupFetch8 can be used.
192 Customization Manager Reference Visual Basic for Applications

The SGroupFetch1 function uses the following arguments (SGroupFetch4 and

SGroupFetch8 respectively have four and eight table structures and corresponding
lengths. PNULL should be passed for unused table structure parameters as well as a
corresponding length of zero such as PNULL, 0)

Argument Type Description

RetVal Integer 0 if a record or data value is successfully fetched.
NOTFOUND is returned if no additional records exist in
the current view.
Cursor Integer SQL database cursor.
bTable1 User-defined Table structure corresponding to the primary table or
datatype data value in the SQL statement.
bTable1Length Integer Size of first table structure or data value. For example,
LenB(bTable1) or Len(DoubleVariable). Note: In
Solomon, it is critical to use LenB() instead of Len() for
all non-null “table length” parameters.

Note: The type and size of the data returned can vary when the SQL statement contains
one or more group aggregates. For the COUNT group aggregate, the data will always
be returned as a 4-byte integer (i.e., Long VB datatype). The MIN and MAX group
aggregates always return the same data type and length as the field on which the
aggregate is based. The SUM and AVG group aggregates always return 8-byte floating
point values (i.e., Double VB datatype).
 Solomon API Function Calls 193

Example
Example retrieves the last voucher date for current vendor and selects a count of all
documents less than the last voucher date.
Dim SqlStr$
Dim CountDoc As Long
Dim DateComp As Sdate

DateComp.Val = GetObjectValue("clastvodate")

SqlStr = "Select Count(*) from APDoc Where DocDate < " + Dparm(DateComp)

Call Sql(c1, SqlStr)

serr1 = sgroupfetch1(c1, CountDoc, Len(CountDoc))

Print "Number of Documents: " + str$(CountDoc)

Second Example
Dim QtyOnHand#, TotCost#, SqlStmt$, ItemID$, MessStr$

SqlStmt = "Select Sum(QtyOnHand), Sum(TotCost) from ItemSite Where

ItemSite.InvtId = @parm1 Order By ItemSite.InvtId"

ItemId = GetObjectValue("cinvtid")
Call Sql(c1, SqlStmt)
Call SqlSubst(c1, "parm1", ItemID)
Call SqlExec(c1)
serr1 = sgroupfetch4(c1, QtyOnHand, Len(QtyOnHand), TotCost,
Len(TotCost), "", 0, "", 0)
MessStr = "Qty On Hand " + Str$(QtyOnHand) + "Total Cost "+ Str$(TotCost)

Call MessBox( MessStr, MB_OK, "Message")

See Also
SFetch Functions, Sql Statement
194 Customization Manager Reference Visual Basic for Applications

SInsert Statements
Insert one record into each specified table within an existing database view.
Syntax
Call SInsert1(Cursor, TablesInsertingInto, bTable1, bTable1Length)
Call SInsert4(Cursor, TablesInsertingInto, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length)
Call SInsert8(Cursor, TablesInsertingInto, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length, bTable5,
bTable5Length, bTable6, bTable6Length, bTable7, bTable7Length, bTable8,
bTable8Length)
Remarks
New records can be programmatically inserted directly into an existing database table
via the use of the SInsert1, SInsert4 and SInsert8 statements. In order to insert
information into the database, the server must first know what tables are being
referenced by a particular cursor. Consequently the cursor must first be initialized with
either an SQL statement or stored procedure via the use of the Sql statement or the
SqlFetch1, SqlFetch4 or SqlFetch8 functions. Once the database view has been
established these functions will insert one new record into each table referenced in the
TablesInsertingInto argument using data from corresponding table structure arguments.
SInsert1 is designed for SQL statements referencing a single table. In this case the
TablesInsertingInto is always the name of the single table actually referenced. For
more advanced SQL statements having one or more table joins either SInsert4 or
SInsert8 can be used. The referencing of more than one table does not automatically
force the insertion of a record into every table in the view any time SInsert4 or
SInsert8 is used on the corresponding cursor. A single record will only be inserted into
each table explicitly specified in the TablesInsertingInto argument so long as each
table name so specified is also referenced in the SQL statement which was used to
initialize the current view. Thus, for example, if TableA and TableB are the only two
tables referenced in the SQL statement used to initialize the current view then a value
of TableXYZ would be invalid for the TablesInsertingInto argument.
 Solomon API Function Calls 195

The SInsert1 function uses the following arguments (SInsert4 and SInsert8
respectively have four and eight table structures and corresponding lengths. PNULL
should be passed for unused table structure parameters as well as a corresponding
length of zero such as PNULL, 0)

Argument Type Description

Cursor Integer SQL database cursor.
TablesInsertingInto String Name of each table, in the specified cursor’s view,
into which a new record is to be inserted. Multiple
table names should be separated by commas.
bTable1 User-defined Table structure corresponding to the primary table
datatype in the SQL statement. Data in this structure will be
inserted into its corresponding database table if the
name of the said database table is explicitly
specified in the TablesInsertingInto argument.
bTable1Length Integer Size of first table structure. For example,
LenB(bTable1). Note: In Solomon, it is critical to
use LenB() instead of Len() for all non-null “table
length” parameters.

Example
Example attached to OnUpdate event of the Solomon screen:
If Level = 0 Then
If Found_Cust = "Y" then
Call supdate1(c1, "XCustAddlInfo",
bXCustAddlInfo,Len(bXCustAddlInfo))
Else
Call sinsert1(c1,"XCustAddlInfo",
bXCustAddlInfo,Len(bXCustAddlInfo))
End If
End If
Example 2

Insert new entry into Customer and ARHist tables

Call Sinsert4(c1, "*.*", bCustomer, Len(bCustomer),
bARHist, Len(bARHist), "", 0, "", 0)

See Also
Sql Statement, SqlFetch Functions
196 Customization Manager Reference Visual Basic for Applications

SParm Function
Convert a string into an SQL parameter string.
Syntax
SQLParmStr = SParm(StrToConvert)
Remarks
The SParm function uses the following arguments:

Argument Type Description

SQLParmStr String StrToConvert converted into an SQL parameter string
StrToConvert String String value to convert
Example
These examples assume the following SQL statement was used to create a stored
procedure called Employee_EmpId.
Select * from Employee where EmpId LIKE @parm1 order by EmpId
This code snippet illustrates how to use the Employee_EmpId stored procedure to fetch
the employee record for employee #000581.
SqlStr = "Employee_EmpId" + SParm("000581")
Employee_Fetch = SqlFetch1(CSR_Employee, SqlStr, bEmployee, ↵
LenB(bEmployee))
This code snippet illustrates how to use the Employee_EmpId stored procedure to fetch
all employee records by using a wildcard value for the EmpId parameter.
SqlStr = "Employee_EmpId" + SParm(SQLWILDSTRING)
Employee_Fetch = SqlFetch1(CSR_Employee, SqlStr, bEmployee, ↵
LenB(bEmployee))
While ( Employee_Fetch = 0)
Employee_Fetch = SFetch1( CSR_Employee, bEmployee, LenB(bEmployee))
Wend
This code snippet illustrates how to use the Employee_EmpId stored procedure to fetch
all employee records beginning and ending with zero by using a combination of string
literals and single character wildcard values for the EmpId parameter.
SQLParmStr = "0" + SQLWILDCHAR + SQLWILDCHAR + SQLWILDCHAR + ↵
SQLWILDCHAR + "0"
SqlStr = "Employee_EmpId" + SParm(SQLParmStr)
Employee_Fetch = SqlFetch1(CSR_Employee, SqlStr,
bEmployee, LenB(bEmployee))

While ( Employee_Fetch = 0)
Employee_Fetch = SFetch1( CSR_Employee, bEmployee, LenB(bEmployee))
Wend

See Also
DParm Function, FParm Function, IParm Function
 Solomon API Function Calls 197

Sql Statement
Initialize a new database view.
Syntax
Call Sql(Cursor, SqlStr)
Remarks
Takes the specified SQL text, compiles it, and then executes it. If fetch operations are
required then one of the SFetch functions must be called. If the SQL statement is
performing an Update Set, Delete From or Insert Into operation, no subsequent fetch
operations are required. If the SQL statement references one or more parameters, the
SqlSubst and SqlExec functions must also be called.
The Sql statement uses the following arguments:

Argument Type Description

Cursor Integer SQL database cursor.
SqlStr String SQL statement or stored procedure to be used in initializing
a new database view. If a stored procedure is used then all
parameters must be sequentially appended in order of
occurrence within the original Create Procedure statement
using calls to SqlSubst.

Example
Dim SqlStr As String

'Set AP Documents which are marked as current to non-current

SqlStr = "Update APDoc Set Current = 'False' where APDoc.DocBal = 0
and PerEnt <=" + sparm(NextPerNbr) + " and Current =
'True'"
Call Sql(C_APClose, Trim$(SqlStr))

'Process posted AP batches

SqlStrg = "Select * from Batch Where Module = 'AP' and Status = 'P'
Order By BatNbr"
Call Sql(CSR_Batch, SqlStrg)

serr1 = SFetch1(c1, bBatch, LenB(bBatch))

While serr1 = 0
'Process the batch
....
'Get the next batch
serr1 = SFetch1(CSR_Batch, bBatch, LenB(bBatch))
Wend

See Also
SFetch Functions, SqlExec Statement, SqlSubst Statement
198 Customization Manager Reference Visual Basic for Applications

SqlCursor Statement
Allocate a new database cursor.
Syntax
Call SqlCursor(Cursor, Flags)
Remarks
All read/write communication between an application and the database must occur
through a database cursor. A cursor is basically a database resource used to track low
level information required to implement SQL database read/write operations. For
example, a cursor tracks the SQL statement used to initialize the current view, what
individual fields were selected, the current record within the view as well as other more
detailed information.
Each level within a screen must have a corresponding cursor allocated within the
Form_Load event of Form1 to facilitate database read/write activity at that level.
Additionally, many of the SQL API calls within Solomon Tools for Visual Basic, such
as Sql, SFetch1, SqlFetch1 and SUpdate1 require a database cursor as one of their
arguments.
Each application can allocate a maximum of 36 cursors. Cursors no longer used by the
application can optionally be freed via the use of the SqlFree statement. All cursors are
automatically released by the system when the application terminates execution (i.e.,
when ScreenExit is called).
The SqlCursor statement uses the following arguments:

Argument Type Description

Cursor Integer Variable to be initialized with a resource handle for an
SQL database cursor.
Flags Integer One or more special flags notating what and/or how the
cursor will be used. At a minimum the Flags parameter
must contain one of the LEVEL0 through LEVEL9 or
NOLEVEL symbolic constants defined in the
VBTools_VBA module. Cursors not explicitly associated
with a particular level number should be allocated using the
NOLEVEL flag.
 Solomon API Function Calls 199

The following symbolic constants can optionally be passed as Flags (by adding them
to the required LEVEL0 through LEVEL9 or NOLEVEL symbolic constants):
• SqlList — Read/write operations performed on the cursor will automatically be
buffered to improve performance. If an application updates even one record on a
buffered cursor, it must update all records read with that cursor within the same
database transaction. Failure to comply with this requirement will result in a sparse
update error.
• SqlSystemDb — All database operations will be directed to the system database
as opposed to the application database.
Example
'Example declares a dynamic cursor in Form1_Load
'because it will be used elsewhere in the application

'NoLevel indicates no updating on this cursor,

'only lookups will be performed

Call SqlCursor(c1, NoLevel)

'NoLevel + SQLList indicates a buffered cursor

Call SqlCursor(c2, NoLevel + SqlList)

'Example declares a static cursor in Chk event. Note

'that a previous SqlCursor call was not made for c3:

Dim SqlStmt$
Dim CountResult As Long
SqlStmt = "Select Count(*) from Customer"
Call Sql(c3, SqlStmt)
serr1 = SgroupFetch1(c3, CountResult, Len(CountResult))
Call MessBox("Count is: " + Str$(CountResult), MB_OK, "Message")

See Also
SFetch Functions, SInsert Statements, Sql Statement, SqlFetch Functions, SqlFree
Statement, SUpdate Statements
200 Customization Manager Reference Visual Basic for Applications

SqlCursorEx
Allocate a new database cursor.
Syntax
Call SqlCursorEx(Cursor, Flags, CursorName, ReferencedTableNames,
UpdateTableNames)
Remarks
All read/write communication between an application and the database must occur
through a database cursor. A cursor is basically a database resource used to track low
level information required to implement SQL database read/write operations. For
example, a cursor tracks the SQL statement used to initialize the current view, what
individual fields were selected, the current record within the view as well as other more
detailed information.
Each level within a screen must have a corresponding cursor allocated within the
Form_Load event of Form1 to facilitate database read/write activity at that level.
Additionally, many of the SQL API calls within Solomon Tools for Visual Basic, such
as Sql, SFetch1, SqlFetch1 and SUpdate1 require a database cursor as one of their
arguments. If the cursor handle passed to one of these SQL API calls has not been
previously allocated then it will automatically be allocated during the call. However it
is important to be aware of the fact that all cursors not explicitly allocated, via an
SqlCursorEx call, are automatically allocated as read-only cursors.
Each application can allocate a maximum of 36 cursors. Cursors no longer needed by
the application can optionally be freed via the use of the SqlFree statement. All cursors
are automatically released by the system when the application terminates execution
(i.e., when ScreenExit is called).
 Solomon API Function Calls 201

The SqlCursorEx statement uses the following arguments:

Argument Type Description

Cursor Integer Variable to be initialized with a resource handle
for an SQL database cursor.
Flags Integer One or more optimization flags notating what
and/or how the cursor will be used. At a
minimum the Flags parameter must contain one
of the LEVEL0 through LEVEL9 or
NOLEVEL symbolic constants defined in the
VBTools_VBA module. Cursors not explicitly
associated with a particular level number
should be allocated using the NOLEVEL flag.
CursorName String Alias name associated with the cursor. This
value is used solely to enhance the readability
of diagnostic messages.
ReferencedTableNames String Comma delimited list of table names that will
be referenced by the cursor. This list should be
thought of as being applicable so long as the
cursor remains allocated.
UpdateTableNames String Comma delimited list of all tables which may
be updated by the cursor. The principle usage of
this list is to facilitate performance
optimizations related to tables in the cursor’s
view that will never be updated. If no table
names are specified then by default it will be
assumed that all of the referenced tables will be
updated at some point. Any table name
appearing in UpdateTableNames must also be
specified in ReferencedTableNames. This list
of table names should not be confused with the
table names passed to any of the SInsert,
SUpdate or SDelete statements. The names
passed to those statements identify the actual
tables updated in a particular database operation
– which may be a subset of the
UpdateTableNames argument.
202 Customization Manager Reference Visual Basic for Applications

Note: The following optimization flags are implemented as symbolic constants in the
VBTools_VBA module. They can optionally be passed via the Flags argument by
adding them to the required LEVEL0 through LEVEL9 or NOLEVEL symbolic
constant:
• SqlFastReadOnly – Similar to SqlReadOnly, the cursor will be used exclusively
for read operations. On the SQL Server platform, all database operations occurring
on an SqlFastReadOnly cursor will be serviced directly from SQL Server’s faster
low-level API. Please refer to the note below for more information regarding the
practical implications of utilizing SQL Server’s low level API. Cursors with this
flag should not be used to access tables which have received insert, update or
delete operations from a different cursor in the same database transaction.
• SqlList – Read/write operations performed on the cursor will automatically be
buffered to improve performance. If an application updates even one record on a
buffered cursor, it must update all records read with that cursor within the same
database transaction. Failure to comply with this requirement will result in a sparse
update error. In the SQL Server environment, all database operations are buffered
where possible – regardless of whether the SqlList flag has been specified. Refer
to the SqlNoList flag for more information.
• SqlLock – Every composite record retrieved with this type of cursor will be
locked. This flag effectively avoids the overhead of explicitly locking every record
that is fetched from the database within a transaction. SqlLock is primarily
designed for usage in process-like scenarios where it is known in advance that
every record accessed by the cursor needs to be updated. If the application will
ever be waiting for user-input while the cursor still has a current record then the
cursor should probably not be allocated with the SqlLock flag. This is due to the
simple fact that the current record would be locked while waiting for the user to
respond – thus potentially causing contention across the system. Records retrieved
on SqlLock cursors will remain locked until the next record is retrieved. For this
reason, the application should always continue to fetch records until a
NOTFOUND is returned – thereby unlocking the last record which was actually
retrieved. It is strongly recommended that applications only implement the usage
of SqlLock to facilitate optimum performance – as opposed to using it to
implement their own multi-user contention management scheme (i.e., “process
XYZ must be running because such and such a record is locked”). This flag is only
supported on the SQL Server platform.
• SqlNoList – This flag forces the buffering of read/write operations to be
suppressed. In the SQL Server environment all database operations are buffered by
default, where possible, regardless of whether or not the SqlList flag has been
specified. Consequently on the SQL Server platform, buffering must be explicitly
suppressed if for some reason the application does not want a particular cursor to
be buffered. In some cases this default buffering is automatically suppressed due to
low level restrictions.
 Solomon API Function Calls 203

• SqlNoSelect – This flag indicates that the cursor will be used with any SQL
statement except Select statements. The most common usage of this type of cursor
will be to process Update and Delete SQL statements. On the SQL Server
platform, all database operations occurring on an SqlNoSelect cursor will be
serviced directly from SQL Server’s faster low-level API. Please refer to the note
below for more information regarding the practical implications of utilizing SQL
Server’s low level API.
• SqlReadOnly – The cursor will be used exclusively for read operations. The
cursor will not be used for record inserts, updates or deletions.
• SqlSingleRow – This flag is to be used with cursors which will never process
more than one composite record after each Select statement. This flag is primarily
designed to facilitate optimization on the SQL Server platform. On the SQL Server
platform, all database operations occurring on an SqlSingleRow cursor will be
serviced directly from SQL Server’s faster low-level API. Please refer to the note
below for more information regarding the practical implications of utilizing SQL
Server’s low level API. SFetch calls on cursors of this type should not be
separated from the associated Sql call by any other database operations. The
simplest method to satisfy this requirement is via the usage of the SqlFetch
function.
• SqlSystemDb – All database operations will be directed to the system database as
opposed to the application database.

Note: Regarding the optimization flags which invoke usage of SQL Server’s low-level
API (SqlFastReadOnly, SqlNoSelect and SqlSingleRow): On the SQL Server platform,
all database operations occurring on a cursor optimized with one of these flags will
bypass SQL Server’s standard cursor API. Instead, database operations will be serviced
directly from SQL Server’s low level API. The advantage here is that the low level API
is faster. However when using the low level API the cursor can encounter contention
with other cursors in the same application (which is not the case when all operations
are serviced by SQL Server’s cursor API). SQL statements processed via this type of
cursor must include all of the fields for every table referenced in the statement. For
example, partial record Select statements are not supported on this type of cursor.
204 Customization Manager Reference Visual Basic for Applications

SqlErr Function
Obtain the return value for the SQL operation last performed.
Syntax
RetVal = SqlErr()
Remarks
This function can be used after any SQL call that is declared as a statement (as opposed
to a function), in order to obtain the return value. For example, the call SInsert1 is
declared as a subroutine and does not return a value to the application. In most cases,
the application does not need to check the return from this call, since by default SWIM
traps all return codes except 0 and the NOTFOUND symbolic constant. However in
special cases where the SqlErrException statement is used to give the application
more control over error handling, the application will need to obtain the return code
and this function is used for that purpose.
The SqlErr function returns one of the following integer global constants declared in
the VBTools_VBA module:

Return Value Description

DUPLICATE The record last updated or inserted caused a duplicate error as defined
by one or more unique indexes on the relevant table

Example
This example illustrates how to insert a uniquely numbered Batch record into the
database. The example assumes that a database transaction is already active when the
illustrated procedure is called. SqlErrException and SqlErr are used to detect
duplicate batch number error without causing Swim to abort the transaction. The
sample procedure receives two parameters:
• BatchStruct – A Batch record which is to be saved to the database, having all
relevant fields ALREADY initialized EXCEPT the batch number itself.
• AutoNbr_SqlStr – The name of an “auto number” stored procedure which will
fetch AutoBat and LastBatNbr fields (in that order) from one of the setup records.
Sub BATCH_AUTONBR_INSERT (BatchStruct As Batch, ByVal AutoNbr_SqlStr As
↵ String)
Dim AutoNbrFetch As Integer

'Allocate cursor resources

Call SqlCursor(CSR_AutoNbr, NOLEVEL)
Call SqlCursor(CSR_Batch_AutoNbr_Insert, NOLEVEL)

'Setup cursor with stored procedure so it will be able to

'execute an SInsert1()
Call Sql(CSR_Batch_AutoNbr_Insert, "Batch_Module_BatNbr" + ↵
sparm("") + sparm(""))
 Solomon API Function Calls 205

'Fetch the necessary fields for auto batch numbering from ↵

the Setup
'record specified by AutoNbr_SqlStr
AutoNbrFetch = SqlFetch1(CSR_AutoNbr, ↵
AutoNbr_SqlStr, AutoNbr,
LenB(AutoNbr))

'Turn ON exception error checking for DUPLICATE error ↵

condition so
'Swim will not go into abort mode if a duplicate batch ↵
number happens
'to already exist.
Call SqlErrException(EXCEPTION_ON, DUPLICATE)

Do
'Increment AutoNbr.LastNbrUsed to next ↵
sequential value
'(within the size of batch numbers actually being ↵
used).
Call incrstrg(AutoNbr.LastNbrUsed, 6, 1)

BatchStruct.BatNbr = AutoNbr.LastNbrUsed

'Attempt to insert batch record with new batch ↵

number
Call SInsert1(CSR_Batch_AutoNbr_Insert, ↵
"Batch", BatchStruct,
LenB(BatchStruct))

Loop While (SqlErr() = DUPLICATE)

'Write changes to Setup record back to database

Call SUpdate1(CSR_AutoNbr, "*.*", AutoNbr, ↵
LenB(AutoNbr))

'Turn OFF exception error checking for DUPLICATE.

Call SqlErrException(EXCEPTION_OFF, DUPLICATE)

'Free up cursor resources

Call SqlFree(CSR_AutoNbr)
Call SqlFree(CSR_Batch_AutoNbr_Insert)

End Sub

See Also
SqlErrException Statement
206 Customization Manager Reference Visual Basic for Applications

SqlErrException Statement
Toggle automatic error handling logic for one or more database error codes.
Syntax
Call SqlErrException (ToggleFlag, ErrorToExcept)
Remarks
By default, all error codes except 0 and NOTFOUND are trapped within SWIM and
are not returned to the application. To alter this behavior an application can use the
SqlErrException function to tell SWIM not to trap certain errors and instead return
them to the application. This statement is used in conjunction with the SqlErr
function.
Note that the application is responsible for toggling the exception back off once it is no
longer needed.
The SqlErrException statement uses the following arguments:

Argument Type Description

ToggleFlag Integer Used to tell SWIM to turn the error exception on or off.
The EXCEPTION_ON and EXCEPTION_OFF
symbolic constants are defined in the VBTools_VBA
module as the only two valid values.
ErrorToExcept Integer Error code to be returned to the application rather than
handled automatically by the system. If only duplicate
record errors should be excepted from automatic error
handling logic then the DUPLICATE symbolic constant
defined in the VBTools_VBA module should be passed.
The RETURN_ALL_ERRVALS symbolic constant
defined in the VBTools_VBA module should be passed
if all errors are to be returned to the application.
 Solomon API Function Calls 207

Example
Dim DupFlag%
DupFlag = DUPLICATE

'Tell the Solomon to return DUPLICATE status messages

Call SqlErrException(EXCEPTION_ON, DUPLICATE)
'Loop until a non duplicate number is assigned
Do Until DupFlag <> DUPLICATE

'Increment last reference number

Call IncrStrg(bARSetup.LastRefNbr, Len(bARSetup.LastRefNbr, 1)

'Attempt to insert the new refnbr

bARDoc.RefNbr = bARSetup.LastRefNbr
bRefNbr.RefNbr = bARDoc.RefNbr
Call sinsert1(c8, "RefNbr", bRefNbr, Len(bRefNbr))

'Check the return value for duplicates

DupFlag = SqlErr() 'DUPLICATE or 0

Loop 'Until exited with a good Refnbr

See Also
SqlErr Function
208 Customization Manager Reference Visual Basic for Applications

SqlExec Statement
Execute an inline SQL statement.
Syntax
Call SqlExec(Cursor)
Remarks
Execute a dynamic SQL statement on a cursor previously initialized with calls to the
Sql and SqlSubst statements (in that order).
The SqlExec statement uses the following arguments:

Argument Type Description

Cursor Integer SQL database cursor

Example
Dim VendorCount&, SqlStmt$

SqlStmt = "Select Count(*) from Vendor Where VendId Like @parm1"

Call Sql(c1, SqlStmt)

Call SqlSubst(c1, "parm1", "V001%")
Call SqlExec(c1)
serr1 = sgroupfetch1(c1, VendorCount, Len(VendorCount))

Call MessBox("Count is " + Str$(VendorCount), MB_OK, "Message")

See Also
Sql Statement, SqlSubst Statement
 Solomon API Function Calls 209

SqlFetch Functions
Used to initialize a new database view and immediately retrieve a composite record.
Syntax
RetVal = SqlFetch1(Cursor, SqlStr, bTable1, bTable1Length)
RetVal = SqlFetch4(Cursor, SqlStr, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length)
RetVal = SqlFetch8(Cursor, SqlStr, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length, bTable5,
bTable5Length, bTable6, bTable6Length, bTable7, bTable7Length, bTable8,
bTable8Length)
Remarks
In order to fetch information from the database, a database view must first be
initialized specifying what tables, fields and restriction criteria are to be utilized.
Secondly an actual request for data from an existing view must be sent to the server.
Each of the SqlFetch1, SqlFetch4 and SqlFetch8 functions effectively perform both
of these operations in a single call which would otherwise require a combination of two
calls (i.e., Sql and SqlFetch1). In looping situations where a program needs to
sequentially read through multiple records in a view, these functions are convenient for
initializing the view and immediately fetching the first record. However they should
not be used to fetch subsequent records since the view is being re-established each time
SqlFetch1, SqlFetch4 or SqlFetch8 is called and therefore they will always only fetch
the first record in the view. In these cases, SFetch1, SFetch4 or SFetch8 can be used
to fetch subsequent records.
SqlFetch1 is designed for SQL statements returning data from a single table. For more
advanced SQL statements having one or more table joins either SqlFetch4 or
SqlFetch8 can be used.
The SqlFetch1 function uses the following arguments (SqlFetch4 and SqlFetch8
respectively have four and eight table structures and corresponding lengths. PNULL
should be passed for unused table structure parameters as well as a corresponding
length of zero such as PNULL, 0)
210 Customization Manager Reference Visual Basic for Applications

Argument Type Description

RetVal Integer 0 if a record is successfully fetched. NOTFOUND is
returned if no records matching the restriction criteria
exist in the newly established view.
Cursor Integer SQL database cursor.
SqlStr String SQL statement or stored procedure to be used in
initializing a new database view. If a stored procedure
is used then all parameters must be sequentially
appended in order of occurrence within the original
Create Procedure statement. These parameter values
must also be properly converted to SQL parameters via
usage of the SParm, IParm, FParm and DParm
functions – whichever is appropriate for the datatype
of each individual parameter.
bTable1 User-defined Table structure corresponding to the primary table in
datatype the SQL statement.
bTable1Length Integer Size of first table structure. For example,
LenB(bTable1). Note: In Solomon, it is critical to use
LenB() instead of Len() for all of the non-null “table
length” parameters.
SGroupFetch1, SGroupFetch4 or SGroupFetch8 must be used if the SQL statement
used to initialize the cursor contains one or more of the following components:
• Group aggregate functions (such as Count and Sum)
• DISTINCT keyword
• GROUP BY clause
• HAVING clause
• Subqueries
 Solomon API Function Calls 211

Example 1
Example from CustId chk event which fetches new table info.
SUB ccustid_Chk(chkstrg$, retval%)
serr1 = sqlfetch1(c1, "XCustAddlInfo_CustId" + sparm(chkstrg),↵
bXCustAddlInfo, Len(bXCustAddlInfo))
If serr1 = NOTFOUND Then
serr1 = SetDefaults("NewInfo", "")
bXCustAddlInfo.CustId = chkstrg
Found_Cust = "N"
Else
Found_Cust = "Y"
End If
Call DispFields("NewInfo","")
END SUB

Example 2
'Select Unreleased APDocs and Join Vendor Table
Dim SqlStmt$
SqlStmt$ = "Select * from APDoc, Vendor Where APDoc.VendId =↵
Vendor.VendId(+) And APDoc.Rlsed = 'False'
Order by APDoc.RefNbr

serr1 = sqlfetch4(c1, SqlStmt, bAPDoc, Len(bAPDoc),

bVendor,Len(bVendor),↵
"", 0, "", 0)

See Also
DParm Function, FParm Function, IParm Function, SGroupFetch Functions, SParm
Function, Sql Statement, SqlFetch Functions
212 Customization Manager Reference Visual Basic for Applications

SqlFree Statement
Free a database cursor no longer needed by the application.
Syntax
Call SqlFree(Cursor)
Remarks
The SqlFree statement is used to deallocate cursors previously allocated with the
SqlCursor statement. The usage is this statement is entirely optional. It is normally
used when a cursor is no longer needed by an application whose total number of
cursors is very close to the maximum limit. All cursors are automatically released by
the system when the application terminates execution (i.e., when ScreenExit is called).
The SqlFree statement uses the following arguments:

Argument Type Description

Cursor Integer Resource handle for the SQL database cursor to be
deallocated

Example
Example uses SqlFree in a general sub-routine.:
Get APSetup Information set global variable NextRefNbr

Sub GetSetupInfo()
Call SqlCursor(c1)
Call SqlFetch1(c1, "APSetup_All", bAPSetup, Len(bAPSetup))
NextRefNbr = bAPSetup.LastRefNbr
Call SqlFree(c1)
End Sub

See Also
SqlCursor Statement
 Solomon API Function Calls 213

SqlSubst Statement
Specify a data value for a substitution parameter in an inline SQL statement previously
executed via the Sql function.
Syntax
Call SqlSubst(Cursor, ParmName, ParmValue)
Remarks
SqlSubst allows you to specify values for one or more substitution variables in an
inline SQL statement that is executed via the Sql statement. It is not to be used for a
stored procedure.
This statement must be called after the Sql statement and before the SqlExec
statement. It can be called any number of times before SqlExec is called, depending on
how may parameter values there are to substitute into the SQL statement.
The SqlSubst statement uses the following arguments:

Argument Type Description

Cursor Integer SQL database cursor previously initialized with an inline
SQL statement containing one or more parameters
ParmName String Name of the SQL statement parameter (not including the
“@” character)
ParmValue String Data value to be used for the designated parameter

Example
Dim VendorCount&, SqlStmt$

SqlStmt = "Select Count(*) from Vendor Where VendId Like @parm1"

Call Sql(c1, SqlStmt)

Call SqlSubst(c1, "parm1", "V001%")
Call SqlExec(c1)
serr1 = sgroupfetch1(c1, VendorCount, Len(VendorCount))

Call MessBox ( "Count is " + Str$(VendorCount), MB_OK, "Message")

See Also
Sql Statement, SqlExec Statement
214 Customization Manager Reference Visual Basic for Applications

StrToDate Statement
Convert a date value from a string in MMDDYYYY format into an SQL date format.
Syntax
Call StrToDate(DateStringToConvert, SQLDate)
The StrToDate statement uses the following arguments:

Argument Type Description

DateStringToConvert String String in MMDDYYYY format
SQLDate SDate user-defined Converted date value
datatype (declared in the
VBTools_VBA module)

Example
Dim NewDate As Sdate
Call StrToDate("10311994", NewDate)

See Also
DateToIntlStr Function, DateToStr Function, DateToStrSep Function, IntlStrToDate
Statement
 Solomon API Function Calls 215

StrToTime Statement
Convert a time value from a string in HHMMSShh format into an SQL time format.
Syntax
Call StrToTime(TimeStringToConvert, SQLTime)
The StrToTime statement uses the following arguments:

Argument Type Description

TimeStringToConvert String String in HHMMSShh format
SQLTime STime user-defined Converted time value
datatype (declared in the
VBTools_VBA module)

Example
Dim TimeVal As Stime
Dim TimeStr As String
TimeStr = "12010000"
Call StrToTime(TimeStr, TimeVal)

See Also
TimeToStr Function
216 Customization Manager Reference Visual Basic for Applications

SUpdate Statements
Update one record of each specified table within an existing database view.
Syntax
Call SUpdate1(Cursor, TablesUpdating, bTable1, bTable1Length)
Call SUpdate4(Cursor, TablesUpdating, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length)
Call SUpdate8(Cursor, TablesUpdating, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length, bTable5,
bTable5Length, bTable6, bTable6Length, bTable7, bTable7Length, bTable8,
bTable8Length)
Remarks
Existing records can be programmatically updated directly via the use of the
SUpdate1, SUpdate4 and SUpdate8 statements. However, before a record can be
updated it must first be fetched using one of the SFetch1, SFetch4 and SFetch8 or
SqlFetch1, SqlFetch4 and SqlFetch8 functions. The fetch operation which precedes
the update must be made using the same database view/cursor on which the update will
occur. For example, if the fetch occurs on Cursor A then the update must also occur on
Cursor A as opposed to some unrelated Cursor XYZ. Nevertheless, once the database
view has been established these functions will update the current record in the view for
each table referenced in the TablesUpdating argument using data from corresponding
table structure arguments.
SUpdate1 is designed for SQL statements referencing a single table. In this case the
TablesUpdating is always the name of the single table actually referenced. For more
advanced SQL statements having one or more table joins either SUpdate4 or
SUpdate8 can be used. The referencing of more than one table does not automatically
force the current record of every table within the view to be updated any time
SUpdate4 or SUpdate8 is used on the corresponding cursor. The current record of a
particular table in the view will only be updated if its corresponding table name is
explicitly specified in the TablesUpdating argument so long as each table name so
specified is also referenced in the SQL statement which was used to initialize the
current view. Thus, for example, if TableA and TableB are the only two tables
referenced in the SQL statement used to initialize the current view then a value of
TableXYZ would be invalid for the TablesUpdating argument.
The SUpdate1 function uses the following arguments (SUpdate4 and SUpdate8
respectively have four and eight table structures and corresponding lengths. PNULL
should be passed for unused table structure parameters as well as a corresponding
length of zero such as PNULL, 0)
 Solomon API Function Calls 217

Argument Type Description

Cursor Integer SQL database cursor.
TablesUpdating String Name of each table, in the specified cursor’s view,
whose current record is to be updated. Multiple
table names should be separated by commas.
bTable1 User-defined Table structure corresponding to the primary table
datatype in the SQL statement. Data from this structure will
be used to overwrite existing data in the
corresponding current record if the name of the said
database table is explicitly specified in the
TablesUpdating argument.
bTable1Length Integer Size of first table structure. For example,
LenB(bTable1). Note: In Solomon, it is critical to
use LenB() instead of Len() for all non-null “table
length” parameters.

Note: Database updates occurring on cursors allocated by SqlCursorEx using the

SqlList flag (i.e., buffered cursors) have two unique requirements. First, the application
must update all records it reads, using a buffered cursor, if it updates even one record.
Failure to comply with this requirement will result in a sparse update error. Secondly,
the application should not modify the view on the cursor after updates have occurred
until after the transaction has ended. For example if the application is reading and
updating Table A records on buffered Cursor A then Cursor A should not be used for
any other purpose until after the database transaction has ended. If no updates are made
using Cursor A then this requirement does not apply.

Example
This simple example updates all GLTran records in General Ledger Batch 000001 as
being released. Within Solomon the release of GLTran records actually entails
additional application logic which is not directly relevant to the illustration of the
SUpdate4 statement and therefore it has been removed from this example.
This example assumes the GLTran_Module_BatNbr_LineNbr stored procedure was
originally created with the following SQL statement:
Select * from GLTran
where Module = @parm1
and BatNbr = @parm2
and LineNbr between @parm3beg and @parm3end
order by Module, BatNbr, LineNbr
218 Customization Manager Reference Visual Basic for Applications

Since the above SQL statement only retrieves data from a single table (for example, the
GLTran table) SUpdate1 would be adequate. However in this example, SUpdate4 is
actually used to illustrate how to pass "", 0 for unused table structure arguments.
Dim CSR_GLTran As Integer
Dim SqlStr As String
Dim GLTranFetch As Integer

'Allocate a database cursor. A buffered cursor (i.e., SqlList) can be

'used to speed up performance since ALL GLTran records read within the
'database transaction will also be updated.
Call SqlCursor( CSR_GLTran, NOLEVEL + SqlList)

'Begin a database transaction since all updates to the database must ↵

occur
'within a transaction.
Call TranBeg(True)

'Initialize SqlStr with a stored procedure and associated parameters which ↵

'can be used to fetch all GLTran records in GL Batch 000001.
SqlStr = "GLTran_Module_BatNbr_LineNbr" + sparm("GL") + ↵
sparm("000001") + iparm(INTMIN) + iparm(INTMAX)

'Initialize cursor with a SQL stored procedure and immediately fetch

'first record
GLTranFetch = SqlFetch4(CSR_GLTran, SqlStr, bGLTran, ↵
Len(bGLTran), "", 0, "", 0, "", 0)

While (GLTranFetch = 0)

'Release current transaction

bGLTran.Posted = "U"
bGLTran.Rlsed = LTRUE

'Update the record last fetched on CSR_GLTran (i.e., the ↵

current
'GLTran record) with the modified contents of bGLTran
Call SUpdate4(CSR_GLTran, "GLTran", bGLTran, ↵
Len(bGLTran), "", 0, "", 0, "", 0)

'Load next transaction record

GLTranFetch = SFetch4(CSR_GLTran, bGLTran, Len(bGLTran),↵
"", 0,"", 0, "", 0)

Wend

'End the database transaction to commit all updates to the ↵

database.
Call TranEnd

See Also
SFetch Functions, SqlCursor Statement, SqlFetch Functions
 Solomon API Function Calls 219

TestLevelChg Function
Return the current update status flag for a specific level.
Syntax
Status = TestLevelChg(LevelNbr)
Remarks
Each update level, as defined by the Levels property of the SAFUpdate control, has a
corresponding level status flag that is automatically maintained by the system. The
purpose of the level status flag is to facilitate the optimization of database updates
performed in response to Parent toolbar buttons. In general, these flags allow the
system to only perform database updates for update levels which have in fact changed.
If no information has changed then no information needs to be saved.
As previously mentioned, these update flags are automatically maintained by the
system. When an existing record is loaded the flag is set to NOTCHANGED. If any
non-key field is subsequently modified then the level status flag for the corresponding
level is set to UPDATED. When a new record is being entered, the level status flag is
set to INSERTED.
The TestLevelChg function allows the application to access the current value of this
flag for a specific level. The current level status flag can be overridden by the
application using the SetLevelChg statement.
The TestLevelChg function uses the following arguments:

Argument Type Description

Status Integer Current value of the level status flag for the designated
LevelNbr. The following possible values are defined as
symbolic constants in the VBTools_VBA module:
INSERTED, UPDATED, NOTCHANGED.
LevelNbr Integer Level whose status flag is to be returned.
220 Customization Manager Reference Visual Basic for Applications

Example
The Payroll module’s Earnings Type Maintenance (02.270.00) window contains a
button to automatically populate the grid with all Deductions. This amounts to
inserting records into the grid (i.e., into its underlying memory array) under program
control. Since the data is not entered via the user interface by the user, the system
needs to be notified that information at the grid level (i.e., LEVEL1 in this case) has
been programmatically updated and therefore needs to be saved. However, such
notification only needs to occur if the system is not already aware that data has
changed.
'If any records were inserted into the memory array then we need to make
'sure that the level status for the detail level is something other than
'NOTCHANGED so the system will know that something needs to be saved.
If (AnyRecsInserted = True) Then

If (TestLevelChg(LEVEL1) = NOTCHANGED) Then

Call SetLevelChg(LEVEL1, UPDATED)
End If

End If

See Also
SetLevelChg Statement
 Solomon API Function Calls 221

TimeToStr Function
Convert a time value from SQL time format into a string in HHMMSShh format.
Syntax
TimeString = TimeToStr(TimeToConvert)
Remarks
The TimeToStr function uses the following arguments:

Argument Type Description

TimeString String TimeToConvert converted to a string in
HHMMSShh format
TimeToConvert STime user-defined Time value to be converted
datatype (declared in the
VBTools_VBA module)

Example
'If any records were inserted into the memory array then we need to make
'sure that the level status for the detail level is something other than
'NOTCHANGED so the system will know that something needs to be saved.
If (AnyRecsInserted = True) Then

If (TestLevelChg(LEVEL1) = NOTCHANGED) Then

Call SetLevelChg(LEVEL1, UPDATED)
End If

End If

See Also
StrToTime Statement
222 Customization Manager Reference Visual Basic for Applications

TranAbort Statement
Abort the current database transaction.
Syntax
Call TranAbort
Remarks
The TranAbort statement allows the application to abort a database transaction which
was initiated using the TranBeg statement.
Calling TranAbort directly is not, however, the recommended method to abort
transactions. If the transaction to be aborted is an update operation for an application
screen then the recommended method is for the application to set RetVal in the
OnUpdate event of the SAFUpdate control to either an error message number or the
ErrNoMess symbolic constant defined in the VBTools_VBA module. This will also
have the effect of aborting the current database transaction.
Example
Call TranBeg(True)
....
'Perform Processing
.....
'Determine any error condition that would cause the transaction to abort
If ErrorCondition Then
Call TranAbort
End If

'Perform the Insert Or Update

Sinsert...
OR
Supdate...
OR
Sdelete...

'End Transaction/Commit Work to Database

Call TranEnd

See Also
TranBeg Statement, TranEnd Statement, OnUpdate Event
 Solomon API Function Calls 223

TranBeg Statement
Begin a database transaction.
Syntax
Call TranBeg(IsAbortable)
Remarks
All updates to the database must occur within a database transaction. All updates to the
database will not actually be committed to the database until the transaction is ended
via the TranEnd statement.
If any errors occur during the database transaction then the system will automatically
abort (i.e., roll back) all updates occurring during the transaction as opposed to
committing them to the database. If the transaction is an update operation for an
application screen then it will be aborted when the application to sets RetVal in the
OnUpdate event of the SAFUpdate control to either an error message number or the
ErrNoMess symbolic constant defined in the VBTools_VBA module.
The TranBeg statement uses the following argument:

Argument Type Description

IsAbortable Integer True if the transaction is abortable (which is virtually always
the case). Otherwise False. Errors occurring during non-
abortable transactions will cause the application to
immediately terminate.

Example
Call TranBeg(True)
'Perform Processing
'Determine any error condition that would cause the transaction to abort
If ErrorCondition Then
Call TranAbort
End If

'Perform the Insert Or Update

Sinsert...
OR
Supdate...
OR
Sdelete

'End Transaction/Commit Work to Database

Call TranEnd

See Also
TranEnd Statement, TranStatus Function, OnUpdate Event
224 Customization Manager Reference Visual Basic for Applications

TranEnd Statement
End the current database transaction and commit all updates to the database.
Syntax
Call TranEnd
Remarks
If any errors occurred during the database transaction then the system will
automatically abort (i.e., roll back) all updates which occurred during the transaction as
opposed to committing them to the database. If the transaction is an update operation
for an application screen then it will be aborted when the application to sets RetVal in
the OnUpdate event of the SAFUpdate control to either an error message number or
the ErrNoMess symbolic constant defined in the VBTools_VBA module.
Example
Call TranBeg(True)
'Perform Processing
'Determine any error condition that would cause the transaction to abort
If ErrorCondition Then
Call TranAbort
End If

'Perform the Insert Or Update

Sinsert...
OR
Supdate...
OR
Sdelete...

'End Transaction/Commit Work to Database

Call TranEnd

See Also
TranBeg Statement, TranStatus Function, OnUpdate Event
 Solomon API Function Calls 225

TranStatus Function
Returns the status of the current or last database transaction.
Syntax
IntegerErrVal = TranStatus()
Remarks
If a database transaction is currently not open then the status of the last performed
database transaction is returned.
A return value of zero indicates that the transaction was successful.
A non-zero return value indicates a fatal error occurred during the transaction and
therefore it will be, or was, aborted. In this case, the actual return value itself is the
number of the error message describing the nature of the problem.
Example
Call TranBeg(True)
'Perform Processing
'Determine any error condition that would cause the transaction to abort
If ErrorCondition Then
Call TranAbort
End If

'Perform the Insert Or Update

Sinsert...
OR
Supdate...
OR
Sdelete...

'Test for Database condition

If TranStatus() <> 0 Then
Call TranAbort
End If

'End Transaction/Commit Work to Database

Call TranEnd

See Also
TranBeg Statement, TranEnd Statement, OnUpdate Event
226 Customization Manager Reference Visual Basic for Applications

VBA_MExtend Function
Extend the grid of an application so that another table’s structure can be added to the
grid.
Syntax
RetVal = VBA_MExtend(MemHandle, bTable1, bTable1Length)
Remarks
Although this function is provided to extend the number of tables that are accessed by
the grid control, the VBA application is responsible for all database I/O to the new
table. This includes using memory array functions to cycle through the grid at save
time to determine if the contents of the structure of the underlying table has changed
and perform the appropriate action.
The VBA_MExtend function uses the following arguments:

Argument Type Description

RetVal Integer Non-zero if the operation is successful. Otherwise it is
zero.
MemHandle Integer Unique handle to a previously opened memory array.
bTable1 User-defined Supplementary table structure to be added to the
datatype existing memory array.
bTable1Length Integer Size of supplementary table structure. For example,
LenB(bTable1).

Example
Following example extends the grid for the chart of accounts screen. It adds the
definition of a new table, Xaccount, to the account grid.
Global GridHandle As Integer

'Calls in Form1_Load event:

Call VBA_SetAddr("bXAccount", bXAccount, nXAccount, LenB(bXAccount))
Call SQLCursor(c1, NOLEVEL)

'Calls in Form1_Display
GridHandle = GetGridHandle("Spread1")
serr1 = VBA_MExtend(GridHandle, bXAccount, LenB(bXAccount))

See Also
GetGridHandle Function, VBA_SetAddr Statement
 Solomon API Function Calls 227

VBA_MOpen Functions
Open a new memory array and return a corresponding unique memory array number.
Syntax
MemHandle = VBA_MOpen(DelRetToSystem, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length)
MemHandle = VBA_MOpen8(DelRetToSystem, bTable1, bTable1Length, bTable2,
bTable2Length, bTable3, bTable3Length, bTable4, bTable4Length, bTable5,
bTable5Length, bTable6, bTable6Length, bTable7, bTable7Length, bTable8,
bTable8Length)
Remarks
A memory array must be opened before insert, update, delete or memory array
navigation operations can be performed on it. The memory array handle returned by
VBA_MOpen and VBA_MOpen8 are used when performing these types of
operations on memory arrays.
VBA_MOpen allocates memory for up to four table structures whereas
VMA_MOpen8 can handle up to eight different table structures for each memory
array record.
VBA_MOpen is only used to open memory arrays which are not associated with an
SAFGrid control. Memory arrays which correspond to grids are opened automatically.
The VBA_MOpen function uses the following arguments (VBA_MOpen8 has eight
table structures and corresponding lengths. PNULL should be passed for unused table
structure parameters as well as a corresponding length of zero such as PNULL, 0)

Argument Type Description

MemHandle Integer Unique handle to the newly created memory array. If a
new memory array was successfully opened this value
will be >= 0.
bTable1 User-defined First table structure of memory array.
datatype
bTable1Length Integer Size of first table structure. For example, LenB(bTable1).
Note: In Solomon, it is critical to use LenB() instead of
Len() for all non-null “table length” parameters.
bTable2 User-defined Second table structure of memory array. PNULL if the
datatype memory array only contains one table structure.
bTable2Length Integer Size of second table structure. Zero if the memory array
only contains one table structure.
bTable3 User-defined Third table structure of memory array. PNULL if the
datatype memory array contains less than three table structures.
bTable3Length Integer Size of third table structure. Zero if the memory array
contains less than three table structures.
228 Customization Manager Reference Visual Basic for Applications

Argument Type Description

bTable4 User-defined Fourth table structure of memory array. PNULL if the
datatype memory array contains less than four table structures.
bTable4Length Integer Size of fourth table structure. Zero if the memory array
contains less than four table structures.
The table structures passed to VBA_MOpen8 do not have to be actual database tables.
They can be either a simple data item, such as a double, or any user-defined data type
created with the VB Type statement.
Example
This example illustrates how to open a memory array and load the entire Solomon
Chart of Accounts into the newly created array.
Dim Mem_Account As Integer
Dim CSR_Account As Integer
Dim SqlStr As String
Dim Account_Fetch As Integer

'Open memory array to hold Chart of Accounts

Mem_Account = VBA_MOpen( TRUE, bAccount, Len(bAccount), PNULL, 0, PNULL, ↵
0, PNULL, 0)

'Allocate cursor
Call SqlCursor( CSR_Account, NOLEVEL)

'Initialize cursor with a SQL stored procedure and immediately fetch

'first record
SqlStr = "Select * from Account order by Acct"
Account_Fetch = SqlFetch1(CSR_Account, SqlStr, bAccount, LenB(bAccount))

'Read through all subsequent Account records, inserting each one

'into the memory array.
While( Account_Fetch = 0)

'Insert current Account record into the memory array

Call MInsert( Mem_Account)

'Fetch the next Account record

Account_Fetch = SFetch1(CSR_Account, bAccount, ↵
LenB(bAccount))

Wend

See Also
MClear Statement, MClose Statement, MDelete Function, MDisplay Statement, MFirst
Function, MInsert Statement, MKey Statement, MKeyFind Function, MLast Function,
MNext Function, MPrev Function, MUpdate Statement
 Solomon API Function Calls 229

VBA_SetAddr Statement
Associate a table name together with a VB variable and an optional screen level
number.
Syntax
Call VBA_SetAddr(TableNameStr, bTableName, nTableName, bTableNameLength)
Remarks
The VBA_SetAddr statement facilitates proper runtime binding between a VB data
variable and relevant data entry controls – including controls created using the
Customization Manager.
Although SWIM has access to extensive information about any particular data entry
control, one vital piece of information cannot be determined merely by looking at the
control itself. In particular, SWIM needs to know where the data for the control is
stored in memory. Since the data is actually stored in an underlying VB variable,
SWIM has no means of directly determining where that VB variable is stored in
memory. The VBA_SetAddr statement is used by the application to resolve this
problem.
To facilitate the explanation of the linkage between the VBA_SetAddr statement and
corresponding data entry controls, consider the following user-defined datatype and a
corresponding VBA_SetAddr call for the Account database table:
Type Account

Acct As String * 10
Active As Integer
ConsolAcct As String * 10
CuryId As String * 4
Descr As String * 30
NoteID As Long
RatioGrp As String * 2
SummPost As String * 1
Type As String * 2
User1 As String * 30
User2 As String * 30
User3 As Double
User4 As Double

End Type

Global bVBVarAccount As Account, nVBVarAccount As Account

Call VBA_SetAddr( "bAccount", bVBVarAccount, nVBVarAccount,↵

LenB(bVBVarAccount))
230 Customization Manager Reference Visual Basic for Applications

The VBA_SetAddr call itself associates the value of the TableNameStr argument
together with the memory location of the first byte of the VB variable passed via the
bTableName argument. If the relevant table is a database table, SWIM can access
detailed information relating to each individual field contained therein using the SQL
data dictionary. For example, SWIM can determine the name, data type, maximum size
as well as the relative placement (i.e., byte offset) of each individual field within the
table. After the VBA_SetAddr call in the above example, SWIM would know that the
first byte of bVBVarAccount is at a particular location in memory, hereafter referred to
as location M, and furthermore that the first byte of bVBVarAccount.Acct is offset
zero bytes from location M as well as the fact that Acct is ten bytes long. Similarly, it
would also know that the first byte of bVBVarAccount.Active is offset ten bytes from
location M, and is two bytes long since it is an integer. Since the value of “bAccount”
is passed as the TableNameStr argument it is the string literal associated with memory
location M. Any time SWIM encounters “bAccount.<SomeFieldName>” in a
FieldName property it will have all of this detailed information readily available so it
can access the corresponding data at the appropriate memory location. The same
concept applies when SWIM encounters “bAccount.<SomeFieldName>” in any of the
DBNav, Default, PV or Trigger properties.
As previously mentioned, the detailed information acquired by SWIM as a result of the
VBA_SetAddr call can be directly linked to the FieldName property of data entry
controls. The FieldName property contains a Struct.FieldName value along with other
more detailed information such as field offset value, declare type and length. Once they
have been fully initialized, these values facilitate the linkage between the control and
the associated memory location where the data value of the control is stored. In the vast
majority of cases the detailed field information is initialized automatically by SWIM in
using information acquired via a corresponding VBA_SetAddr call and the SQL data
dictionary. Usage of an unbound control is the only case where the developer must fill
in the detailed field information manually since it will not exist in the SQL data
dictionary.
The Struct.FieldName portion of the FieldName property must always be populated
with a string value in the “bTableName.FieldName” format. Using the above example,
a control for the Acct field would have a value of “bAccount.Acct” for the
Struct.FieldName portion of its FieldName property. Similarly the Active control
would have a value of “bAccount.Active” for the Struct.FieldName portion of its
FieldName property.
The first portion of this Struct.FieldName string, “bAccount” in our example, is used to
link the control with a particular VBA_SetAddr call that had the same value for its
TableNameStr argument. Once that initial linkage is made the exact memory location
can be determined automatically by correlating the last portion of the Struct.FieldName
string, “Acct” or “Active” in our example, with the detailed field information acquired
as a result of the relevant VBA_SetAddr call.
In general, the VBA_SetAddr call facilitates the linkage of a
“bTableName.FieldName” type of string literal with a precise location in memory for
the corresponding data value.
 Solomon API Function Calls 231

The VBA_SetAddr statement uses the following arguments:

Argument Type Description

TableNameStr String Table name string literal which can subsequently be used
by SWIM to link the table name portion of a
“bTableName.FieldName” type of string literal with a
precise location in memory. By convention this value
should begin with a “b” such as “bAccount” for the
Account table. Note: This value does not have to
correlate to a database table. In these cases, the system
will assume it refers to an unbound data buffer. All
references to unbound “table names” in DBNav, Default,
FieldName and PV properties must be accompanied with
manually entered detailed field information since the
system will be unable to access this information from the
SQL data dictionary.
bTableName User- VB variable whose datatype corresponds to the table
defined referred to in the TableNameStr argument. For example
datatype if “bAccount” is passed then the VB variable passed via
this argument must be a user-defined datatype whose
structure precisely corresponds to the Account table in
the database.
nTableName User- VB variable whose datatype corresponds to the table
defined referred to in the TableNameStr argument. If
datatype TableNameStr does not correlate to a database table then
PNULL must be passed as the value for this argument.
This value will be properly initialized with null values as
long as the relevant table is a database table. Any
structure of the relevant datatype can then be easily
blanked out using the bTableName = nTableName
methodology.
bTableNameLength Integer Length (i.e., size) of the entire bTableName user-defined
type such as Len(bTableName). Note: In Customization
code, it is critical to use LenB() instead of Len().
The VBA_SetAddr statement is closely associated with the SAFUpdate control. The
SAFUpdate control is used to define logical groups of information on the screen via its
Levels property as well as expose key database and/or navigational events to the
application such as OnCancel, NewLevel, OnDelete, OnFinish, and OnUpdate. All
applications have an SAFUpdate control on Form1. Properties of the SAFUpdate
control are Customizable (D), Index (D), Left, Levels (D), Name (D), Tag, and Top.
(“D” means the property can be modified at design time only, not runtime.) Also refer
to ApplGetReturnParms and SqlCursor Statement.
232 Customization Manager Reference Visual Basic for Applications

Example
External .dh file
This declares a structure that matches the Solomon Country table. Note the exact size
of the fields must be declared and the buffer and NULL buffer structures are declared
globally:
Type Country
CountryId As String * 3
Descr As String * 30
End Type
Global bCountry As Country, nCountry As Country

In Customization events:
(general) declarations

For BSL customization, add the following line:

'$include: "cu\country.dh"

For VB customizations, add the .dh file to the VBA Project.

Sub Form1_Load
Call VBA_Setaddr("bcountry", bcountry, ncountry, LenB(bcountry))
Call Sqlcursor(c1, NOLEVEL)
End Sub

See Also
FieldName Property
 Glossary 233

Glossary
BSL
The acronym for the Basic Script Language (BSL).
BSL.DH
A text format file in the Solomon Program directory which contains global and
function declarations for all of the Solomon Kernel functions that can be used in Basic
Script Language.
call by reference
Arguments passed by reference to a procedure can be modified by the procedure.
Procedures written in Basic are defined to receive their arguments by reference. If you
call such a procedure and pass it a variable, and if the procedure modifies its
corresponding formal parameter, it will modify the variable. Passing an expression by
reference is legal in Basic; if the called procedure modifies its corresponding
parameter, a temporary value will be modified, with no apparent effect on the caller.
call by value
When an argument is passed by value to a procedure, the called procedure receives a
copy of the argument. If the called procedure modifies its corresponding formal
parameter, it will have no effect on the caller. Procedures written in other languages
such as C can receive their arguments by value.
comment
A comment is text that documents a program. Comments have no effect on the
program (except for metacommands). In Basic, a comment begins with a single quote,
and continues to the end of the line. If the first character in a comment is a dollar sign
($), the comment is interpreted as a metacommand. Lines beginning with the keyword
Rem are also interpreted as comments.
control ID
This can be either a text string, in which case it is the name of the control, or it can be a
numeric ID. Note that control IDs are case-sensitive and do not include the dot that
appears before the ID. Numeric IDs depend on the order in which dialog controls are
defined. You can find the numeric ID using the DlgControlID function.
dialog control
An item in a dialog box, such as a list box, combo box, or command button.
234 Customization Manager Reference Visual Basic for Applications

function
A procedure that returns a value. In Basic, the return value is specified by assigning a
value to the name of the function, as if the function were a variable.
IntelliSense
IntelliSense® helps create error-free script statements by presenting you with the names
of methods and properties as soon as you’ve typed in the name of an object or API.
label
A label identifies a position in the program at which to continue execution, usually as a
result of executing a GoTo statement. To be recognized as a label, a name must begin
in the first column, and must be immediately followed by a colon (:). Reserved words
are not valid labels.
metacommand
A metacommand is a command that gives the compiler instructions on how to build the
program. In Basic, metacommands are specified in comments that begin with a dollar
sign ($).
name
A Basic name must start with a letter (A through Z). The remaining part of a name can
also contain numeric digits (0 through 9) or an underscore character (_). A name
cannot be more than 40 characters in length. Type characters are not considered part of
a name.
Object Model
A specification of the objects intrinsic to a given system, including a description of the
object characteristics (attributes) and a description of the static and dynamic
relationships that exist between objects. In the case of Solomon applications the Object
Model is a collection of objects that collectively represent a screen.
precedence order
The system VBA uses to determine which operators in an expression to evaluate first,
second, and so on. Operators with a higher precedence are evaluated before those with
lower precedence. Operators with equal precedence are evaluated from left to right.
The default precedence order (from high to low) is: numeric, string, comparison,
logical.
procedure
A series of VBA statements and functions executed as a unit. Both subprograms (Sub)
and functions (Function) are called procedures.
subprogram
A procedure that does not return a value.
 Glossary 235

type character
A special character used as a suffix to a name of a function, variable, or constant. The
character defines the data type of the variable or function. The characters are: $
(Dynamic String), % (Integer), & (Long integer), ! (Single precision floating point), #
(Double precision floating point), @ (Currency exact fixed point).
vartype
The internal tag used to identify the type of value currently assigned to a variant. One
of the following: 0 (Empty), 1 (Null), 2 (Integer), 3 (Long), 4 (Single), 5 (Double), 6
(Currency), 7 (Date), 8 (String), 9 (Object).
VBA – Visual Basic for Applications
Visual Basic for Applications is the premier development technology for rapidly
customizing packaged applications and integrating them with existing data and
systems. VBA offers a sophisticated set of programming tools based on Microsoft
Visual Basic, the world’s most popular rapid application development system, that
developers can use to harness the power of packaged applications. VBA enables
companies to buy off-the-shelf software and customize it to meet their specific
business rather than building from scratch. This saves time and money, reduces risks,
leverages programmer skills, and delivers precisely what users need
VBA IDE – Integrated Development Environment
Includes many of the elements familiar to developers using Visual Basic, including a
Project Window, a Properties Window and debugging tools.
236 Customization Manager Reference Visual Basic for Applications
 Index 237

Index
Close selection 92
Code Editor 5
* Complete Word 5
composite record 189, 191, 202, 203
*.* 178 constant 17
control page 11
@ control templates 11
Controls toolbox 11
cursor 157, 189, 191, 194, 198, 200, 203
@ 169
custom control 11, 12
Customization Manager 3, 15, 17
A
abort transaction 222, 223, 224 D
ActiveX 3
data field 22
ActiveX Controls 12
database 114, 157, 176
Add-In Manager 13
database operations 202, 203
aggregate function 21, 191
database update 217
AliasConstant 63, 68
DataTips 5
ApplGetParms 63, 69
DateCheck 63, 77
ApplGetParmValue 63, 70
DateCmp 63, 78
ApplGetReturnParms 72
DateMinusDate 63, 79
Application Program Interface (API) 16
DatePlusDays 63, 80
ApplSetFocus 63, 73
DatePlusMonthSetDay 63, 81
ApplSetParmValue 63, 74
DateToInstlStr 82
DateToIntlStr 63
B DateToStr 63, 83
DateToStrSep 63, 84
batch level 18 DBNavFetch 63, 85
binding 229 debugging tools 8
BlankErr 27 Default 16, 42
bound object 185 default data value 42
buffered cursor 199, 202, 217 Default event 42, 181
buffering 202 Default property 42, 181
Button clicks 37 Delete 17, 37
DELETE 23
DELETE operation 43
C Delete selection 93
Delete SQL statement 203
Call Stack 8 Deleted record 53
CallChks 63, 76 design time property 73
Cancel selection 91 detail level 18
character field 22 DIM 17
Chk 16, 38 disable control 181
Click 16, 41 disabled object 185
Click event 45 DispFields 63, 87
238 Customization Manager Reference Visual Basic for Applications

DispForm 63, 89
Display 16, 50 G
Double 17
Dparm 63 General_Declarations 17
DParm 90 general-use routines 37
generic code 139
GetBufferValue 64, 108
E GetDelGridHandle 64, 109
GetGridHandle 64, 110
Edit_Cancel 63, 91 GetObjectValue 64, 111
Edit_Close 63, 92 GetProp 64, 112
Edit_Delete 63, 93 GetSqlType 64, 114
Edit_Finish 63, 94 GetSysDate 64, 115
Edit_First 63, 95 GetSysTime 64, 116
Edit_Last 63, 96 GLOBAL 17
Edit_New 63, 97 Grid linechk 37
Edit_Next 64, 98 Grid linegotfocus 37
Edit_Prev 64, 100 GUI 15
Edit_Save 64, 101
embedded screen object 15
empty string 188 H
Enabled 28
ErrNoMess symbolic constant 222, 223, 224 Heading 30
error checking 125, 181 Hide 16, 51
error codes 206 HideForm 64, 117
Error condition 102, 104, 105, 106, 107
error trapping 206
event 16, 37 I
IDE 1, 3, 4
F Immediate window 8
IncrStrg 64, 118
fatal VB error 73 INSERT 23
Field chk 37 Insert operation 61
Field default 37 INSERTED 183, 219
Field PV 37 Integer 17
FieldName 29 integrated form designer 10
FieldName property 230 IntelliSense 3, 5, 17
Finish selection 94 IntlStrToDate 119
finished 59 invisible object 185
First selection 95 IParm 64, 120
Form Display 37 Is_TI 64, 121
Form Hide 37
Form Load 37
FPAdd 64, 102 K
FParm 64, 103 key field 146, 148, 150, 152, 167
FPDiv 64, 104 key field value 146, 148, 150, 152, 166
FPMult 64, 105
FPRnd 64, 106
FPSub 64, 107
function 17
L
language, non-English 68
Last selection 96
 Index 239

Launch 64, 122 MKeyOffset 65, 152

level 18, 198, 200 MLast 65, 156
level status flag 183, 219 MLoad 65, 157
line status 163, 168 MNext 65, 159
LineChk 53 MPrev 65, 160
LineChkEvent 16 MRowCnt 65, 161
LineGotFocus 16, 55 MSet 65, 162
List Constants 5 MSetLineStatus 65, 163
List Properties/Methods 5 MSetProp 65, 165
Load 16, 52 MSetRowNum 65, 166
load data 157 Msort 65
Locals window 8 MSort 167
locked record 202 multi-user contention management 202
looping 209 MUpdate 65, 168

M N
macro level 45 NameAltDisplay 65, 169
margin indicator 6 named parameter section 70, 74
Mask 31 NEW 43
master table 61 new record 194
Max 32 New selection 97
MCallchks 64 Next selection 98
MCallChks 125 Normal level 38
MClear 64, 126 NOTCHANGED 183, 219
MClose 64, 127 null out 181
MDelete 64, 128 NULLDATE 78
MDisplay 64, 129
memory array 109, 110, 126, 127, 128, 129, 141,
144, 146, 148, 150, 152, 157 O
Mess 64, 131
mess statement call 18 object 15
message 18 Object Browser 9, 15
message function 18 Object Model 4
message number 18, 131, 135 object type 16
Messages.csv 131, 132, 135, 136 OLE Controls 12
Messbox 65 OnCancel 16, 37, 57
MessBox 134 OnDelete 16, 43
Messf 65, 135 OnFinish 16, 37, 59
MessResponse 65, 138 OnInsert 16, 37, 61
mFindControlName 139 OnUpdate 16, 37, 47
MFirst 65, 141 optimization flags 203
MGetLineStatus 65, 142 Option Explicit 17
MGetRowNum 65, 143
Microsoft Forms 10
Microsoft SQL Server 114 P
Min 33
parameter passing 70, 74, 122
MInsert 65, 144
parameter section 70
MKey 65, 146
password 14
MKeyFind 65, 148
PasteTemplate 66, 170
MKeyFld 65, 150
PeriodCheck 66, 171
240 Customization Manager Reference Visual Basic for Applications

PeriodMinusPeriod 66, 172 SetProp 66, 186

PeriodPlusPerNum 173 SetStatusBarText 66, 188
PNULL 189, 192, 195, 209, 216, 227 SFetch 66, 189
Previous selection 100 SGroupFetch 66, 191
procedure 50, 51, 52 SInsert 66, 194
Project Explorer 7 Solomon data control 87
properties 15 Solomon Kernel 17, 18
Properties window 7 Solomon.ini 74
property, check value 112 sort order 146, 148, 150, 152
PV 16, 45 Sparm 66
PVChkFetch 66, 174 SParm 196
sparse update error 199, 217
special structure 21
Q Sql 66, 197
SQL call 204
Quick Info 5 SQL data dictionary 230
SQL Select statement 157
R SQL Server API 202, 203
SQL syntax 23
SqlCursor 66, 198
read operations 202, 203
SqlCursorEx 66, 200
read/write operations, suppress 202
SqlErr 66, 204
record 132, 136
SqlErrException 66, 206
record number 166
SqlExec 66, 208
Relative Date window 176
SqlFetch 66, 209
Relative Period window 176
SqlFree 66, 212
report, Solomon 123
SqlSubst 66, 213
retrieve record 23
standard section name 70
return code 204
start application 74
return value 225
stored procedure 23, 157
reverse order 59
String 17
ROI application 123
StrToDate 66, 214
ROI, launch 124
StrToTime 66, 215
structure 21
S subroutine 17
substitution variable 213
SAFOption button 42 SUpdate 67, 216
SAVE operation 47 SWIM 229, 230
Save selection 101 Swimapi.dll 17
SaveTemplate 66, 176
screen event 1
Sdelete 66 T
SDelete 178
Tab Index property 139
SdeleteAll 66
TabIndex 34
SDeleteAll 179
table join 194, 209, 216
Select Case Level 18
target control 73
select statement 21
Template feature 170, 176
Select statement 203
TestLevelChg 67, 219
SetBufferValue 66, 180
TimeToStr 67, 221
SetDefaults 66, 181
toolbar text 188
SetLevelChg 66, 183
tooltip 188
SetObjectValue 66, 180, 185
 Index 241

TranAbort 67, 222

TranBeg 67, 223
TranEnd 47, 67, 224
TranStatus 67, 225
Trigger property 38

U
unbound control 230
Update 17
UPDATE 23
Update event 18
Update SQL statement 203
UPDATED 183, 219
user field 22

V
validate 38
variable 18
variable type 17
VB MsgBox statement 131, 134, 135
VBA 1, 3, 10
VBA code 18, 23, 37
VBA function 17
VBA modules directory 17
VBA project components 7
VBA routine 17
VBA_Mextend 67
VBA_MExtend 226
VBA_MOpen 67, 227
VBA_SetAddr 67, 229
VBTools_VBA module 17
view 179, 198, 200, 209, 216
Visible 35
Visual Basic Editor 4, 37

W
Watches window 8