[Originally posted 09-27-2021 16:20]

Work Area Support Utility

The Work Area Support utility provides Uniface developers with simple access to file-based version control. It maintains a directory structure (called WorkArea) containing Uniface sources that can be used by file-based version control systems and synchronize changes made in the files and the IDE Repository.

You can access the utility from the IDE user-defined menu items added to the IDE Main Menu ( ≡ ).

Background

Securing source code from loss or damage is a vital part of software development. Today, there are many version control systems available to help developers protect their software and allow them easy access to previous versions of their product sources for maintenance and reference.

The Uniface Development Environment (IDE) uses a database as its repository for storing sources. This offers many advantages but is not a natural fit if you want to use the current file-based version control systems.

The Work Area Support utility bridges the gap between the Uniface Repository and file-based version control systems.

How it Works

To use the IDE with version control systems such as GIT:

Uniface source code needs to be made available as files outside of the IDE's repository.
The Repository and the work area need to be synchronized with each other, so a change in the Repository can be exported to a file, and changes in a file are detected after being imported into the Repository.

The WAS utility does this by:

Monitoring a local work area for changes made by the version control system, or any operating system updates, and reflecting those changes into the Uniface repository.
Monitoring changes made within the IDE by the developer and offering a choice to save the updates into the work area, or revert to the version in the work area.

Installation

The utility consists of two files:

WASListner.exe—monitoring utility, which monitors the work area folder structure for changes, and reflects any updates into the Uniface Repository.
VersionControl.uar—Uniface components.

Copy the WASListner.exe to your Uniface installation's common\bin folder, and the VersionControl.uar to the common\usys (or any other location).

License

In using the utility, you agree to the terms of the LICENSE supplied with the Work Area Support utility.

Configuring the IDE

Add a reference to the VersionControl.uar in the [RESOURCES] section of your ide.asn file. It must be placed before the standard Uniface UAR files. For example:
```
[RESOURCES]usys:VersionControl.uarusys:ide.uarusys:ide_messages.uarusys:ide_classic.uar
```
This enables the Uniface IDE to access the components that supply the utility's functionality.
To add the utility menu to the IDE, add or update the logical IDE_DEFINE_USERMENUS to include the component VC_UPDATED. For example:
```
[LOGICALS]IDE_DEFINE_USERMENUS=VC_UPDATED
```
This adds three new menu items to the IDE's main menu.
Optionally, override the WorkArea folder name using the logical WAS_ROOT_FOLDER in the assignment file. This logical is available for both the Uniface plugin and the WASListener utility - your project's IDE and WASListener should both be configured to use the same location.

Configuring the Listener

The WASListener.exe watches for changes within the WorkArea and replays the actions within the IDE. The WorkArea folder must be a local folder because Windows does not monitor changes to files on a network path.

For each development environment:

Create a shortcut to the WASListener.exe you copied to the Uniface \common\bin folder, and set its command-line parameters as required. For example:

"C:\Program Files (x86)\Uniface 10\common\bin\WASListener.exe" -a "C:\Program Files (x86)\Uniface 10\uniface\adm" -i "C:\Program Files (x86)\Uniface 10\uniface\adm\usys.ini" -f ".\asn\my.asn"
Set the Start in folder to the project root (or leave it blank if the shortcut is located in that folder).

Alternatively use the -p option to set the Start in folder.

WASListener Parameters

Parameter	Description	Default value
`-h` [-- help]	Displays a summary of the available command-line parameters
`-p` [ --project-folder ]	Start In folder. By default, the listener watches the WorkArea folder in the root of the project. You can change the location using this switch.	Current or Start in folder
`-a` [ --uniface-adm-folder ]	Location of the Uniface ADM folder to use, for example. `-a "C:\Program Files (x86)\Uniface 10\common\adm"`	1. ..\..\uniface\adm relative to the WASListerner.exe file 2. ..\common\adm relative to the WASListerner.exe file
-f [ --uniface-asn-file ]	Uniface assignment file to be used by the listener As the WASListener utility will need to share most of the same configuration as the IDE you can use the same asn file as your project's IDE.	1) WASlistener.asn in the local folder 2) WASlistener.asn in the ADM folder 3) u3gl.asn in the local folder 4) u3gl.asn in the ADM folder
`-i` [ --uniface-ini-file ]	Uniface initialization file to be used by the listener

Using the WAS Utility

You can access the utility from user-defined menu items added to the Main Menu ( ≡ ).

WorkArea Export/Revert—displays a list of tracked changes within the Repository so that you can export or revert the changes.
Import WorkArea—import all files from the work area.
Mark all as ready for export—reset the status of all Repository objects as new. This allows you to export the whole Repository into the WorkArea using the WorkArea Export/Revert screen.

When the Workarea Export/Revert screen is first activated, it will complete a setup procedure and create several tables and a view within the Repository.

For the setup procedure to complete successfully, it must have sufficient privileges in the database to create the tables and view.

Click on the WASListener shortcut to run the monitoring executable.

An icon will appear in the system tray (bottom right status) while it is running. If it disappears, you probably have a configuration issue.

You should be able to see WASListener.exe as a running process in the Details tab of the Windows Task Manager.
Start the IDE and choose WorkArea Export/Revert from the Main Menu ( ≡ ).

The first time you open this dialog, all Repository objects are listed. Thereafter, only modified objects are listed.
Click Export on individual items or Export All to export all listed items.

The export files are created in the WorkArea folder (unless you have overridden this location).

Downloads

Uniface 10.4.01 x86/x64

WASListener v2.0.00.zip

Uniface 10.3.02 x86

WASListener v1.1.01.zip

Source code

The WASlistener utility is an open-source community project. To obtain the source code or to get involved with the project, please go to uniface/WASListener (github.com)

Please note, that although this tool is uploaded by the Uniface team, it is made available as-is and is not in any way part of the regular Uniface product. Therefore the rules and regulations for Uniface maintenance and support do not apply to this tool.