sl70_enus_tvb_03

Chapter 3: Adding a New Table and a Detail Level

3-1

CHAPTER 3: ADDING A NEW TABLE AND A DETAIL LEVEL Objectives

The objectives are:

• Learn how to add a new table to the Microsoft Dynamics SL database.

• Create and execute index and stored procedure SQL scripts. • Learn what a “detail” level is and how it works. • Implement a “detail” level, using the SAFGrid control. • Know what a container object is and how it is used. • Know how to add data controls to a container object. • Learn how to test run your program. • Learn how to add code to the Linegotfocus event of a spreadsheet

control. • Review the checklist for adding a detail level to a program.

Introduction The second development project builds on the maintenance window created in the last course. The resulting project will be a time entry program in which a salesperson's time spent working for a customer can be recorded.

Microsoft Official Training Materials for Microsoft Dynamics ® Your use of this content is subject to your current services agreement

Tools for Visual Basic in Microsoft Dynamics® SL 7.0

3-2

Adding a New Table to the Dynamics SL Database Adding the Table

The Microsoft Dynamics SL database contains well over 700 tables. However, you might frequently find that there are no tables that hold the information to store. For example, in the project currently being worked on, you need a table to store Customer information, salesperson information, and a table to store information about the time a salesperson spent working for a Customer. There is already a CUSTOMER and SALESPERSON table in the Microsoft Dynamics SL database. However, it is necessary to create a completely new table to store the information about the time a salesperson spent working for a Customer.

The Microsoft Dynamics SL Tools for Visual Basic provide several utility programs that make the creation and management of new tables easier. Generate Schema (93.400.00) is a utility that creates DH and SDO files and Create Table scripts. It uses information that can be entered and maintained by two other programs, Record Maintenance (93.260.00) and Field Maintenance (93.250.00). These two programs are used in this lesson to define the required new table and the standard control types and properties for controls that access the fields in that table.

Once the table is defined, it needs to be created in the database. Whenever a new table is created, it is also necessary to create indexes, and at least one stored procedure is almost always required.

Here is a checklist of the steps that are most often used when adding a new table to the Microsoft Dynamics SL database. As with the steps for adding a normal level, these steps do not necessarily need to all be done at the same time or in the order described here. Establishing some consistent practices for performing these steps can greatly reduce development time in the long run.

1. Define new table using Record Maintenance (93.260.00). Define the name and description of the new table to be created.

2. Define new fields using Field Maintenance (93.250.00). Define the fields of the new table and define the default controls types and property settings for VB controls that access the fields.

3. Generate a SQL CREATE TABLE script file using Generate Schema (93.400.00). Create a CRT file that contains a SQL CREATE TABLE statement that can be used to create the new table in any Microsoft Dynamics SL database.

4. Execute the CRT SQL script file. Use Microsoft SQL Server Management Studio to run the CRT SQL script file created in the previous step. This creates the table in a database.



3-3

5. Create and execute a CRX SQL script file.

Create a SQL script file that will create a unique index on the new table. Use Microsoft SQL Server Management Studio to execute the script file.

6. Create and execute a CRP SQL script file. Create a SQL script file that will create a stored procedure. Use Microsoft SQL Server Management Studio to execute the script file. • The Procedure should be a select statement that selects

every field from the table. • Every field from the unique index of the table should be

included as a condition in the where clause. • At least one of the where clause conditions on one or more

of the index fields should be compared to a replacement parameter. • If a wildcard is passed to at least the last parameter, then

the statement should return every row in the table. • If actual values are passed, the statement should return

one and only one row. There should be an ordered by clause that matches an index of the table. Usually, it will match the unique index.

Define a New Table Using Record Maintenance

FIGURE 3.1



3-4

Tools for Visual Basic come with a utility program called Record Maintenance (93.260.00). This utility allows the developer to define the name of a table and a few other pieces of information such as a description. This utility does not actually create a table in the database. When adding new tables to the Microsoft Dynamics SL database, there is a naming convention suggested by Microsoft. Microsoft Dynamics SL never begins any of the standard product table names with an “X.” Therefore, if third party developers always create their tables beginning with an “X,” then they can be sure that future updates of the Microsoft Dynamics SL product will not cause a naming conflict. (Note that there is no formal convention to prevent multiple third party developers from creating tables with the same names.)

NOTE: Although the “X” is the only explicitly stated naming convention for tables, there are some implicit restrictions. These restrictions result from Microsoft Dynamics SL using the name assigned to tables as the names for variables in Tools for Visual Basic programs. Naming restrictions that apply to VB variables must be followed for Microsoft Dynamics SL tables. Some of the restrictions are: Table names should not contain spaces. Table names should not begin with numbers. Other than underscores, no special characters should be used in a table name.

There is one more restriction that results from the Microsoft Dynamics SL Kernel's implementation of its SetAddr function:

• Table names should not END in a number.

The reason for this restriction will be discussed later in this course.



3-5

Define New Fields Using Field Maintenance

FIGURE 3.2

Once a new table is defined in Record Maintenance (93.260.00), then the fields for that table must be defined. This utility actually allows the program to define two things:

• The data type and size of the fields. • The standard controls and properties of the controls that should be

used when creating a Tools for Visual Basic program that access the field, (This information is no longer used. It can be filled in but is not used.)

As with the table names, field names are used within Tools for Visual Basic programs as variable names. Therefore, field names must adhere to standard variable naming restrictions.

NOTE: When a Tools for Visual Basic program accesses a row from the database, a variable with the exact same structure as the row being selected must be defined and created when the program is written. This is true for all the standard Microsoft Dynamics SL programs as well as any programs written by third parties. Because Microsoft Dynamics SL almost always retrieves rows by performing “SELECT * FROM Table,” any changes to the structure of a table would cause rows from that table to no longer properly fit in the variables that were created to hold those rows.



3-6

What this means is that a change to the structure of a table without updating and recompiling all programs that access that table breaks every program that accesses that table.

Generate SQL Scripts Using Generate Schema

At this point, a complete description of the new table would be entered into the Microsoft Dynamics SL database. However, the table does not actually exist.

The next step is to use the information just entered into Record Maintenance (93.260.00) and Field Maintenance (93.250.00) to create Microsoft SQL script files that could be run on any database to create the new table. The Generate Schema (93.400.00) program is designed to do exactly that.

FIGURE 3.3

The Generate Schema (93.400.00) program creates three files:

• A CRT extension file, which contains the SQL CREATE TABLE statement required to create the table in a database

• A DH extension file, which contains a VB UDT declaration and two global declarations for variables of that type. This file will be used for customization manager if a developer wants to access this new custom table through a customization to a window.

• A VB extension file (SDO), which contains a VB Class declaration, two global declarations for variables for this new class and a public cursor declaration. This file is needed for the VB Tools application that is being created.



3-7

These three files are created by the same program, using the same information, at the same time. This ensures that, if the CRT file is used to create the table in the database, then the UDT and SDO will have the exact same structure as the table.

Execute the CRT SQL Script File

At this point, the new table still does not actually exist in the database. The Microsoft SQL script statements found in the CRT file just created must now be executed in the database. This could be done in one of two ways.

• A utility program called Database Update (DB.UPD.ATE) is supplied as part of the Microsoft Dynamics SL system. It is specifically design to execute these and other types of files. This program is primarily designed for use by Customers to install updates and enhancements to their Microsoft Dynamics SL installation.

• A program called Microsoft SQL Server Management Studio is supplied with Microsoft SQL Server. It is designed to allow a Database administrator (DBA) to execute any required SQL statements interactively.

Either method will work. However, as a developer you might find SQL Server Management Studio to be an invaluable tool for many purposes. Therefore, to gain some experience with this tool, use SQL Server Management Studio to execute the CRT SQL script file.

NOTE: In many versions of Microsoft Dynamics SL, the Kernel queries the database at the time the user first logs into a company to determine the names of all the tables in the database. By default, the Kernel then assumes that the list of table names it found at that time is the complete list, and it does not query the database for this information again until the program is shut down and a user logs in again at a later time.

This “feature” of the product almost never has any affect on the Customers, since they are never creating any new tables as part of their interactions with the product. However, this can be very significant to developers. If a programmer is already logged into Microsoft Dynamics SL and adds a new table to the database using SQL Server Management Studio (or any utility other than Database Update), the Microsoft Dynamics SL Kernel will not know that the table exists. Therefore, it is highly likely that the Kernel might present an error message indicating that the Microsoft Dynamics SL Kernel could not find the new table when the program is tested. A similar issue exists if the structure of a table changes after having run a Tools for VB program that referenced that table. Microsoft Dynamics SL must be shut down and restarted for the Microsoft Dynamics SL Kernel to be aware of the change.

The one exception to these scenarios is when the Database Update utility program is used to add or modify the table. The Microsoft Dynamics SL Kernel understands that when Database Update is used, changes to the database schema should be expected, and, therefore, it will take a fresh look at the list of tables. Subsequently, it is aware of the table that was added or modified.



3-8

NOTE: The SQL Server Management Studio program is a part of the Microsoft SQL Server product, not the Microsoft Dynamics SL or Microsoft Dynamics SL Tools for Visual Basic products. By default, an Icon for this program is installed only on the workstation or server that was used to install Microsoft SQL Server.

Since this is a utility that may be needed frequently, it is recommended to place an icon for this program somewhere on the workstation that is used for development. Microsoft SQL Server has been installed on each workstation for this class.

FIGURE 3.4



3-9

Once SQL Server Management Studio has been started, the CRT file created by Generate Schema (93.400.00) can then be loaded as a script file and executed.

FIGURE 3.5

The first statement is always a DROP TABLE statement. Given this fact, be very careful not to load and execute the wrong CRT files.

Create and Execute CRX and CRP Script Files Create and Execute a CRX SQL Script File

Any table in a properly designed relational database must have at least one unique index. In other words, there must be some field or group of fields for which no two rows in a table are allowed to have the same values.

The next step in adding a new table is to create and execute a Microsoft SQL Server script file that contains the SQL statements that will create a unique index on the new table.



3-10

Unlike the CRT file, the CRX file that contains these Microsoft SQL script statements is not automatically created by either the Microsoft Dynamics SL Tools for Visual Basic or Microsoft SQL Server. In normal development, it is the responsibility of the programmer to create these files. To reduce typing time and errors during the class, the CRX file has been created for you. The code in this script file could also be added to the bottom of the script file that creates the table to cut down on the number in script files delivered with the executable in the end.

FIGURE 3.6

In the project currently being created, rows in the new table cannot be uniquely identified by a single field. Lots of XBILLABLE rows can have the same Customer ID, and many of the XBILLABLE rows could appear on the same line of detail grid on the window. However, no two rows in this table could occupy the same line of the detail grid for the same Customer at the same time. Therefore, the unique index on this table is a segmented index made up of these two fields.

NOTE: The Microsoft Dynamics SL Kernel has been hard coded to assume that every table that it might be responsible for updating will have a unique index with a name that matches the following format: TableName0 Thus, the index name: Xbillable0 is being used here. If a table fails to supply a unique index with a name that matches this naming convention, the Kernel will generate an error if it is expected to perform updates on that table (the table is the primary table for a level in the window).

Create and Execute a CRP SQL Script File

Almost without exception, if the rows from a table are to be used within a Tools for Visual Basic program, a stored procedure will need to be created. The stored procedure also almost always needs to be able to return two different result sets:

• Retrieve all rows of interest • Retrieve only one row

Which of these two sets the procedure returns is determined by whether or not wildcards are passed as parameters to the stored procedure.



3-11

The stored procedure for the new table needs to be able to generate the first set when the user wants to navigate through rows, while it needs to generate the second set when the Microsoft Dynamics SL Kernel has to update individual rows that have been changed.

By reviewing the Tools for Visual Basic program that is being created, more details can be derived about exactly what the stored procedure needs to do in each of these conditions.

FIGURE 3.7

Retrieving ALL Rows of Interest

When the user navigates from one Customer to another, the Microsoft Dynamics SL Kernel needs to retrieve all XBILLABLE rows for the given Customer to display them in the grid.

FIGURE 3.8

This behavior could be achieved with a stored procedure like the one in the previous figure. However this stored procedure could be used for ONLY the first of the two required behaviors.



3-12

Retrieve Only One Row

When the user saves changes to XBILLABLES rows, the Microsoft Dynamics SL Kernel needs to retrieve each XBILLABLE row individually to lock it, check for multi-user contention problems, and update the row.

FIGURE 3.9

This behavior could be achieved with a stored procedure like the one in the previous figure. However, this stored procedure could be used for ONLY the second of the two required behaviors.

Retrieve ALL Rows if Interest OR Only One Row

FIGURE 3.10



3-13

Both required behaviors can be achieved using a single stored procedure if the stored procedure is properly constructed, like the one in the previous figure.

FIGURE 3.11

In Microsoft SQL, the between operator is inclusive. Therefore if the minimum and maximum values for the LineNbr field are passed in place of the parm2min and parm2max parameters, then the between condition of the where clause is evaluated as though it did not even exist. This results in the stored procedure returning every XBILLABLE row for the given Customer.

FIGURE 3.12



3-14

If the same value is passed to both parameters of a between operator, then the between operator will function just like an “equal to” operator. Since Custid and LineNbr are the unique index for the given table, using the stored procedure this way is guaranteed to return either an empty set or one and only one row.

FIGURE 3.13

In normal development, it is the responsibility of the programmer to design, create, and execute the Microsoft SQL script file that creates the stored procedure for a table. This can be done with the SQL Server Management Studio utility.

To reduce typing time during the class, a Microsoft SQL script file with the CRP extension has already been created for you.



3-15

Lab 3.1 - Define a New Table Scenario

Define New Table Using Record Maintenance (93.260.00)

Step by Step

1. Return to the Microsoft Dynamics SL Toolbar. 2. Choose the Administration wonder bar. 3. Click on Record Maintenance in the right pane. 4. When the Record Maintenance (93.260.00) program appears, left

double-click anywhere on the grid area to switch to “form view.” 5. On the Microsoft Dynamics SL Toolbar, click the New button. 6. In the Record Name field type (without quotes): “xBillable”. 7. In the Description field type (without quotes): “Salesperson Billable

Time”. 8. In the Module field select AR. 9. On the Microsoft Dynamics SL Toolbar, click the Save button. 10. On the Microsoft Dynamics SL Toolbar, click the Close button.

FIGURE 3.14



3-16

Lab 3.2 - Define New Fields Scenario

Define New Fields Using Field Maintenance (93.250.00)

Step by Step

1. Return to the Microsoft Dynamics SL Toolbar. 2. Choose the Administration wonder bar. 3. Click on Field Maintenance in the right pane. 4. In the Record Name field, type (without quotes): “xBillable.” 5. On the following seven pages is the information needed to define the

table columns. They are organized one field per page. Enter the information for each field. After completing one field, click the Finish button on the Microsoft Dynamics SL Toolbar to save the field you just entered, and start adding the next field.

Field Value Record Name Xbillable

Field Name Custid

Active True

Caption Customer ID

Heading Customer ID

Data Type Character

Data Length 15

Total Precision NA

Decimal Places NA

Array False

Array Size NA

Default Type NONE

Default From Record NA

Default From Field NA

Constant NA

Control Type Text box

Mask Type Uppercase Alphanumeric

Display Length 15

Visible True



3-17

Field Value Enabled True

Required True

Minimum Value NA

Maximum Value NA

Microsoft Dynamics SL II Name NA

PV-SQL NA

PV-Parms NA

Record Name Xbillable

Field Name Descr

Active True

Caption Description

Heading Description

Data Type Character

Data Length 60

Total Precision NA

Decimal Places NA

Array False

Array Size NA

Default Type NONE



Constant NA


Mask Type ASCII

Display Length 60

Visible True

Enabled True

Required False

Minimum Value NA

Maximum Value NA




3-18

Field Value PV-SQL NA

PV-Parms NA


Field Name LineNbr

Active True

Caption Line Nbr

Heading Line Nbr

Data Type Integer

Data Length 2

Total Precision NA

Decimal Places NA

Array False

Array Size NA

Default Type NONE



Constant NA


Mask Type NA

Display Length NA

Visible False

Enabled False

Required True

Minimum Value NA

Maximum Value NA


PV-SQL NA

PV-Parms NA


Field Name NoteID

Active True



3-19

Field Value Caption Note ID

Heading Note ID

Data Type Integer

Data Length 4

Total Precision NA

Decimal Places NA

Array False

Array Size NA

Default Type NONE



Constant NA


Mask Type NA

Display Length NA

Visible False

Enabled False

Required False

Minimum Value NA

Maximum Value NA


PV-SQL NA

PV-Parms NA


Field Name SlsperID

Active True

Caption Sales Person ID

Heading Sales Person ID

Data Type Character

Data Length 10

Total Precision NA



3-20

Field Value Decimal Places NA

Array False

Array Size NA

Default Type Record.Field

Default From Record CUSTOMER

Default From Field SLSPERID

Constant NA


Mask Type Uppercase Alphanumeric

Display Length 10

Visible True

Enabled True

Required True

Minimum Value NA

Maximum Value NA


PV-SQL NA

PV-Parms NA


Field Name Hours

Active True

Caption Hours Worked

Heading Hours Worked

Data Type Float

Data Length NA

Total Precision Use Default

Decimal Places Use Default

Array False

Array Size NA

Default Type NONE




3-21

Field Value Default From Field NA

Constant NA


Mask Type NA

Display Length NA

Visible True

Enabled True

Required True

Minimum Value 0

Maximum Value 24


PV-SQL NA

PV-Parms NA


Field Name WorkDate

Active True

Caption Date Worked

Heading Date Worked

Data Type SmallDateTime

Data Length NA

Total Precision NA

Decimal Places NA

Array False

Array Size NA

Default Type NONE



Constant NA


Mask Type NA

Display Length NA



3-22

Field Value Visible True

Enabled True

Required True

Minimum Value Use Default

Maximum Value Use Default


PV-SQL NA

PV-Parms NA



3-23

Lab 3.3- Create Required Database Objects Scenario

Generate the needed scripts and create the required database objects for this project (ST26000).

Challenge Yourself!

1. Create the new CRT, DH and SDO files for the xBillable Table. 2. Create the Table xBillable in the database. 3. Create the Index for xBillable in the database. 4. Create the Stored Procedure for xBillable in the database.

Need a Little Help?

1. Select the Administration Group then generate schema. 2. Create the new CRT, DH and SDO files for the xBillable Table. Put

the new scripts in the ST26000 folder. a. To select the table, place an “X” in the “Selected” column. b. Browse to find the ST26000 folder by using the button next to

each text box at the bottom of the window.

3. Use SQL Server Management Studio for all the objects in the following steps.

4. Load the scripts from the ST26000 folder. 5. Create the Table xBillable in the database. 6. Create the Index for xBillable in the database. 7. Create the Stored Procedure for xBillable in the database.

Step by Step

1. Create the new CRT, DH and SDO files for the xBillable Table. Put the new scripts in the ST26000 folder. a. In Dynamics SL, select the Administration Group Wonder Bar

then generate schema in the right pane under the Utilities group. b. Locate and select the xBillable table in the list and place an “X”

in the “Selected” column. c. Click the browse button next to the SQL Create Table Directory

path. d. Browse to find the ST26000 folder for each of the three paths, by

using the browse button next to them at the bottom of the window.



3-24

e. Click the Begin Processing button. f. Click OK on the process status window. g. Close the Generate Schema window.

2. Create the Table xBillable in the database.

a. Locate the Microsoft SQL Server Management Studio icon under the Microsoft SQL Server program group and click it to start the program.

b. On the Connect to Server window verify the server name and choose Windows Authentication. You could use SQL Authentication and supply the SQL Server SA login and password. After choosing your Authentication and server click the Connect button.

c. Click the New Query button. If you see the Connect to Server window again supply the same credentials you did before.

d. Select File > Open > File or click the open file icon on the toolbar.

e. At this point there are two ways this can be done. The first is to Navigate to the 26000 folder where the script files are stored and select the xBilable.CRT script to open it then copy the contents into the new query window that you opened two steps ago. The second way to do this is to change the name of the file to add a .sql to the end of it. That way SQL will see it as a SQL script file and open it to where you can select the database you wish to run it against on the toolbar.

f. Select the database you wish to run the script against on the toolbar.

g. Run the script by selecting the Execute button on the toolbar.

3. Create the Index for xBillable in the database. a. You should already be connected to SQL and have run your first

query from the steps above. b. Either rename the xBilable.CRX script file to have a .sql on the

end of it or click the New Query button to open a query window to copy the script text into. If you see the Connect to Server window again supply the same credentials you did before.

c. Select File > Open > File or click the open file icon on the toolbar.

d. Navigate to the 26000 folder where the script files are stored and select the xBilable.CRX script to open it. If you renamed it you can go to the next step. Otherwise, copy the contents into the new query window that you opened two steps ago.

e. Select the database you wish to run the script against on the toolbar.

f. Run the script by selecting the Execute button on the toolbar.



3-25

4. Create the Stored Procedure for xBillable in the database. a. You should already be connected to SQL from the previous

steps. b. Either rename the xBillable_p1.CPR script file to have a .sql on

the end of it or click the New Query button to open a query window to copy the script text into. If you see the Connect to Server window again supply the same credentials you did before.

c. Select File > Open > File or click the open file icon on the toolbar.

d. Navigate to the 26000 folder where the script files are stored and select the xBilable.CPR script to open it. If you renamed it you can go to the next step. Otherwise, copy the contents into the new query window that you opened two steps ago.

e. Select the database you wish to run the script against on the toolbar.

f. Run the script by selecting the Execute button on the toolbar.



3-26

Introduction to the Detail Level The detail level has many of the steps required to implement a “Normal” level. They are:

• Adding a SDO file to the project. • Declaring a public cursor variable. • SetAddr call in the Form1 Load event. • SQLCursorex call in the Form1_Load event.

Since these steps were covered in detail previously, they will not be discussed now. The focus is on new API functions, controls, and properties needed to implement the spreadsheet in a detail level.

Review the Checklist for Adding a New Table

1. Define new table using Record Maintenance (93.260.00). Define the name and description of the new table to be created.

2. Define new fields using Field Maintenance (93.250.00). Define the fields of the new table and define the default controls types and property settings for VB controls that access the fields.

3. Generate a SQL CREATE TABLE script file using Generate Schema (93.400.00). Create a CRT file that contains a SQL CREATE TABLE statement that can be used to create the new table in any Microsoft Dynamics SL database.

4. Execute the CRT SQL script file. Use SQL Server Management Studio to run the CRT SQL script file created in the previous step. This creates the table in a database.

5. Create and execute a CRX SQL script file. Create a SQL script file that will create a unique index on the new table. Use SQL Server Management Studio to execute the script file.



3-27

6. Create and execute a CRP SQL script file.

Create a SQL script file that will create a stored procedure. Use SQL Server Management Studio to execute the script file. • The Procedure should be a select statement that selects every field

from the table. • Every field from the unique index of the table should be included as

a condition in the where clause. • At least one of the where clause conditions on one or more of the

index fields should be compared to a replacement parameter. • If a wildcard is passed to at least the last parameter then the

statement should return every row in the table. • If actual values are passed, the statement should return only one

row. • There should be an order by clause that matches an index of the

table. It will usually match the unique index.

What is a Detail Level?

A “detail level” is a logically related group of information just like a normal level. There are two important differences between a normal level and a detail level:

• The user interface - The user interface for a detail level must always be implemented

using a spreadsheet control.

• The number of rows retrieved from the database into the program at one time

With the normal level, at any given time, only one copy of one row from the database is in the program. If the user wants to move to another row in a normal level, the user must either commit or abandon any changes he or she may have made to the current row data. This is because in a normal level, the program has only allocated enough space for a single row at a time.

With a detail level, copies of entire sets of rows are retrieved from the database and stored in the program. The user can then make changes to as many of the rows in the set as he or she wants without having to commit changes to a row before moving to another.

The Tools for Visual Basic come with an extremely robust spreadsheet control that makes the implementation of both the detail level and its user interface very easy.



3-28

Add the DetailSetup Call to the Form1_Load Event

The DetailSetup call must supply four things that the Microsoft Dynamics SL Kernel requires to manage a detail level:

1. The name of the spreadsheet control that will be the user interface for the level.

FIGURE 3.15

The Microsoft Dynamics SL Kernel is capable of managing the entire detail level. It will:

• Format the spreadsheet controls (defining columns, column headings, column sizes, total spreadsheet size, and so on).

• Display data from the database in the spreadsheet control. • Save changes made to rows displayed in the spreadsheet control.

By passing the handle to the spreadsheet control, the Microsoft Dynamics SL Kernel is given direct access to the spreadsheet control so that it can perform these functions.

2. The handle to the database cursor for the detail level.

FIGURE 3.16



3-29

The Microsoft Dynamics SL Kernel uses the level of the cursor (determined in the SQLCursorEx call) to determine which update level the particular spreadsheet control is associated with.

3. The field that should be automatically numbered during insertion of new rows.

FIGURE 3.17

If there is no field that will be visible in the spreadsheet of a detail level, which can be used to uniquely identify a row in the spreadsheet, then the rows must be uniquely identified by their ordinal position within the spreadsheet. This requires that the Microsoft Dynamics SL Kernel calculate and set the line number for each line as it is updated or inserted into the database.

NOTE: Rows in a detail level must be kept unique one of two ways: By the ordinal position in which the user entered the rows into the spreadsheet. By one or more Key fields which are visible as a field in the spreadsheet.

If the rows are unique by their ordinal position, then the rows must always be displayed in the spreadsheet, in the order in which they were entered.

If the rows are unique by some “key” field, then the rows must always appear in the spreadsheet sorted by that field in ascending order. The techniques of auto-numbering and key fields CANNOT be mixed within a single detail level. The significance of this constraint will be evident in the project currently being created.

It would be desirable for items in the detail section of this window to be sorted by date. The only way to accomplish this would be to make the Date field a key field. If this were done, then the Microsoft Dynamics SL Kernel would require that no two rows in the detail section have the same date. Another side effect of this would be that the date of a row in the detail section could never be changed.



3-30

The complete discussion of this issue is beyond the scope of this note. However, you may have a need to have rows in a detail section that appear sorted by something other than the unique index of the rows. The Tools for Visual Basic are not designed to do this, and attempting to do so could create more problems than it solves.

4. The location and size of the global variables that have been defined to hold the copies of the rows retrieved from the database (usually the “buffer” variables declared in the SDO files).

FIGURE 3.18

The Microsoft Dynamics SL Kernel needs to be able to dynamically allocate enough space to hold as many rows as it might need to fill the spreadsheet of the detail level. Prior to the call to the DetailSetup function, there is enough memory in the program to hold only one row from the database (the “buffer” variable declared in the DH file).

When the DetailSetup call is made, the Microsoft Dynamics SL Kernel creates a dynamic array. Microsoft Dynamics SL Software calls these dynamic arrays “memory arrays.” Each element of the memory array is as big as the sum of the lengths of the variables that are passed in the parameters 5,7,9, and 11 of the DetailSetup call.



3-31

The memory array is actually created within the Microsoft Dynamics SL Kernel. Therefore, the Tools for Visual Basic program does not have direct access to the contents of this array. The variables which are passed in parameters 4,6,8, and 10 provides the “window” through which the elements of the memory can be accessed from within the Tools for Visual Basic program.

FIGURE 3.19

The DetailSetup function returns a pointer (handle) to the memory array it creates. Should the programmer need to navigate, insert, update, or delete rows in the array, she or he can do so by passing the handle of the memory array to special Microsoft Dynamics SL Kernel functions and accessing a copy of the data from the array, through the variables passed in parameters 4,6,8, and 10 of the DetailSetup function.



3-32

Lab 3.4 - Spreadsheet Foundation Scenario

The project has many steps that are similar to adding the Normal level. This exercise tests the ability to carry that information forward from a previous course. Additionally, a public variable for a memory array pointer and the DetailSetup API call will be added.

Challenge Yourself!

1. Add the xBILLABLE.dh.vb file to the project. 2. Declare a public cursor variable “csr_xBillable.” 3. Set the Levels property of the Update1 Control to include a new

detail level. 4. Add a SetAddr API call for the xBillable table. Or use the

Init_xBillable function. 5. Add a SQLCursorEx API call for the xBillable table. Or use the

Init_xBillable function. 6. Declare a Public variable “mh_xBillable” to be a pointer to the

memory location of the array. 7. Add the DetailSetup API call to the Form1_Load event.

Need a Little Help?

1. Add the xBILLABLE.dh.vb file to the project. a. This can be done by using Project > Add Existing Item.

2. Declare a public cursor variable “csr_xBillable.”

a. This should already be in the SDO file you just added. It is created when you use the generate schema window.

3. Set the Levels property of the Update1 Control to include a new

detail level. a. The levels is a Detail level with a name of “Billables.”

4. Add a SetAddr API call for the xBillable table.

a. There is a sub of code that was created in the SDO file by the generate schema window that will set this up. Put a call to the sub in the form load event.



3-33

5. Add a SQLCursorEx API call for the xBillable table. a. There is a sub of code that was created in the SDO file by the

generate schema window that will set this up. Put a call to the sub in the form load event.

6. Declare a Public variable “mh_xBillable” to be a pointer to the

memory location of the array. a. This variable is an integer and must be declared in the same

module as the public cursor variables.

7. Add the DetailSetup API call to the Form1_Load event. a. Be sure to set this memory array for auto-numbering.

Step by Step

1. Add the xBillable.dh.vb file to the project. a. Return to the ST26000 project in VB. b. Choose Project > Add Existing Item. c. Add the XBILLABLE.DH.VB file from the ST26000 directory.

2. Declare a public cursor variable “csr_ xBillable.”

a. The cursor statement was created for you by the generate schema window. Look in the xBillable.dh.vb file to see it.

3. Set the Levels property of the Update1 Control to include a new

detail level. a. Choose View > Solution Explorer. b. In the Solution Explorer window, double-click on the Form1

object. c. In the design view of the Form1 object, click once on the update

control (looks like a 3.5 diskette, usually located in the lower left corner of the form). If you do not see it, click the drop-down in the properties window in the next step and select it from there.

d. Choose View > Properties Window. e. In the Properties - Update1 windows, locate the Levels property. f. Set the Levels property of the Update1 control to:

Customer;N,Billables;D

4. Add a SetAddr API call for the xBillable table.

a. Return to the ST26000 project in VB. b. Choose View > Solution Explorer.



3-34

c. In the Solution Explorer window, double-click on the Form1 object.

d. In the Form1 design window, double-click on the form. e. Add the following code where the setaddr calls go to leverage a

sub of code created for you by the generate schema window. The line of code calls the sub and supplies it with two values. The values passed are the level the setaddr is for and if you want a sqlcursorex call to be used. There may be times when you do not need a sqlcursorex call.

Call Init_xBillable(LEVEL1, True)

5. Add a SQLCursorEx API call for the xBillable table.

a. In the previous step, if you put true as the second parameter, the SQLCursorEX call has already been taken care of for you. If you by chance put false in the command, change it to true. False means that you do not want a SQLCursorEX call to be made.

6. Declare a Public variable “mh_xBillable” to be a pointer to the

memory location of the array. a. In the Project Explorer window, double-click on the ST26000

file to display the code window of the file. b. In the (declarations) event of the ST26000 module add the line:

Public mh_xBillable as Integer

7. Add the DetailSetup API call to the Form1_Load event.

a. Return to the ST26000 project in VB. b. Choose View > Solution Explorer. c. In the Solution Explorer window, double-click on the Form1

object. d. In the Form1 code window, select the Form object and the Load

event. e. Add the following line of code after the ScreenInit line:

mh_xBillable = DetailSetup(csr_Xbillable, SAFGrid1, _ bXBillable.LineNbr, bXBillable, lenb(bXBillable), _PNULL, 0, PNULL, 0, PNULL, 0)

8. Click the Save button to save the project.



3-35

Add a Container Object Paste A Container Object (Group Box) And Grid Control On The Form.

Paste a Container Object (Group Box) on the Form

To cause the spreadsheet control to cover the desired portion of the form and to include the desired columns, a Group Box must be pasted onto the form. The fields that should be columns for the spreadsheet can then be pasted into the container and the spreadsheet control itself can be added from the Visual Basic Toolbox.

When the program is run, and the WindowInit call is made, the Microsoft Dynamics SL Kernel determines what container the spreadsheet control is in and will format the spreadsheet to cover the entire container. It then iterates through all Tools for Visual Basic controls in the same container and creates and formats columns for each control it finds. The order of the columns is determined by the tab index of the controls from which columns are derived.

HINT: The spreadsheet control will be formatted to fit WHATEVER container object it is in, and remember, a form classifies as a container object. If a Tools for Visual Basic program has the spreadsheet control covering the entire form and not just the group box, then the spreadsheet is probably on top of but not IN the group box. To fix this problem, return to design mode, cut the spreadsheet off the form, give focus to the group box, and paste the spreadsheet into the group box.

Paste an SAFGrid Control into the Contain Object

Once the container object has been pasted onto the form, the next step is to paste a Tools for Visual Basic custom spreadsheet control into the container object. The control simply needs to be placed into the container object, and it is necessary to verify that the name property of the control matches the name used in the DetailSetup call of the Form1_load event. It is not necessary to make the spreadsheet control any particular size because the Microsoft Dynamics SL Kernel automatically formats the control at run time.



3-36

Add Data Controls And Set The DBNav Property

Add Data Controls To the Container Object

The next step is to paste the data controls. Even though detail levels have a spreadsheet interface, the data controls are still required on the Form for two reasons.

• The Microsoft Dynamics SL Kernel uses the controls in the container object to determine: - What columns should be included in the spreadsheet. - How the columns should be formatted. - Which buffer variables to which the columns will be bound.

If there were no data controls, there would be no columns in the spreadsheet.

• Detail levels in a Tools for Visual Basic program automatically support two different views of the data. - The spreadsheet view is commonly referred to as “grid view.” - If the user double-clicks on the grid, or presses the F4 key, the

Microsoft Dynamics SL Kernel hides the spreadsheet control so the data controls underneath it can be seen. This view is called “form view” and allows the user to see all the fields for a single row in the grid at one time.

Because of the “form view” functionality, it is important to place the data controls for the detail level in an esthetically pleasing way.

HINT: Do not forget to set the level property of the controls. The level being added at this point is level 1. Controls will be pasted to whatever container object had focus last. The current controls should go into the container group box.

Set the DBNav Property of the Spreadsheet Control A Quick Recap

The program has a place to put one XBILLABLE row from the database and the Microsoft Dynamics SL Kernel knows about it.

• The SDO file allocated memory in the program with the global declaration of the bXBillable variable.

• The SetAddr call told the Microsoft Dynamics SL Kernel where the variable is located.



3-37

• A global database cursor has been declared to retrieve and update rows in the XBILLABLE table. - The global declaration of the csr_Xbillable variable provides a

place to store the handle to the cursor. - The SQLCursorEx call caused the cursor to be created on the

database, and the Microsoft Dynamics SL Kernel passed the handle back.

• A dynamic array is created to hold as many XBILLABLE rows as

might be needed, and associated a spreadsheet control and cursor with the array by the DetailSetup API function.

• There is place to display the XBILLABLE rows after they are retrieved from the database. - A container object has been added to the form. - Controls and a spreadsheet control have been pasted into the

container object on the form.

At this point there is still a key component missing. The Microsoft Dynamics SL Kernel needs a SQL statement that it can use to retrieve the XBILLABLE rows from the database. The necessary stored procedure was created in Lesson 5 when the new table was created.



3-38

The next step is to tell the Microsoft Dynamics SL Kernel what the name of the stored procedure is and where it can get the data to pass to the parameters of the stored procedure.

FIGURE 3.20



3-39

The Microsoft Dynamics SL Kernel found the stored procedure for level 0 by looking in the PV property of the last key field control of that level. The Microsoft Dynamics SL Kernel expected to find the stored procedure at this location because level 0 is a normal type level.

FIGURE 3.21



3-40

Since the current level is a detail type level, the Microsoft Dynamics SL Kernel expects to find the stored procedure for the level in the DBNav property of the spreadsheet control associated with the level (the spreadsheet control was associated with the level by passing the level 1 cursor, and the handle to the spreadsheet control in the DetailSetup call).

FIGURE 3.22

The stored procedure was created in the last lesson. Now the DBNav property of the spreadsheet control must be set so the Microsoft Dynamics SL Kernel will know the name of the stored procedure that should be used when navigating the level.

FIGURE 3.23



3-41

Setting the DBNav property of the spreadsheet control is almost exactly like setting the PV property of the Customer ID control. However, there are a couple of minor exceptions.

FIGURE 3.24

Text controls, like the cCustiD control, are bound to a single field of a buffer variable. The Microsoft Dynamics SL Kernel is designed on the assumption that the last parameter of a DBNav or PV stored procedure is associated with this field. Since the Microsoft Dynamics SL Kernel knows what field a text control is bound to, it also knows that this is where it should get the data for the last parameter to a DBNav or PV stored procedure. This means that when a programmer sets up a PV or DBNav property of a text control, the program is responsible for telling the Microsoft Dynamics SL Kernel where the data should come from for all procedure parameters except the last one.



3-42

Spreadsheet controls, by contrast, are not bound to any one specific field. This means that the Microsoft Dynamics SL Kernel cannot make any assumptions about where to get the data for any of the parameters to be passed to the stored procedure. The programmer must explicitly tell the Microsoft Dynamics SL Kernel by setting the structure.field properties of the DBNav property.

FIGURE 3.25

The program currently contains a bCustomer.Custid variable and a bXBillable.Custid field. At first glance, it might appear that the data for the first parameter could come from either of these two places. However, the Microsoft Dynamics SL Kernel will load the data for the window one level at a time in ascending level order. This means that before trying to load the detail level, the Microsoft Dynamics SL Kernel will first retrieve the CUSTOMER row into the level0 buffer, bCustomer. By the time the Microsoft Dynamics SL Kernel starts loading the detail level data, bCustomer.Custid already contains the desired value.

FIGURE 3.26



3-43

By passing the key field value from the previous level as a parameter to the stored procedure that loads the current level, the desired referential link between the levels is achieved.

FIGURE 3.27

Passing the bCustomer.Custid field has handled the first parameter of the stored procedure. However, there are still two more parameters and as stated earlier, the programmer is responsible for telling the Microsoft Dynamics SL Kernel where to get the data for both of these.

FIGURE 3.28



3-44

The Xbillable_p1 stored procedure can do two different jobs depending on what is passed in these last two parameters.

• If the minimum and maximum integer values are passed, then the stored procedure will retrieve the entire set of rows for the current Customer. This is exactly what we need to have happen when the Microsoft Dynamics SL Kernel is loading the row for the level.

• If the actual value in the bXBillable.LineNbr field is passed to both parameters, the stored procedure will retrieve only one row. This is exactly what needs to happen when the Microsoft Dynamics SL Kernel needs to lock a row for updating.

If the focus is on the second task first, then the Struct.Fieldname field of the parm2 tab of the DBNav property should contain “bXBillable.LineNbr.”

Now you must determine how the minimum integer value to be passed to this parameter can do so to achieve the first task. The values INTMIN and INTMAX are “wild card” values for an integer data type that are declared in the Solomon.VBTools.vb file. The answer to being able to wildcard a parameter can be found in the DBNav property window itself.

Checking the Wildcard check box for a parameter tells the Microsoft Dynamics SL Kernel to pass a wildcard value when it needs to load rows, but to pass the value found in the Struct.Fieldname when it needs to save the rows.

This actually handles both of the remaining parameters. When the Microsoft Dynamics SL Kernel determines that the data type of the field in the Struct.Fieldname is a numeric or date type, it knows that it will actually be required to send two values to the stored procedure. During load, it sends the minimum and maximum values for the data type. During save, it sends the value in the Struct.Fieldname twice. This means that although the stored procedure requires three parameters, the programmer only fills in information for the parm1 and parm2 tabs to explicitly identify the source of all three parameters.

NOTE: Had the data type of the last field been a string, then a LIKE operator could have been used. LIKE operators can accept a single percent sign as a wildcard. The BETWEEEN operator requires two values to achieve the wildcard functionality. Therefore, if the field had been a string data type, there would have been a one to one correspondence between the number of parameters in the stored procedure, and the number of parm tabs filled in the DBNav property.



3-45

Set the Level Property of Any Key Fields

There are two ways to keep the rows in a detail section unique:

• “KEY FIELDS” - The rows can be unique by some field that is visible on the window, which will be filled in by the user. Examples of this are things like the Chart of Accounts Maintenance (01.250.00) window. In this program, the user assigns account codes to rows. The Microsoft Dynamics SL Kernel automatically maintains the rows sorted by this field and enforces the rule that no two rows can have the same value for this field. The Account code field is a “key” field in this window.

• ORDINAL POSITION - The rows are automatically assigned a “line number” that represents the ordinal position in which the user entered the rows. This type is used when there is no field or group of fields, visible on the form that can uniquely identify a row. An example of this is detail lines on an invoice. It would be perfectly acceptable to have two invoice detail rows with exactly the same data in all the visible fields. It may also be the case that the order in which the invoice lines appear has some significance. In this case, the rows can be uniquely identified and sorted by their ordinal position within the spreadsheet.

There are no fields in this detail level that uniquely identify XBILLABLE rows. So there are no key fields in this detail level. Instead, the LineNbr field has been auto-numbered (in the DetailSetup function call in Form_Load).

HINT: These two methods cannot be mixed. If a Tools for Visual Basic program is written to have an auto-numbered field AND a key field in the same detail level the program may appear to work most of the time, but it will eventually crash.



3-46

Lab 3.5 - Set Up the Spreadsheet Scenario

This exercise adds the container, controls, and set properties needed to create the spreadsheet for this program.

Challenge Yourself!

1. Paste a container object on the form. 2. Paste a SAFGrid (spreadsheet) control in the container. 3. Paste the following controls in the container: Date Worked,

Salesperson ID, Hours Worked, and Description. 4. Set the required properties of the controls that were just added to the

container object. 5. Set the DBNav property of the spreadsheet control to use the

xBillable_P1 stored procedure. Set the required parameters. 6. Set the Key Fields (if any) on the controls in the container object.

FIGURE 3.29



3-47

Need a Little Help?

1. Paste a container object on the form.

a. The group box is on the Visual Basic toolbar.

2. Paste a SAFGrid (spreadsheet) control in the container. a. The SAFGrid control has to be “in” the group box, not outside of

it. b. The spreadsheet control has to be big enough to see, not cover

the entire frame.

3. Paste the following controls in the container: Date Worked, Salesperson ID, Hours Worked, and Description.

4. Set the DBNav property of the spreadsheet control to use the xBillable_P1 stored procedure. Set the required parameters. a. Parameter 1 must be from the bCustomer buffer. b. Parameter 2 is from the bxBillable buffer and must be ‘wild

carded.’

5. Set the Key Fields (if any) on the controls in the container object. a. There are only key fields when the spreadsheet is not “auto-

numbered.”

FIGURE 3.30



3-48

Step by Step

1. Paste a container object on the form.

a. Return to the ST26000 project in VB. b. Choose View > Solution Explorer. c. In the Solution Explorer window, double-click on the Form1

object. d. Choose View > Toolbox. e. Select the group box object. Hold the mouse cursor over controls

for a couple of seconds to display their names. f. On the form1 object, click and hold down the left mouse button

at the location where you want the upper left corner of the group box.

g. While holding down the left mouse button, drag to where you want the lower right corner of the group box, and let go of the left mouse button.

h. Refer to the window shot for an example of the placement of the frame.

2. Paste an SAFGrid (spreadsheet) control in the container.

a. Choose View > Solution Explorer. b. In the Solution Explorer window, double-click on the Form1

object. c. Left-click once on the group box to select it. d. Choose View > Toolbox. e. Select the SAFGrid object. Hold the mouse cursor over controls

for a couple of seconds to display their names. f. In the group box object, click and hold down the left mouse

button at the location where you want the upper left corner of the spreadsheet control.

g. While holding down the left mouse button, drag to where you want the lower right corner of the spreadsheet control and let go of the left mouse button. Make it big enough to see, but small enough to be out of the way.

h. Refer to the window shot for an example of the placement of the frame.

3. Paste the following controls in the container: Date Worked,

Salesperson ID, Hours Worked, and Description. a. Choose View > Solution Explorer. b. In the Solution Explorer window, double click on the Form1

object to display the design window of Form1. c. Left mouse click once on the group box object.



3-49

d. Use a SAFDate control for the work date. Use SAFMaskedText fields for the rest of the fields. Either drag and drop the fields into the group box or you can select the type of field and then draw it on using the same technique that was used to add the group box and spreadsheet control. Select the SAFDate control and add it to the group box.

e. Set the Name property of the new date control to cWorkDate. The standard naming convention is to start each control name with a lower case c.

f. Set the FieldName property to (without the quotes) “bxbillable.workdate”. This tells the control what buffer it is bound to.

g. Set the Heading property to (without the quotes) “Date Worked”. This is what will show as the heading for the field in grid mode.

h. Set the Level property to 1. i. Add a label for the worked date by selecting a label control from

the toolbox. j. Set the Name property of the label control to (without the

quotes) “lDateWorked”. The standard naming convention is to name the label fields starting with a lower case L.

k. Set the Text property of the label to (without the quotes) “Date Worked”. This is the text that the label will display.

l. In the Form1 design window, position the Worked Date data field and the label like they are on the window shot below.

m. Continue inserting all fields from the Xbillable table except for the CustID, LineNbr, and NoteID fields.

n. Set the Name, Fieldname, Heading and Level properties for each data control.

o. Set the Name and Text properties for each Label. p. Refer to the window shot below for an example of the placement

of the controls.

4. Set the DBNav property of the spreadsheet control to use the xBillable_P1 stored procedure. Set the required parameters. a. Choose View > Solution Explorer. b. In the Solution Explorer window, double-click on the Form1

object to display the design window of Form1. c. Click once on the SAFGrid1 control. d. Choose View > Properties Window. e. In the Properties- SAFGrid1 window, locate the DBNav

property. f. Click on the ellipse button in the DBNav property. g. Set the SQL Proc/Text: field of DBNav property to (do not

include quotes): “xbillable_p1”. h. Left mouse click on the parm1 tab.



3-50

i. Set the Struct.Fieldname field to (do not include quotes): “bCustomer.custid”.

j. Click the parm2 tab. k. Set the Struct.FieldName field to (do not include quotes):

“bxbillable.linenbr”. l. Check the Wildcard check box. m. Click the OK button on the DBNav property window.

5. Set the Key Fields (if any) on the controls in the container object.

a. Since the detail section is auto-numbered, there are not any key fields. Therefore, there is nothing to do for this step.

6. Click the Save button to save the project.



3-51

Test Run Testing the Program

All eleven of the steps required to add a detail level to a project have been completed. If this detail level were the first level in the project (a single, detail level window like Row Maintenance (93.260.00) or Chart of Account Maintenance (01.250.00)), then the level would function properly at this point. However, since the detail level is actually a subordinate level to the normal level, there is one more step that must be performed. Since it is a common mistake to forget this step, test the program at this time and observe the behavior that results when this step is missed. This will also give an opportunity to track down any syntax or typing errors that might have occurred.

NOTE: This was not included in the checklist for adding a detail level because it is not technically a required step for a detail level. This step would not be necessary in the following cases: The Form has only one level and that is the grid. This would be the case in the Chart of Accounts Maintenance (01.250.00). The level directly above the detail level is auto-numbered.

NOTE: An easy way to check for other common coding errors is to run the VB Code Inspector program which is automatically added to your Visual Basic Add-Ins list when the Tools for Visual Basic are installed.



3-52

Lab 3.6 - Testing the Program Scenario

Step by Step

Testing the Program by Adding Detail Rows to a Customer

1. Make sure that Microsoft Dynamics SL is running. 2. Return to the ST26000 project in VB. 3. Click the green triangle on the toolbar at the top. 4. While your program is running, click the First button on the

Microsoft Dynamics SL toolbar on your window. a. You should see the Customer ID and name of the first Customer

in the Customer table.

5. Click in the first field of the first line in the spreadsheet. 6. Enter values for several fields. 7. Move to the next line in the spreadsheet.

a. If you cannot move to the next line, you may have some controls in the detail section with their level property set to 0 instead of 1.

8. Enter values for several fields. 9. Click the Save button on the Microsoft Dynamics SL Toolbar. 10. Click in the Customer ID data control. 11. Click the Next button on the Microsoft Dynamics SL Toolbar. 12. Click the Previous button on the Microsoft Dynamics SL Toolbar. 13. Verify whether or not your detailed lines appear. 14. Add more rows to this customer and press the Save button.

a. Was a message displayed indicating that another process already added the rows?

15. Stop the program by clicking the Close button on the Microsoft

Dynamics SL Toolbar.



3-53

Lab 3.7 - Find Out What Went Wrong Scenario

Use Microsoft SQL Server Management Studio to find out what went wrong.

Step by Step

1. Locate the Microsoft SQL Server Management Studio icon on your desktop (note that the instructor may have included this within a folder for the class, or in the START menu with the other MS SQL Server programs).

2. In the Connect to SQL Server dialog box select the database server name on which your Microsoft Dynamics SL database is installed.

3. In the Connect to SQL Server dialog box, Select Windows Authentication. If you select SQL Authentication, you will need to supply the SA user name and password to connect.

4. Click the Connect button. 5. Click the New Query button on the toolbar. 6. Select the database from the drop-down that you want to run the

query against. In this instance select the application database you are logged into with Dynamics SL.

7. Type “Select * from xbillable” (without the quotes) into the Query window.

8. Click the Execute button on the toolbar. 9. Review the result set. Pay particular attention to the Custid field. 10. How does the data explain the behavior in the previous exercise?



3-54

Adding Code To Linegotfocus to Fill the Foreign Key Field in the Detail Level

It is the programmer's responsibility to fill the CustID field of the XBillable row using the data from the CustID field of the Customer row.

The spreadsheet control has an event called the LineGotFocus event. This event fires whenever the user moves to a different row in the detail section

NOTE: The event will fire even if the user is in form view and the spreadsheet is not visible.

The Microsoft Dynamics SL Kernel passes a parameter called MaintFlg, which contains the status of the line the user just moved from, when the event fires. MaintFlg can have a status of:

• NOTCHANGED − The row was inserted into the spreadsheet (usually from the database), and the user has not made any changes to the data since then.

• UPDATE − Some changes to the data have occurred since the row was inserted into the spreadsheet (usually from the database), and the row has not yet been saved to the database.

• INSERTED − The user has entered data into the row and moved off the row, but the row has not yet been saved to the database.

• NEWROW − The current line is not yet a valid row. If the user enters any data into the line and moves off the line, the row will then have a status of INSERTED. In other words, the user has clicked the Insert button on the Toolbar, or she has moved off the last line in the spreadsheet to a blank line.

Whenever the LineGotFocus event fires, with a status of NEWROW, it is our responsibility to programmatically set the bXBillable.Custid field equal to the bCustomer.Custid field. Since we put the value we want in the field, the proper value will be saved in the database.



3-55

Lab 3.8 - Add Code to Linegotfocus Scenario

Step by Step

1. Return to the ST26000 project in VB. 2. Choose View > Solution Explorer. 3. In the Solution Explorer window, double-click on the Form1 object

to display the design window of Form1. 4. Double-click on the SAFGrid1 Control to open the code window for

the default event of that control. 5. In the Events: list box, select LineGotFocus. 6. In the code window, add the following code (note that you should

find the Sub and End Sub lines are already there):

‘Check for a new row

If maintflg = NEWROW then

’Is a new row, set the relationship

bXBillable.Custid = bCustomer.Custid

end if

7. Save the project.



3-56

Lab 3.9 - Adding Detail Rows to a Customer Scenario

Step by Step

1. Make sure that Microsoft Dynamics SL is running. 2. Return to the ST26000 project in VB. 3. Click the green triangle on the toolbar to start your program. 4. Click the First button.

a. The Customer ID and name of the first Customer in the Customer table will be displayed.

5. Click in the first field of the first row in the spreadsheet. 6. Enter values for several fields. 7. Move to the next line in the spreadsheet. If you cannot move to the

next line, you may have some controls in the detail section with their level property set to 0 instead of 1.

8. Enter values for several fields. 9. Click the Save button on the Microsoft Dynamics SL Toolbar. 10. Click in the Customer ID data control. 11. Click the Next button on the Microsoft Dynamics SL Toolbar. 12. Click the Previous button on the Microsoft Dynamics SL Toolbar. 13. Did the detail lines appear? 14. Add more rows, and press the Save button. 15. Was a message displayed indicating that another process already

added the rows? 16. Stop the program by clicking the Close button on the

Microsoft Dynamics SL Toolbar.



3-57

Review of Checklist for Adding a Detail Level

# Description 1. Add a “SDO” file to the Tools for Visual Basic project.

2. Add the Public Cursor variable. (Done for you since using Generate Schema to create the files.)

3. Set the “Levels” property of the “Update” control.

4. Add the SetAddr call to the Form1_Load event. (Can leverage a sub of code created for us by Generate Schema.)

5. Add the SQLCursorEx call to Form1_Load event. (Can leverage a sub of code created for us by Generate Schema.)

6. Add the Public Memory Array Pointer variable.

7. Add the DetailSetup call to Form1_Load event. • Tell the Microsoft Dynamics SL Kernel to create a dynamic data

structure to hold multiple rows for the level. • Get a handle to the data structure created. • Associate the data structure, spreadsheet control, and cursor to each

other, and to the update level. • Tell the Microsoft Dynamics SL Kernel if it will be responsible for

assigning line numbers to the rows, and if so, which field of the row will contain the line number.

8. Paste a container object (Frame) on the form. The Microsoft Dynamics SL Kernel knows that all controls in this container should be considered to be columns of the spreadsheet control.

9. Paste an SAFGrid control into the contain object. The name of this control must match the name used in the second parameter of the DetailSetup call.

10. Add data controls to the container object.

11. Set the DBNav property of the spreadsheet control. Tell the Microsoft Dynamics SL Kernel the name of the stored procedure or the SQL Select statement that should be used to retrieve and update rows for the level.

12. Set the level property of any key fields, if any.



3-58

Summary We introduced the detail level of a Visaul Basic project and completed other tasks which include:

• Adding a new table to a Dynamics SL database. • Adding codes. • Adding container objects. • Performing a test.



3-59

Quick Interaction: Lessons Learned Take a moment and write down three key points you have learned from this chapter:

1.

2.

3.



3-60


sl70_enus_tvb_03

Documents

salesperson table

required new table

table scripts

new fields

microsoft dynamics sl

microsoft dynamics sl

customer information

salesperson information