Software Development Kit (SDK) Development Utilities Guide

Transcription

1 Software Development Kit (SDK) Development Utilities Guide Sage ERP MAS 500 ERP

2 Copyright Sage Software, Inc. All rights reserved. Sage, Sage logos, and the Sage product and service names mentioned herein are registered trademarks or trademarks of Sage, Inc. or its affiliated entities. All other trademarks are the property of their respective owners.

3 Table of Contents Chapter 1: Development Utilities... 1 Application Wizards... 1 Installing and Using the Application Wizards... 2 Table Design... 2 Data Dictionary... 4 Applications... 5 Sage ERP MAS 500 Application Architecture... 5 Customization Project Generation... 7 Dependencies... 9 Wizard Behavior Step 1 - User Interface Step 2 - Project Details Step 3 - Select Columns Step 4 - Review Choices Control Types and Data Types Line Entry Application Wizard Example Projects Report Wizard Starting the Wizard Building the Project Error Rigging Error Rigging User Interface Visual Basic 6.0 IDE - Conditional Compilation Ranges Overview Local Strings Overview Local Messages Overview Lookup Definition Maintenance Overview Connecting to the Database Scripting Lookup Input/Lookup Definition Select Columns For Display Dialog Box SQL View Col Mapping Tab Data Dictionary Lookup Tab S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE III

4 Module Overview Creating Custom Modules Step by Step Assigning Tasks to Custom Modules Table Population Data Dictionary Task Editor Task Selection Schema Browser Standards Checker Installation/Registration The Application Maintain Report Sort Selection Information Introduction Using the Utility S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE IV

5 Development Utilities This document provides an overview and detailed explanation of different utilities used in the Sage ERP MAS 500 development environment. Every utility has a purpose that supports Sage development strategies. This chapter discusses the following development utilities: Application Wizards Line Entry Application Wizard Report Wizard Error Rigging Ranges Local Strings Local Messages Lookup Definition Module Data Dictionary Task Editor Schema Browser Standards Checker Application Wizards Maintain Report Sort Selection Information Application Wizards are used to create Visual Basic projects that run from the Sage ERP MAS 500 Desktop. Application Wizards build wizard files (files with an AAW extension). These are plain text files containing data collected during each wizard session. The name of the Application Wizard file is the same name that is used to create the VBP file. Both the Application Wizard file and the VBP file are stored in the same location. The Application Wizard file also contains other data, particularly the Data Dictionary information obtained from the system database tables tsmdatadictflat, tsmdatadictcol, tsmdatadicttbl, tsmdatadictrelatn, tsmdatadictviewcol, and tsmdatadictfk. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 1

6 The Application Wizard collects information used for naming components of the project as well as the sources of data used in the application. The wizard accesses the Data Dictionary to obtain the properties for each column the application binds to so the correct control and configuration are used. When binding to a grid, the Data Dictionary determines cell dimensions and other setup information. The intent is that, following the wizard session, a new application compiles and runs as a Sage ERP MAS 500 task from the Sage ERP MAS 500 Desktop and the coding of the task s business logic can begin immediately. At the end of each wizard session a To Do List displays indicating what additional steps are necessary in order for the new project to run. Some of these items are optional and dependent on the nature of the project being built. Installing and Using the Application Wizards Preparation The Application Wizards make many assumptions about the nature of the applications being built. Success depends on the accuracy and richness of the Data Dictionary information that describes the data. Become familiar with the entire design and build process described in this guide. Development Environment You must first install the source code. After the source code is installed, run the Ranges utility and contact Sage ERP MAS 500 Support to obtain your company code and data ranges for messages and strings. Table Design For more information, see Schema Browser. Primary Key Every table used in Sage ERP MAS 500 must have a Primary key. Surrogate Key A Primary key may or may not be a Surrogate key. Natural Key A Natural key defines uniqueness for each row in a table. Typically, it is a multi-column key that consists of the IDColumn for the table and one or more Foreign keys. In certain cases for performance reasons, the Natural key is defined in a Clustered index. In this case, it is important to ensure that the Uniquekey and OrderBy properties of any Data Manager objects use the Natural key exactly as defined in the clustered index to deliver optimal performance with applications that use grids. If the OrderBy property is not the same as that defined by a Clustered index, SQL Server creates a temporary table for the result set. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 2

7 IDColumn A table s IDColumn is the only column that is part of the Natural key, but not a Foreign key. This column is generally used as the Lookup control s Bound Column property. In the Sage ERP MAS 500 database there are, however, instances of tables that do not have an IDColumn. In these cases, all of the Natural key columns are Foreign keys and the wizards may have difficulty determining which of the Natural key columns should be used by the Lookup control. For example, the IDColumn for the table tarcustomer is CustID. Example Script The following example script produces two tables that work as the parent and child tables in a Line Entry project. Note that in each case, the Primary key is created as a NONCLUSTERED index. if exists (select name from sysobjects where name = tglalloccjk and type = U ) Drop table tglalloccjk go CREATE TABLE tglalloccjk ( AllocateKey int NOT NULL, AllocID char(10) NOT NULL, AllocMeth smallint NULL DEFAULT 0 CHECK (AllocMeth IN (0, 1, 2, 3, 4, 5, 6)), AllocType smallint NULL DEFAULT 1 CHECK (AllocType IN (1, 2, 3, 4, 5)), CompanyID char(3) NULL, Description varchar(40) NULL DEFAULT, Financial smallint NULL DEFAULT 1 CHECK (Financial IN (1, 0)), LastPostDate datetime NULL, PostCmnt varchar(255) NULL DEFAULT, UpdateCounter int NOT NULL DEFAULT 0 ) go GRANT REFERENCES, SELECT, INSERT, DELETE, UPDATE ON tglalloccjk TO public GO CREATE UNIQUE INDEX XAK1tglAllocCJK ON tglalloccjk ( CompanyID, AllocID ) go ALTER TABLE tglalloccjk ADD PRIMARY KEY NONCLUSTERED (AllocateKey) Go if exists (select name from sysobjects where name = tglallocdetlcjk and type = U ) Drop table tglallocdetlcjk go CREATE TABLE tglallocdetlcjk ( AllocateDetlKey int NOT NULL, AllocAmt decimal(15,3) NULL DEFAULT 0, AllocateKey int NOT NULL, S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 3

8 Data Dictionary AllocPct decimal(5,2) NULL DEFAULT 0, GLAcctKey int NULL, GLAcctMask varchar(100) NULL, PostCmnt varchar(255) NULL DEFAULT, SeqNo int NOT NULL ) go GRANT REFERENCES, SELECT, INSERT, DELETE, UPDATE ON tglallocdetlcjk TO public GO CREATE INDEX XIE1tglAllocDetlCJK ON tglallocdetlcjk ( AllocateKey, SeqNo ) go ALTER TABLE tglallocdetlcjk ADD PRIMARY KEY NONCLUSTERED (AllocateDetlKey) go When new tables are imported using the Data Dictionary, the Data Dictionary is updated with information that the wizards use to create new tables. The wizards are dependent on this information and typically inform you when essential information is missing; however, the wizards are tolerant, to some extent, of variations to ideal table design and allow the flexibility to normalize the database in a variety of ways. Keys The Data Dictionary defines the Primary key, Surrogate key, Natural key components, and which columns in each table are Foreign keys. The Data Dictionary utility maintains this information and the Application Wizard is dependent on this information. Domains The Data Dictionary utility also allows you to assign DomainIDs to each column. This often determines which controls are used to bind to these columns. Grid Setup Properties When data is presented in a grid, the Data Dictionary defines how each grid column is set up. Column width, caption, and cell type properties are obtained from the Data Dictionary. Report Settings Report projects use Data Dictionary information for the default Sort/Select column usage. Captions and Strings You define Short and Long captions in the Data Dictionary. These are localizable and use tsmlocalstring for their persistence. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 4

9 Lookup Definitions The Lookup Definition utility is used to create or change Lookup definitions. You use the Data Dictionary utility to assign Lookups to selected columns. Applications Each type of project has its own unique requirements and dependencies. For more information, see Dependencies. Blank Project A Blank project has no data binding specified during the Application Wizard session. Use this project type to build a task that only has the basic Form controls: Toolbar, Status Bar, and references for the commonly used controls and objects including Customizer components. Single Row Maintenance This type of project maintains a single row from a table using the framework s CompanyID value as the key into the table. Typically, Option type application tasks use this methodology. Multi Row Maintenance Multi Row Maintenance tasks use a Lookup to locate a row in a table. The row s data is then populated into the controls on the form for editing. You can add new rows and delete existing rows. Data Sheet Data sheets present data in a grid for editing. You can add new rows or delete existing rows. Line Entry Line Entry tasks maintain the values in a parent/child relationship. The parent table is the header and its values are maintained in bound controls and the child table contains the detail. Child table data is presented in a grid and edited in controls bound to the grid using the LineEntry class. Report The Report Wizard creates standard Sage ERP MAS 500 style report projects. Sage ERP MAS 500 Application Architecture Form Layout Each task, depending on its type, has a standard set of features, and provides the basic means of controlling the form s state, navigation, data validation, and customizing the form during runtime. The form layout consists of the principal UI components and supporting classes that characterizes the look and behavior of Sage ERP MAS 500 applications. Each project type contains both common and unique form layout components. The Application Wizards reproduce these styles before adding any bound controls and other taskspecific UI items. All project styles contain the following components (although their initialization may be different from one style to another): Toolbar - With different options for which buttons are made visible and operable depending on the project type S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 5

10 Status Bar - The status bar navigation buttons are visible in some project types, but not in others Customizer controls and the Customizer code Validation Manager In addition, and for each project type, you can add the following layouts: Blank Project No other components Single Row Maintenance Tab control to contain bound controls Multi Row Maintenance No other components-all bound controls are placed on the form. Data Sheet Grid, all data is bound to the grid. Line Entry Tab control. Tab 1 contains controls bound to the parent table. Tab 2 contains a grid and the Line Entry frame. Child table data is bound to controls on this tab. Tab 3 is empty and reserved for calculated or derived data. Application Class Module This module is created by the Application Wizard code generator and provides the task s interface to the Framework. The code contained in the class module is always the same except where references are made to names that are specific to the task (for instance, the name of the application s main form module). Application Basic Module This module is created by the Application Wizard code generator and provides the Sub Main(). The code contained in the basic module is always the same except where references are made to names that are specific to the task (for instance, the name of the application s main form module). Common Code Each task, depending on its type, uses many of the Common code modules. The Application Wizard adds these into the project. Data Manager Each bound table requires a Data Manager or Grid Manager. Data Managers deal with the complexity of Control or Grid binding to the database. Data Manager, for most situations, handles the maintenance of data for Insert, Update, and Delete. Business logic requires other techniques, perhaps, for special validations, lookups, and processing. Control Binding Certain controls require special considerations when binding. For example, the Data Manager uses different methods for binding Lookup controls and Drop-Down controls. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 6

11 Coding Standards Coding standards for programs fall into four major categories: Good Practice - Including a consistent naming convention for controls, variables, and file names Classic Constructs - Techniques developed as reference methods of implementing functionality Design Intent - How controls, common code, and objects are designed to interact with each other Error Handling Adherence to these coding standards and conventions is highly recommended. Customization Project Generation Wizard Sessions During each wizard session, data is collected that is used to build both the user interface and code required to create a Visual Basic project that runs in the Sage ERP MAS 500 environment. The wizards collect information used to name the files that are created and to determine a project directory in which to store them. The kind of project being built determines the information collected and how to build the UI and bind controls to data. Building the UI The following steps are used to create the new task s user interface: Build the form and add form controls appropriate to the type of task (including the grid, if required) Add custom controls (their Left property is set to ) Add other bound controls if required Add Customizer components As controls are added to the form, any event handlers along with initialization and termination code they require are added to the form module on the fly. This is also part of the code generation process. For more information, see Code Generation. Controls are added to any of the main elements of a form as prescribed by the project type: To the form To the form s main tab control To the Line Entry frame in a Line Entry project (on Tab 2 of the Line Entry s Main tab) To each of the tabs in a report project There is no dependency in the generated code where these controls must reside and they can be moved as required after project generation is completed. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 7

12 Code Generation The Application Wizard generates code in three ways: Boilerplate code fragments specific to each project type Boilerplate code with token replacement - The code fragments maintained in the Application Wizard contain tokens that are replaced with data collected from the Application Wizard session. Example: smyname = [*FormName*] Might become: smyname = frmcizng001 The Data Manager binding calls are also made in this way. Generated code - This is typically produced when adding certain types of controls to a form. When adding a Lookup control, for example, the control must be initialized in SetupLookups(), there must be a call to TerminateControls() in PerformCleanShutdown() if one does not already exist, and the control s LostFocus() event must be created. What You See Is Not What You Want When the Sage ERP MAS 500 Software Development Kit (SDK) builds a project, it constructs the user interface and code to make the application run in the Sage ERP MAS 500 environment, and bind to the data. The SDK uses a simple algorithm for placing controls on the form and no attempt is made to layout controls using any aesthetic rules. After coding has started, it is easier to add new controls manually than to regenerate your application and have your modifications overwritten. Sage Controls This section describes how the Application Wizard code generator handles the Sage controls when they are added to a project. Lookup A main Lookup is added to Multi Row Maintenance and Line Entry projects. Both project types initialize the control in the same manner: The LookupID property is set at design time. These are automatically set during project generation. The BoundTable and BoundColumn properties are set at design time. These are automatically set during project generation. This applies only to the Natural key Lookup control, not the Foreign key Lookup control. Code is added to the SetupLookups() procedure to initialize the control. This applies only to the Natural key Lookup control, not the Foreign key Lookup control. A call is added to TerminateControls() in PerformCleanShutdown() if it does not exist. This applies only to the Natural key Lookup control, not the Foreign key Lookup control. Creates the control s BeforeValidate and LookupClick events. Adds the control to the Validation Manager s Keys collection in FormActivate(). S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 8

13 The control is bound to the modmheader object. Code is added to the HandleBrowseClick procedure to set up the control when the status bar navigation buttons are used. Dropdown The Dropdown control must be initialized with any static list data during task initialization. When a static list is required in the grid of a Line Entry application, specific procedures required to perform the correct display of selected items in the grid and the Line Entry frame. Calendar, Maskededit, Currency, Number These controls are bound to data in BindForm() and/or BindDetail() in the same manner as any non-sage control; there is no special initialization generated by the Application Wizard. Dependencies Project Type Blank Project Single Row Multi Row Data Sheet Line Entry Report Tool Bar Yes Yes Yes Yes Yes Yes Status Bar Yes Yes Yes Yes Yes Yes Validation Manager Data Manager Main Lookup Grid Manager Line Entry Class Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes No No Yes No Yes No No No No No Yes Yes No No No No Yes No Tab Control No Yes No No Yes Yes Bound Controls * No Yes Yes No (just Grid) Yes Yes Customizer Yes Yes Yes Yes Yes Yes *Indicates that columns are bound to controls appropriate to their data type S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 9

14 Wizard Behavior An Application Wizard has two visual elements: TIP If the wizard warns you that there is insufficient information to build the project you can load this file by selecting Load Project Definition from the menu (the Application Wizard file is already built). Although the project does not build correctly, the wizard generates all of the code and UI that it can with the given information. You can then manually fix the code. The panel on the left, which is used to navigate between wizard steps The panel on the right, which is used to collect information for each wizard step Next Button The Next button is enabled if all of the required information on the current step is valid. If this button is enabled, you can click it to proceed to the next step. Previous Button Move to the previous step by clicking this button. Cancel and Exit Cancel and exit the wizard by clicking this button. Finish Button This button is enabled when the wizard has all of the information required to generate a project (usually on the last step). Step Numbers When a step number is highlighted, it is the current step. You can select a step number to move between steps if the required information is present and valid between the current step and the new step (you can move multiple steps if the intervening steps are valid). When you start a wizard session, you must move sequentially through all of the steps until the last step is reached and the Finish button is enabled. When the last step is reached, you can select any of the previous steps to make changes by selecting a step number. Keyboard Shortcuts When focus is on the left panel s navigation buttons, use the Left and Right cursor keys to move between the Previous, Next, and Finish buttons. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 10

15 Step 1 - User Interface In the wizard pages that follow, a data sheet application will be built as an example. The specifics relating to each of the project types that can be built with this wizard are also detailed. Step 2 - Project Details First, you need to select the project style to use for the new task. Type the application title, project ID, module ID, form caption, and select the HTML Help check box, if applicable. The HTML Help check box is available only if the ModuleID selected is not a Sage delivered module. For SDK developed modules, you have the option to use WinHelp or HTML Help. Select this check box if the project uses HTML Help. Clear this check box if the project uses WinHelp. It is assumed that you use the Sage ERP MAS 500 naming conventions (for example, ProjectID must always begin with the two letter module abbreviation). S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 11

16 WARNING Ensure that you create a subdirectory exactly two levels down from Src\App\ so that Visual Basic can find the files in Src\App\Common\. It is highly recommended that you use the default behavior of this feature and the same naming convention and directory tree structure. The files generated from the example shown above are: cizng001.vbp cizng001.frm cizng001.bas cizng001.cls (the Visual Basic name for the class will be clscizng001 ) cizng001.aaw (the Application Wizard data file) All of these files are stored in the following directory: <<Sage MAS 500 SDKSourceRoot>>\Src\App\CI\CIZNG001\ where the directory CI is taken from the first two letters of the ProjectID. These directories are automatically created or you can place the files in a different location; however, it is very important that the relative address to the Common directory is maintained so that the project can correctly reference it. Common files are located in: <<Sage MAS 500 SDKSourceRoot>>\Src\App\Common\ The first two letters of the ProjectID are assumed to be the module identifier as defined in the system table tsmmodule. For more information, see Directory Synchronization below. The Application s ProgID is <<ProjectID>>.<<ClassName>>. The ProgID for the example above is cizng001.clsfobmaint. Directory Synchronization The Application Wizard needs to build projects within a known and controlled environment because each project requires common source files that are referenced in the VBP file using a relative pathname. The Sage ERP MAS 500 development team uses the same project directory structure enforced by the Application Wizard. A Sage ERP MAS 500 Source Root directory exists (for example, F:\Sage MAS 500 SDK\) that can be any directory name off the root of a specific drive. From this directory, the SRC subdirectory contains various types of source code. Application source is located in the SRC subdirectory App, which is where your source files reside. In the App directory, the source is divided into modules, such as GL, AP, and so on. Within each module, additional subdirectories contain the source for each project. The final directory structure should look similar to the following: F:\Sage MAS 500 SDK\Src\App\GL F:\Sage MAS 500 SDK\Src\App\AP The Application Wizard automatically synchronizes the target directory for new projects when you enter the first two letters of the ProjectID. Based on this information, the Application Wizard fills in the Module field and synchronizes the project source directory to the correct module subdirectory. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 12

17 Step 3 - Select Columns If a new module is created (for example, by entering a ProjectID of QW that does not exist), the Application Wizard prompts you to create the new Module subdirectory. If you made a mistake, click No and start again; otherwise, the new subdirectory is created as a container for the new module s projects. When you enter the complete name of the new task in the ProjectID field and the control loses focus, the Application Wizard prompts you to create the Project directory. If you click Yes, the new directory is created and the complete directory tree for the new project is defined. This is the source code location for all Application Wizard generated Visual Basic files for the project you are creating. If, when prompted to create a new directory, you click No, click the Create Directory button to define your own source code location. This feature adds another sub directory to that shown in the Project Location drive and file list boxes. When this step appears you will notice that some columns are preselected. These are required columns and cannot be removed from the project. These columns are identified by prefixes with the following meanings: *ID* = IDColumn *SK* = Primary key column. This is determined by the Application Wizard and is obtained using the sp_pkeys stored procedure. All tables must have a Primary key defined. *UK* = Both a Foreign key and Natural key column (UK stands for Unique Key because it is returned by the stored procedure spgetuniquekey). These columns must be selected into the project for a data sheet because the Data Manager must be physically bound to all elements of the Natural key. If you do not want to display or edit these values in a data sheet application, hide these columns by setting their ColHidden property to true in the SetupGrid function in the Form Module after the project is generated. Select other columns that are required for the project from the Available Columns list box. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 13

18 Click the >> button to select all columns, or > to select individual columns. You can also double-click a column to move it the Selected Columns list box. Click the << button to remove all items from the Selected Columns list box or click < to remove individually selected columns. You cannot remove columns prefixed with the asterisk markers. When the selected columns are generated into the project, the binding statements are in the same order as you defined them. Also, controls that are being created use the same order. The Application Wizard provides no way of changing the order after you make your selections; however, where this is important (for example, in a Data Sheet project), you can alter the order in which the data is bound to the grid columns by changing the Bind statements in the BindForm or BindDetail procedures in the generated project s form module. You must also alter the constant definitions for the columns in the Declarations section of the form module. The numbers assigned determine the ordinal position of the columns in the grid. The constants have kcol as the prefix to the table column names, for example, kcolvendid. Natural Key The Natural key is obtained in the following manner: The Application Wizard calls the stored procedure spgetuniquekey. If this returns any columns, they are used as the Natural key. The Application Wizard then queries tsmdatadicttbl for the Natural keys defined for the table. The query that produces the larger number of columns becomes the Natural key. LookupID This is obtained by calling the stored procedure spdddataselect with the table name. If this does not return a LookupID, tsmlookup is queried. If both of these queries fail to find a LookupID, the Application Wizard builds a Simple LookupID using the IDColumn for the name and a suffix to identify the LookupID s owner. To identify the LookupID as belonging to your company or organization, tsmsdkinfo is queried for the value of the CompanyCode column. If tsmsdkinfo does not exist (because the Ranges utility has not been run) _AVT is used as the LookupIDs Company Suffix. The Company Suffix is appended to the column name and the name is truncated if it is too long before adding the suffix. If the name has already been used, numbers are used to make the ID unique, further truncating the name if necessary. You need to alter the Lookup definition using the Lookup Definition utility. A simple LookupID, however, allows the new task to build, run, bind to data, and navigate between rows. Not all project types need a LookupID. The wizards do not create Lookups for Blank Project, Single Row Maintenance, Report, and Data Sheet. If a Lookup is not required, no attempt is made to find or make one. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 14

19 Order By This is, by default, the same as the Natural key and cannot be changed during the wizard session. If the Natural key has been defined using a Clustered index, the Order By clause must not be changed. Doing so causes SQL Server to create a temporary table, thus limiting performance. Specifics This section details the different requirements of the project types at this step. Blank Project Blank Project tasks have no data binding. This step is not available for this project type. Single Row Maintenance No Lookup control is required for this type of project. The Application Wizard preselects the IDColumn, *ID*. The Application Wizard preselects the Primary key ( *SK* ). Multi Row Maintenance This type of project must have a Lookup. The Application Wizard preselects the IDColumn, *ID*. The Application Wizard preselects the Primary key ( *SK* ). Data Sheet No Lookup control is required for this type of project. The Application Wizard preselects all of the Natural key components (required by the Grid Manager). These contain the markers *ID* and *UK*. The Application Wizard preselects the Primary key ( *SK* ). S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 15

20 Step 4 - Review Choices The Application Wizard session concludes by presenting the information collected. You can view the information; however, you cannot make any changes. Click Back to return to previous steps to make any changes. To exit the Application Wizard session and build the new project, click Finish. If errors are discovered during the project generation process, they display in a window. These errors fall into three categories: Failure to reference a control or object because it is not correctly registered Failure to locate Common source code because the relative path to..\src\app\common\ cannot be found Other miscellaneous errors that are raised by the Application Wizard or Visual Basic during generation If the problem is a control or object registration problem, you can retry the build process without having to repeat the Application Wizard session. From the Add-Ins menu in Visual Basic, select Sage ERP MAS 500 Repository > Load Project Definition. Browse the choices and select the AAW file. This window defaults to the last Application Wizard file that was generated. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 16

21 Example of the Print To Do List window After building the project, the ToDo list appears if no errors were detected. Use this information as a guide. Click the Print button to get a permanent record, as this window does not display again. Example of a Data Sheet project The data sheet shown on page 17 was built using the example information processed in the previous pages and demonstrates the following intent and goals: Build a new project without reporting errors during the generation process Compile in Visual Basic without errors Register the project with Sage ERP MAS 500 Launch and run the task (when registered) from the Sage ERP MAS 500 Desktop Save and edit data Insert and delete rows S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 17

22 There are caveats to this; however, and these relate to the database table(s) to which the task is bound. During the wizard session, you can select as many or as few columns as required. If any columns are not selected into a project, they have required values that are not defaulted and cannot be NULL, and there is no Trigger to obtain the data, then such an application cannot insert rows, and cannot make updates. This may be a valid situation as deriving these values may be part of the application s business logic that the Application Wizard does not have the intelligence to code. Control Types and Data Types The Application Wizard determines what controls are appropriate for each of the selected columns. If the columns are to display in a grid, this becomes the Grid Cell Type defined in the Data Dictionary. If a discrete control is required, as in Multi Row Maintenance, the Application Wizard determines which control is appropriate and defines the control s ProgID for the column. The Application Wizard also provides an appropriate name for the control using a control type prefix (such as, txt, lku, and dat) and the column name from the table. The algorithm for this decision is shown in the following table and involves an analysis of the column s Data Dictionary properties, Data Type, and its DomainID. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 18

23 Data Dict. Property IsStaticList LookupID <> IsNaturalKey IsForeignKey DomainID Data Type Control SOTADropDown TextLookup TextLookup TextLookup SQL_DATE SOTACalendar MINORENTITYID ACCTSEGVALUE YESNO AMOUNTHC AMOUNTNC AMOUNT TextLookup TextLookup CheckBox SOTACurrency SOTACurrency SOTACurrency SQL_NUMBER SOTANumber WARNING Prior to generating a new project using the procedure described in this section, ensure that any project presently loaded in Visual Basic has been saved or abandoned as required. This procedure forces you to save any currently loaded project prior to generating any new projects. It is safer if you begin with a new project that has not been altered. Default SOTAMaskedEdit The analysis is performed in the same order as the items shown in the table such that a column with DomainID YESNO is hosted in a SOTADropDown if the Data Dictionary property IsStaticList is 1. If no conditions are met the default control is SOTAMaskedEdit. Line Entry projects contain a child table that may have some identical column names to those in the parent table. Child table control names are given the extra prefix: Child, for example, txtchildvendorname. Building the Project This section describes how to build a Sage ERP MAS 500 project using a Project Definition file created by the Report Wizard. Load A Project Definition File Normally, a new project is built immediately after the Application Wizard session finishes. There are times; however, when you may want to repeat the last project build (or any other that has a.aaw file) From the Add-Ins menu in Visual Basic, select Sage ERP MAS 500 Repository > Load Project Definition. Use Windows Explorer to locate the required AAW file. Select the file. During project generation there will be periods of apparent inactivity; at other times, the UI generator and code generator display. The process is complete when the To Do List displays. You can print this list, if required. When you close this window, the project has been built. Follow the instructions in the To Do List to complete the project. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 19

24 Line Entry Application Wizard This section assumes that you are already familiar with the general concepts of application wizards. The following description details only the specifics of the Line Entry Application Wizard. 1. Enter the project information for the new task. For more information, see Step 2 - Project Details in the Application Wizard section. 2. Select the parent table from the Parent Table Columns combo box. The table is selected and the available columns list box is populated when the combo box loses focus. Select the columns required for the header that will be placed on Tab 1 of the Line Entry Tab control. The wizard creates a Lookup control that is placed on the form (not on the Tab Control) and that is bound to the IDColumn of the parent table. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 20

25 3. Select the child table and columns from the Child Table Columns combo box. Select the child table to use for the new task. The Child Table drop-down list only lists those tables defined as being children of the selected parent table. Child tables are determined by querying tsmdatadictrelatn. Use the Data Dictionary to set up a parent/child relationship to use in a Line Entry project. Select other child columns that are required to be bound by the detail table Data Manager. You can define the Order By column by selecting it in the Order By drop-down list. The ParentLink defined for the child table is the parent table s Primary key and the corresponding Foreign key in the child table. The table tsmdatadictfk defines the Parent Link columns. 4. Review your choices. Examine the details for the new project and click Back to make changes or click Finish to generate the project. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 21

26 After the project is successfully created, the ToDo List appears. Example of the Print To Do List window Example Projects Blank Project Example of a Blank project with no additional components S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 22

27 Single Row Maintenance Example of a Single Row Maintenance project using a tab control to contain bound controls Multiple Row Maintenance Example of a Multiple Row Maintenance project with all controls placed on the form Data Sheet Example of a Data Sheet project with all data bound to the grid S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 23

28 Line Entry Example showing the controls on the Header tab Example showing the controls on the Detail tab S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 24

29 Report Wizard The Report Wizard is similar to the Application Wizard. Its purpose is to create an Application Wizard definition file (.AAW) that is used to build a new report project inside Visual Basic's IDE. The wizard collects information about the project, and upon completion, creates the file in the location specified for the project files. Starting the Wizard To start the Report Wizard, open Visual Basic. From the Visual Basic menu, select Add-Ins > Add-In Manager. Select the Sage ERP MAS 500 Repository check box and click OK. Then, select Add-Ins > Sage ERP MAS 500 Repository > Report Application Wizard. Perform the following steps: 1. Enter the project details. Application Title Type the name for the report form. Do not type the frm prefix. This prefix is added by the Report Wizard. The form s name is used elsewhere to create other names in the code that do not require the prefix. Project ID Type the project s name, such as CIZRY001. Module Type the two-letter module abbreviation, such as AP or AR. Form Caption Type the caption that appears on the form. Stored Procedure Type the name of the stored procedure that is used to obtain data for the report. Default Report Type the name of the SAP Crystal Reports.rpt file. The Report Wizard does not create the report file; it only references a report file of that name in the generated code. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 25

30 HTML Help Select this check box if the project uses HTML Help (available only if the module selected is not a Sage delivered module). For SDK developed modules, you have the option to use WinHelp or HTML Help. Project Location Use the Drive and Directory controls to point at a directory to store the new project. 2. Select the available tables. Select tables from the Available Tables list box and move them to the Selected Tables list box using the > (Add) button. You can also double-click a table to move it to a new location. To remove tables from the Selected Tables list box, select the table(s) and click the < (Remove) button. You can select any table in the Selected Tables list box and move it up or down in the list box by clicking the Up and Down buttons. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 26

31 3. Sort/select the columns. For each table selected in the previous step, define the Select and Sort columns to use. Sage ERP MAS 500 s Data Dictionary provides the default report columns that are used if no columns are selected. The columns shown in the Sort/Select list boxes are prefixed by *. Tables Select a table from this drop-down list to view the fields it contains. The fields display in the Available Columns list box. Available Columns Select the columns required for the report and use the appropriate > (Add) button to move them to the Sort or Select Column list box. Columns added in this manner have the + prefix denoting that they are not defined as Sort or Select columns in the Data Dictionary. Sort Columns/Select Columns These list boxes display the columns that have been selected for the report. You can arrange the items in either list box by clicking the Up and Down buttons. You can remove columns from a list box by clicking the associated < (Remove) button; however, if a column is defined in the Data Dictionary as being a Sort or Select column, you cannot physically remove them using this window. You can only change the * prefix to -, which is required by the code generator to override the automatic generation of these columns. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 27

32 4. Select the work tables for the report. Provide the names of the work tables for the report project to use. Type a table name in the Work Table text box and click Add to add it to the list of work tables. To remove a work table, select it in the Work Table list box and click Remove. 5. Select the Key columns. The Code generator needs to know which column in each real table is the Key column. Select each table from the Tables drop-down list and select the Key column in the Available Columns list box. The selected field appears in the Key Column field. Tables This list contains the tables that were selected in step 3. Select a table from this list box in order to identify its Key column. Available Columns This list box displays the column names for the currently selected table. Select the Key column for the table. The column name appears in the Key Column field. To change it, select a different column. Key Column This field displays the currently selected Key column for the currently selected table. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 28

33 Temp Table This field displays the name of the temporary table that the report project uses. 6. Enter the report options. This step determines the elements that appear on the Options tab of the report form. Format If you select this option, a Format frame is created on the Options tab containing the Summary and Detail check boxes. Message Required If you select this option, a Message frame is created on the Options tab containing five message lines. Include Option Any entries you enter in this option create an Include Options frame on the Options tab. Each item you enter creates a check box inside that frame with the text entered appearing as the check box s caption. Add After typing the caption in the Include Option field, click Add to add the new item to the list. Remove To remove an include option entry, select it and then click Remove. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 29

34 7. Review your choices. In this step you can review the choices made in the preceding steps and, if necessary, go back to make changes. Tree View The tree view presents the information used to build the project. Click any node to expand the branches to view the data items. You cannot use the tree view to make changes. Finish Click Finish to create the Application Wizard file. The file uses the same name as the project name with an extension of.aaw. This file is stored in the location defined in step 1. To build the project created using this wizard, select Load Project Definition from the menu, browse to the project definition file, and click OK. To load the project into Visual Basic, see Building the Project below. Building the Project This section describes how to build a Sage ERP MAS 500 project using a Project Definition file created by the Application Wizard or the Report Wizard. Loading a Project Definition File To build the project created, from the Visual Basic Add-Ins menu, select Sage ERP MAS 500 Repository > Load Project Definition. Next, browse to the project definition file, and click OK. Use Windows Explorer to locate the required AAW file and select it. You are prompted to confirm that you want the project generation to proceed. If you click Yes, the project is built. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 30

35 WARNING Before generating a new project, ensure that any project loaded in Visual Basic has been saved or abandoned as required. This procedure will force a save of any currently loaded project before generating a new project. It is safest if users start with a new project that has not been altered in any way. During project generation, you might notice periods of apparent inactivity; at other times you will see the UI generator and code generator working. The process is complete when the To Do List displays. You can print this list, if required. Error Rigging WARNING The Error Rigging engine is supplied on an as is basis and is not yet supported. We welcome and appreciate your comments and feedback on any problems or anomalies found. Example of the Print To Do List window When this window closes, the project is built. Follow the instructions in the To Do List to complete the project. Error Rigging is an automatic process that generates the standard Sage ERP MAS 500 error handler code. Error handler code varies according to the type of module and the type of procedure. Sage ERP MAS 500 Repository provides methods to manage Error Rigging using the following strategies: Rig or unrig an entire module Rig or unrig procedures by type (Sub/Function; Event; Property) Rig or unrig selected procedures (multiselect from a list box) The Error Rigging features apply only to the current module s code window. At this time there is no way to rig an entire project using this tool. The code generated conforms to the standards of the version 4.0 product (then called Acuity) using the VB5.X methodology and is hard-coded in Sage ERP MAS 500 Repository. There are three important considerations when using this tool: Avoid unintended rigging/unrigging Ensure that the main class module for an application is identified to the Rig engine Protect individual procedures from the rig process These consideration are discussed in more detail in the following sections. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 31

36 Error Rigging User Interface To start Error Rigging from the Add-Ins menu, select Sage ERP MAS 500 Repository > Error Rigging. Example of the Error Rigging Window Rig Style Sage ERP MAS 500 Select the Sage ERP MAS 500 (for ALL Sage ERP MAS 500 Projects) option, which is the default, without exception for any Sage ERP MAS 500 module. Generic For non-sage ERP MAS 500 programs, the Generic style generates a simple error handler that displays a message containing the module name, procedure name, and error description. This style may not be used for Sage ERP MAS 500 modules. Rig Targets All Rigging or unrigging is applied to all procedures, properties, and events in the current module. The Error Rigging process does not affect any procedures that have Custom Error Handlers, or that contain the following line of code: +++ VB/Rig Skip +++ Selected Types Rigging or unrigging is applied to the selected types: Subs and Functions Events Properties Selected Procedures This selection displays a list box containing all of the riggable procedures in the current module. Select one or more procedures to rig or unrig. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 32

37 Prompt before Rigging/Unrigging If you select this option, you are prompted for permission to process each procedure selected during the Rigging or Unrigging process. If you clear this option, all selected procedures are processed. Be aware that there is no way to cancel the process after it is started. Apply Click Apply to begin the rigging process. Rigging is only applied to selected procedures that have no Error Handler code. Any procedure that has an error handler is skipped. You can place the following line inside any procedure that you never want to be rigged: +++ VB/Rig Skip +++ If you want standard error handling, do not modify any of the code that is generated by the Error Rigging process as it may cause the code to be unriggable. If you need to change error handling code, create a custom handler and remove all of the generated comments. Ensure that error handler labels are different than those generated by the rigging process. Remove the following comment lines: +++VB/Rig Begin Push +++ and +++ VB/Rig End +++ Remove Click Remove to begin the unrigging process. Unrigging is not performed on procedures that contain custom Error Handlers. Unrigging is only performed on procedures that have been previously rigged using the Sage ERP MAS 500 SDK. During the unrigging process, the following line of code is added to the Declarations section if the application s Main Class Module is detected: Private Const kbclassismainclass = True This is required so that special rigging code can be applied to the public methods of the module that are used by the Sage ERP MAS 500 Desktop. If this line of code is missing from your application s Main Class Module, it needs to be added before the Rigging process is applied. Exit Click Exit to close the Error Rigging window. Visual Basic 6.0 IDE - Conditional Compilation The Visual Basic 6.0 IDE presents the following problem: When code is excluded because of Conditional Compilation settings, this code is not visible to the Error Rigging engine. To error rig these procedures, you must ensure that they are included by appropriate Conditional Compilation settings. Always verify that you have exposed all of the procedures subject to Conditional Compilation. Ranges The Ranges utility is used to reserve unique ranges for system data you add. If you are creating an add-on package, this utility helps to prevent conflicts with data that is being installed from other add-on packages. S AGE ERP MAS 500 SDK DEVELOPMENT UTILITIES GUIDE 33