Functionality

Introduction to Functionality

menu Business logic > Functionality

Using the Functionality screen, you can develop and test the application's business logic that cannot be modeled. This business logic not only comprises traditional business rules  but also the logic to control the user interfaces, process flows and messages.

The functionality screen consists of six tabs:

• Control procedures - Define the business logic. See 1. Create a control procedure.

• Template - Templates contain the actual source code for the business logic. See 2. Add a template.

• Assigning - For statically assigned business logic, you can assign a template to the various program objects. Parameter values can be specified for every assignment. See 3. Assign a template.

• Deploy - This is where the program objects that use the template are (re)generated and can be applied to the database. See 4. Apply the functionality.

• Unit tests - The place to create, maintain and run unit tests. See 5. Run unit tests.

• Code review - The code review is based on the live code of the control procedure. See 6. Complete the control procedure.

• Validation - This tab shows validation messages regarding the selected business logic.

Functionality

Definitions

Control procedures

A control procedure is a placeholder for a specific piece of business logic. The control procedure describes the business logic, defines where and how it is applied, and shows the development, test and review status of the functionality.

Templates

Functionality is written in the form of code templates, based on the functional description which has been drawn up when modeling the application logic. A control procedure always contains one or more templates.

The code in templates with which the application logic is developed is dependent on the platform that the end product uses. The information available when performing the logic (the context), and the possibilities for each logic concept are almost identical for each platform.

Some points of attention:

• The code groups are often identical to the logic concepts as discussed in this manual. However, it may occur that certain logic concepts are included in different code groups.
• Examples have been worked out in this chapter, in which the end product makes use of a platform that supports Transact-SQL. The way in which the execution context is read out and in which the values are set may differ on the various platforms. However, the information that contains the execution context and the possibilities for the application of logic are practically the same for each platform.

Program objects and items

Every logic concept results in one or more program objects in the end product, which are generated by the Software Factory. When using Transact-SQL for your business logic, these program objects result in stored procedures (for most concepts), triggers (for events), and functions on the database, which are executed by the application tier and user interfaces.

A program object contains one or more program object items. The header and footer items are provided by the Software Factory. The items containing business logic correspond to the custom code templates.

A program object for the project table default concept will look like this:

/* Header, generated by the Software Factory */

create procedure def_project
(
   @default_mode       tinyint,             /* 0 = add, 1 = update */
   @import_mode        tinyint,             /* 0 = regular, 1 = import */
   @cursor_from_col_id varchar(255),        /* trigger column */
   @cursor_to_col_id   varchar(255) output, /* focus column */

   /* column values */
   @project_id         project_id output,
   @project_desc       description output,
   @finished           no_yes output,
   @finished_date      date output,
   @insert_user        user_name output,
   @insert_date_time   date_time output,
   @update_user        user_name output,
   @update_date_time   date_time output
)
as
begin

  /* Business logic to fill finished date when finished is checked */
  
  if @finished = 1 and @finished_date is null
  begin
    set @finished_date = getdate();
  end

  /* Business logic to fill trace columns */

  if @default_mode = 0 /* New record */
  begin
    set @insert_user = dbo.tsf_original_login();
    set @insert_date_time = getdate();
  end
  
  set @update_user = dbo.tsf_original_login()
  set update_date_time = getdate();

/* Footer, generated by the Software Factory */

end

When are program objects generated

If a program object is in some way affected, the generated code is set as 'stale' to indicate it needs to be generated again. For example, in case of new, updated, or deleted assignments, or new, updated, or deleted parameter values.

This is checked during the definition generation and code (group) generation. If a program object does not contain any code, it will always be generated. Once the program object code is generated, it is no longer considered 'stale'.

The Code stale field is set automatically, but its state is visible in the menu Models > Model content > tab Program objects > group Generation.

note

If you are using the Fully controlled strategy in a Control procedure, you need to set generated_code_stale to 1 manually in the code to ensure the program object's code is generated again. In that case, however, using the Staged strategy instead is probably more suitable for the Control procedure.

Example (to be adapted to suit your own situation):

update prog_object
set generated_code_stale = 1
where model_id = @model_id
  and branch_id = @branch_id
  and prog_object_id = [Prog object(s)]
  and generated_code_stale = 0

It is not necessary to empty prog_object_generated_code.

Prefilters for control procedures

menu Business logic > Functionality > tab Control procedure

To get a better overview of the control procedures, the following prefilters are available:

• - Control procedures in development. This prefilter does not show the disapproved control procedures.
• - Control procedures that need to be reviewed.
• - Disapproved control procedures assigned to you.
• - All control procedures developed by you.
• - Hide control procedures that have already been generated.
• - Hide inactive control procedures.

Adding functionality

The step-by-step plan for creating functionality is discussed in the following paragraphs.

For a better overview, the following rules apply:

• Tab Control procedure: When a control procedure is created or edited, the name of the developer will automatically be filled in the Developer field.
• Tab Templates: When a control procedure is in development or in review, and you are not the responsible developer, templates are shown in red.
• Control procedure- or template code for inactive control procedures is shown in grey.

1. Create a control procedure

A new control procedure can be created in the Control procedure tab.

Before you start:

• Check out the Control procedure guidelines.
• As long as the control procedure has not been completed, you can roll back the changes you made. See: Abandon changes in a control procedure.
• When a control procedure is created or edited, the name of the developer is automatically entered in the Developer field. If any questions arise about the development, this directs to the right developer.

To create a control procedure:

menu Business logic > Functionality > tab Control procedure

1. In field Assignment, indicate how this procedure should be assigned: 'Static' or via 'SQL'. It is possible to switch the assignment type of a control procedure: static to dynamic (control procedure code will be added) or dynamic to static (static assignments will be added).
2. Select the Type. This will always be 'Program object item', unless you decide to manage the program objects of a code group yourself.
3. If the Assignment is 'SQL', you can select a generation Strategy. For more information, see Generation strategies.
4. If the Assignment is 'SQL', you can change the Generation order no. Its default value is '100'. Only change it to ensure that the control procedures with interdependencies are executed in the correct order.

See also When are program objects generated.

Settings for a control procedure

2. Add a template

menu Business logic > Functionality > tab Templates

Most procedures have one template for weaving. Hence, the template ID and description can be copied as default from the control procedure. The sequence number determines the default sequence of the program objects. These can still be changed for each program object at a later date.

The source code is subsequently defined in the Code tab of the form.

Adding code to the Template tab

You can write the code directly in the Template tab. It will be displayed as usual with an editor, such as Notepad++ or SQL Server Management Studio. If you prefer to work directly in the editor, you can click on the button next to the code template. A linked editor will open. Changes to the file are automatically reported back to the Software Factory.

When the control procedures or templates are modified, the history is stored in the Software Factory. Several tasks are available to compare these templates and control procedures with the history. It is also recorded when a template is modified and when the source code was last generated.

See also:

• Control procedure guidelines
• Model version specific upgrade scripts

Parameters

A template can have parameters. These are placed in square brackets (e.g., [COL_ID]). When assigning a template to a program object, the parameter is provided with one or more values. If a parameter has more than one value, the line of code containing the parameter will be repeated as many times as there are values.

if @[col_1] = 1 /* checkbox is checked */
begin
  set @[col_2]_mand = 1 /* mandatory */
end
else
begin
  set @[col_2]_type = 2 /* hidden */
end

A parameter value can also be empty and by checking the Ignore if empty check box for the parameter, it can be determined that the source code line, containing the parameter, is not included in the end product.

note

To retrieve the username of the current application user, the Software Factory provides the tsf_user() and tsf_original_login() functions. See also User name.

This method is not supported by Crystal Reports/Crystal Clear, however. In this case the username has to be provided to the report by means of a parameter, filled using a default that uses the tsf_user() or tsf_original_login() function.

3. Assign the template

Templates can be assigned to one or more logic concepts in the Assigning tab.

• To add templates to your upgrade scripts, also read Model version specific upgrade scripts.

menu Business logic > Functionality > tab Assigning

The left column shows all the program objects available for the selected concept. After selecting a program object, the contents of the program object (program object items) are displayed on the bottom right.

1. Execute the Assign task to assign it to the program object.

Logic concepts can be disabled through the settings found in tables, tasks, reports and process actions. This applies for default, layout, context and process program objects.

Disabled concepts are displayed in italics. No code is generated for disabled logic concepts and they are not used in the end product. When assigning a template to a disabled concept, this concept will be automatically enabled.

Assigning control procedure templates

A template can be assigned to the same program object item more than once. To do this, the program object item ID of the existing assignment first has to be modified. This can be done in the list of program object items. Also, the sequence of the templates can be changed here by changing the sequence number.

If a template has parameters, these are automatically created on the Parameters tab. An icon on the tab indicates that there are still parameters without a value. If these are not automatically generated, they can still be generated with the Generate parameters task.

Parameter values required

note

When editing templates with an external editor, selecting a different template will disconnect the temporary file that is created from the Software Factory and add the message This file is disconnected to the top of the file. Trying to import template code containing this message will display an error:

4. Apply the functionality

If a new template is woven or a template's source code is changed, you must re-generate the source code and execute the program objects from the control procedure to the database.

• The headers and footers of any program object already present in the Deploy tab will be refreshed automatically when generating the control procedure. In that case, it is not necessary to re-generate the code group for a model change. For example, if a program object is already available for a task, a newly added task parameter will automatically be added to the header when you generate the control procedure.
• If no program object is present yet, the code group still needs to be generated.

menu Business logic > Functionality > tab Deploy

1. To re-generate the source code, execute the task Generate control procedure .

   • While generating a control procedure, you cannot execute program objects (all or selected) and vice versa.
   • If you cancel a generation or execution job, the step that generates or executes the active program object will be finished. Then the job is terminated.
   • To show the generated code, execute the task Show generated item code . You can include the last preceding program object item, or include all preceding program object items, if present. You can also include the first subsequent program object item, or include all subsequent program object items, if present.
   • If generating a control procedure fails, it is almost always due to an error in the code of a SQL-typed control procedure. If no program objects have been created yet, the Program object tab will be replaced by the tab Generation error, containing the corresponding error.
   tip

   To maintain another control procedure or template within the same program object, use the following tasks:

   • Go to control procedure in Functionality - Opens the object in the Control procedure tab in the Functionality screen.
   • Go to Template in Functionality - Opens the object in the Template tab in the Functionality screen. :::

2. Optional: edit code directly in the program object's Code tab or via an IDE .

   For more information, see Code editing.

3. Execute one of the following tasks to deploy the generated program objects to the database:

   • Execute all program objects - Executes all program objects from the control procedure to the database.
   • Execute selected program objects - Executes the selected program objects from the control procedure to the database.

   The Software Factory parses the program object and updates the modified templates automatically.

note

• In the progress bar, you can see whether the generation or execution has been successful. For more information, see Error handling.
• For an overview of the generated session variables, see Generated session variables.

Deploy tab

5. Run Unit tests

menu Business logic > Functionality > tab Unit tests

Create, maintain and run unit tests. See the Unit tests manual.

6. Complete the control procedure

menu Business logic > Functionality > tab Control procedure

Depending on the settings, a code review is required or not to complete the control procedure:

If no code review is required:

Execute the Complete control procedure task to set the status to Completed. If a modification is made to the template or the control procedure, the control procedure will automatically revert to the status of Development.

If code review is required:

Execute the Ready for review task to set the status of the control procedure to Review. It is mandatory to provide a changelog description for tracking purposes. Optionally, you can assign a reviewer immediately.

note

If a control procedure is marked as Ready for review in both branch and origin, a merge conflict may arise. You can select only one to be merged.

The control procedure will show up in the Code review tab, ready to be reviewed. The review will be based on the live code of the control procedure. For more information on the review process, see the Code review manual.

Three tabs are available:

• Code review - an overview of all changed control procedures, also when they are still in development.
• Changes - an overview of every change since the last time the control procedures have been completed. Here you can see which templates are new, updated, or deleted.
• Comments - an overview of all comments on every change in the selected code review record.

note

If, for any reason, the control procedure needs more time in development, execute the task Set status to development to revert the status back to development.

Code review in Functionality

Development and review status

menu Business logic > Functionality

Icons in the Functionality screen indicate the development and review status of control procedures:

Icon	Description
	Currently in development by current developer
	Currently in development by another developer
	Ready for review, developed by current developer
	Ready for review, developed by another developer
	Changes are disapproved, in development by current developer
	Changes are disapproved, in development by another developer

Abandon changes in a control procedure

As long as a control procedure has not been completed, you can roll back the changes you made. It will then revert to the last time it was approved and completed. The trace information is reverted as well, so it looks as if the changes never occurred.

For a control procedure with the Assignment setting 'Static', it is also possible to revert the assignments and parameters.

menu Business logic > Functionality > tab Control procedure

1. Select the control procedure you wish to revert.
2. Execute the task Abandon control procedure changes .

Abandon changes in a control procedure

Generation strategies

menu Business logic > Functionality > tab Control procedure

The following generation strategies are available for SQL control procedures and in the Dynamic model:

• Delete: All objects generated by this control procedure will be dropped during the Generate definition process and then re-created by the control procedure. See also When are generated objects deleted.
• Fully controlled: All objects generated by this control procedure will not be dropped during the Generate definition process. This strategy means the developer has to manage all the objects generated by this control procedure. So, previously generated and outdated objects need to be deleted by code, if necessary.
• Staged: All objects generated by this control procedure will be either updated, inserted, or deleted based on the object data. If any data has changed, the object will be updated. If no corresponding object is found, a new object will be created. If an object is found but no corresponding data is present, the object will be deleted. See also Managing code generation with staging tables.

Default strategy in control procedures

menu Business logic > Functionality > tab Control procedure

The Staged strategy is recommended because of all its advantages, such as performance.
This strategy uses temporary tables similar to the program object tables but much smaller. The Software Factory will identify and apply changes between the temporary tables and the actual program object tables. Records are only inserted, updated, or deleted as needed. This makes the process more efficient than deleting and recreating all program objects.

• For new SQL-typed control procedures, the default strategy is Staged.
• If you change the assignment to 'SQL' (using the task Switch assignment to SQL ), the strategy will also be automatically set to Staged. The generated SQL code will automatically use the correct staging tables.

Managing code generation with staging tables

Code generation during the Generate definition, Generate code groups, and Generate source code processes can be managed with several strategies. The Staged strategy manages the mutations of the program object and program object item tables by temporary tables. It looks to see if anything is new, changed, or removed. This strategy will fit most SQL-typed control procedures.

It uses temporary program object tables to insert, update and/or delete program objects. The Software Factory creates these temporary tables, and the developer can use them. In SQL-typed control procedures, the developer can insert data into the temporary tables, and the Software Factory processes the data.

Note:

• The temporary tables are almost equal to the permanent model versions. The difference is that they do not contain the model_id, branch_id, and control_proc_id columns, because they are always in the context of one branch/control procedure.
• The selected and prog_object_generated_code columns for program objects are not present as these are not handled in the Generating definition process but in the Generate source code process.

The created temporary tables have the following table structure:

Table #prog_object

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
prog_object_type_id	varchar(100)
tab_id	varchar(100)
task_id	varchar(100)
report_id	varchar(100)
process_flow_id	varchar(100)
process_action_id	varchar(100)
subroutine_id	varchar(100)
code_file_id	varchar(200)
order_no	int
prog_object_file_spec	varchar(1000)
prog_object_status	tinyint	No		0

Table #prog_object_parmtr

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
parmtr_id	varchar(1000)	No
parmtr_value	nvarchar(4000)
order_no	int	No
no_line_when_empty	bit	No		0

Table #prog_object_item

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
prog_object_item_id	varchar(1000)	No	X
order_no	int	No
template_id	varchar(100)	No

Table #prog_object_item_parmtr

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
prog_object_item_id	varchar(1000)	No	X
parmtr_id	varchar(1000)	No
parmtr_value	nvarchar(4000)
order_no	int	No
no_line_when_empty	bit	No		0

Model version specific upgrade scripts

It is possible to add templates to your upgrade scripts when upgrading to a new model version. This can be useful when, for example, a data correction is necessary during a specific part of the upgrade process.

note

Use the Data migration functionality for simple scenarios, where records are moved from one table to another or columns are filled using default values.

To add templates to the upgrade:

menu Business logic > Functionality

1. Create a control procedure with code group Upgrade.

2. The Assigning tab lists the program objects that will be run before, during, and after the Upgrade code file for each available model version, as well as a program object for every model version. Here, assign your templates to the Upgrade program objects. See 3. Assign the template. The code will be weaved into the correct position and executed during the next upgrade.

   You can place custom scripts in various stages of the upgrade process. The stage depends on the program object to which a template is assigned:

   Program object	Stage
   ug_before_upgrade_from_[x]	Before any upgrade code from model version [x] has been executed.
   ug_during_upgrade_from_[x]	After the data migration from model version [x] has been done but before the old tables are dropped.
   ug_after_upgrade_from_[x]	After the old tables from model version [x] have been dropped when upgrading.

   Model version [x] in the program object name corresponds to the configured source model version. Because of this, the template will only affect this specific upgrade.

   If a code needs to be run before, during, or after every single upgrade, you can use one of the following program objects instead:

   Program object	Stage
   ug_before_upgrade_always	Before any upgrade code has been executed.
   ug_during_upgrade_always	After the data migration has been done but before the old tables are dropped.
   ug_after_upgrade_always	After the old tables have been dropped.

   When using a template during the upgrade, you can refer to the old tables using __[tab_id]__.

If no model version-specific program objects are available, make sure the model version is marked to use upgrade logic.

To mark a model version to use upgrade logic:

menu Models > Model overview > tab Branches > tab Model versions

1. Select the Use upgrade logic checkbox. See also Use upgrade logic. To keep the list of upgrade program objects manageable, clear this checkbox for older model versions.
2. Make sure that the model version has a Description. This will be used in the name of the generated program objects.

tip

Model versions of direct and indirect origin branches (menu Models > Model overview > tab Branches > tab Form > group Merging) can be included as well. Select the Use upgrade Logic checkbox for a specific model version in the origin to make its program objects available in all branches based on this origin. If Use upgrade Logic is not selected for a model version in the origin, its program objects will not be available in the branches. This way, you can add upgrade scripts that can be used and re-used in FEATURE and DEVELOP branches.

Model version specific upgrade scripts

Code editing

This topic describes how the Software Factory processes the code that you add to or change in the Functionality screen.

menu Business logic > Functionality > tab Deploy

1. If necessary, edit code directly in the program object's Code tab or via an IDE .

Take the following rules into account when editing code:

caution

Do not attempt to 'rename' a control procedure or template by editing existing comment blocks. This will insert a new control procedure or template instead.

• Code is scanned for the following comment blocks. Note that the indentation has to be consistent:

  --control_proc_id:      default_fill_address
  --template_id:          fill_address
  --prog_object_item_id:  fill_address
  --template_description: Fill in the default address
      
  select @address_id = address_id
  from address
  where ...

  Do not change the order or omit lines in the comment block:

  • If you omit the first line of the comment block, the program object item that is represented by it will not be detected. It may be ignored or get appended to a previous template.
  • Omitting any other lines of the comment block will cause an error when saving.
  • Duplicate program object IDs in comment blocks will cause an error when saving.

• New control procedures will be created automatically when the comment header block refers to a nonexistent control procedure.

• Templates will be created and updated as follows:

  • New templates will be created automatically when the comment header block refers to a nonexistent template. However, this will fail when the appointed control procedure already exists as a generated, dynamically assigned, or disabled control procedure.
  • Update - You are only allowed to update template code for non-generated, static-assigned templates without parameters. Code changes to templates for control procedures with other types than 'Program object item' will be ignored. It is not possible to update a program object header or footer.
  • Description - Be careful when updating template descriptions. If you change the comments of multiple assignments, but accidentally introduce inconsistencies, the resulting change will be arbitrary. Multiline template descriptions can be used and updated. Note how these are formatted to prevent them from being appended to the template code.

• You are only allowed to add or remove template assignments for non-generated, static-assigned templates without parameters.

  • New - New template assignments will be added automatically. You can create additional template assignments by copying the entire code block representing the program object item and providing a new prog_object_item_id in the new comment block. When you use an existing template for a new template assignment, the code of this template will be updated if needed.
  • Remove - You can remove template assignments by removing the entire code block representing the program object item. After the last remaining template assignment has been removed, the template will be deleted. Note that a control procedure will never be automatically deleted. Removing the last template assignment of the current control procedure in the Functionality screen will also remove the program object from the list of relevant program objects.
  • Reorder - Reordering template assignments is only possible for non-generated, static-assigned templates. Static template assignments will be reordered automatically when code is shuffled or when a new template assignment is added. You can also reposition static parameterized program object items. However, relative repositioning of dynamically assigned templates to one another will result in an error.
  • Multiple assignments - When a template is assigned more than once and receives different code changes per assignment with the new code, updating will fail. When it is assigned more than once and receives a code change, this will cause changes to the other assignments, both within the same program object and other program objects.

• Editing program object code has the following limitations:

  • Editing only works if the program object only has a header and a footer. You will be warned if you try to import code with (for instance) a try-catch block, transaction block, or auto-generated code, such as default view code or default handler code.
  • Editing only works if the program object uses a logic code group that supplies the correct comment block used for code comparison and template identification.
  • Editing does not support program objects not aimed at logic, such as program object types DB_CREATE and UPGRADE.

Error handling for generation or execution

If you have woven a new template or changed the template source code, you need to re-generate the source code and execute the program objects to the database.

In the progress bar, you can see whether the generation or execution succeeded or failed.

With prefilter Failed (ALT+F, you can filter program objects that have failed or are still running.

To find the cause of the problem:

menu Business logic > Functionality > tab Deploy

• When the generation of a control procedure fails, it is almost always due to an error in the code of a SQL-typed control procedure. If no program objects have been created yet, the Program object tab will be replaced by the tab Generation error, containing the corresponding error.

  A generation error explained

• When the execution of a program object fails, it is almost always due to an error in the template code. The program object code field is shortened to make room for another one with the corresponding error.

  Explanation of an execution error