Roundtable Total Software Management System

Configuration identification is simply the identification of a relative arrangement of software system components. An important part of configuration identification is the realization that a software project is comprised of much more than source code. A software project might include:

The configuration identification framework must provide an intellectual and mathematical basis for describing the relative arrangement of these system components at a specific point in the development process. Over time, software systems undergo an iterative, incremental evolution that can be described as a series of baselines. The following table lists some commonly used SCM baselines. The terms provide a good starting point for a discussion of which baselines a given product development effort needs.

The following table lists system components and indicates the baselines with which they are usually associated:

Your system may require more or fewer baselines, and some of the system components belong in different baselines. Your objective in identifying a baseline is to define what should be in the system at a given point in time.

Baselines are often incorrectly referred to as milestones. However, milestones identify points in the project schedule where you reach specifically identified goals. Often, there are many project milestones within each project baseline. Configuration auditing is the process of ensuring that a system does contain everything implied by its baseline status.

1.3.1.1. SCM and the Development Cycle

Early SCM efforts saw the waterfall development cycle entrenched in the policies, procedures, and tools used to implement the SCM discipline. Modern software development incorporates an iterative development process that includes rapid prototyping, JAD sessions, and component-oriented system construction. These and other factors make the waterfall development cycle a poor model around which to construct project- and software-management policy and procedures. If SCM is to be a natural and intuitive part of the software development process, its policies, procedures, and tools must accurately record and model the activities of the process. The SCM discipline must support iterative development and the management of parallel activities.

Iterative development involves the incremental improvement of a baseline through a series of measure, cut, and fit cycles. The underlying theory is that it is not possible to completely define the problem domain of a given application without the experience of trying to build some parts of it. Design methodologies are based on the concept of decomposition. You must break down a large system into smaller parts in order to understand the relationships of objects in the problem domain.

The relationships of components in a complex software system are not always obvious until the development process is underway. Changes in system design often occur as a result of issues that surface during the development process. Often, decision makers for a project are not technically oriented and can be reluctant to make decisions based on design abstractions. Instead, they want to see major portions of the system functionality surfaced before they make these decisions.

Roundtable provides an answer to this iterative development process by allowing multiple instances of the software system to exist concurrently. These instances are called workspaces. These workspaces support an incremental development cycle that is fully controllable under the SCM disciplines.

Refer to the three workspaces in the following diagram:

The arrows indicate a flow of new and updated system components from workspace to workspace. This flow is controlled by you, the developer, and generally occurs when a self -consistent set of changes is completed in one workspace and is ready for importation into the next (target) workspace. The important issue in this promotion of changes from one workspace to another is that all modified components are promoted together as a unit, and that comprehensive documentation of the impact of the modifications on the target workspace is available.

A workspace is defined primarily by its use, while a baseline defines the expected content of a workspace. Because you are in control of how many workspaces exist in your development environment and how they are used, Roundtable has no strict rules regarding the relationship between workspaces and baselines. However, here are some general guidelines based on the simple workspace example previously shown:

• Development workspace — Primary development area

• Functional baseline

• Allocated baseline

• Design baseline

• Test workspace — Primary testing, limited changes (mostly bug fixing)

• Alpha baseline

• Beta baseline

• Pre-prod workspace — Primary deployment

• Production baseline

In some environments, there is a tendency to think of the Test and Pre-prod environments as builds of a system. This approach is clumsy and less than satisfactory for larger development efforts as it precludes the opportunity for maintenance or emergency patch activities in any workspace except Development. If there is significant change in the development environment after the build that represents the Test workspace, it may not be possible to produce a patch for the test environment in a timely way.

Roundtable provides extensive support for identifying potentially dangerous concurrent changes to software system components in different workspaces. This conflict is called orphan change management. For more detail, see Section 4.7, “Object Variants”. This support for orphan change management allows parallel development to occur in two or more workspaces simultaneously with an appropriate level of control and visibility.

Your business model drives your decision to allow changes outside the Development workspace. Consider the following situation.

You oversee the development of an in-house MIS system of significant size. Management demands that some, but not all, of the system become operational as soon as possible. Your team members code these early deliveries first and promote them from the Development workspace into the Test workspace, where testing begins.

In the meantime, programmers working on the new system components make changes to some of the previous components to accommodate the interface and shared-data requirements.

In the Test workspace, the testers discover bugs and other problems in the system components. The programmers, working on the system in the Development workspace, inform you that while they can make the changes requested by the testers, they cannot deliver the changes into the Test workspace because the system components in question have been modified to work with the new system components. However, management still wants the system components that are in the Test workspace.

This situation presents a compelling argument for making the bug fixes and required changes in the Test workspace. The Roundtable orphan change management functionality makes this possible with minimum risk.

Parallel development occurs when there are many variations (or flavors) of a system. For example, a core business system might be modified for different clients or for vertical markets. Roundtable maintains each variant in a separate workspace and manages the promotion of code.

A later section in this chapter addresses more advanced issues of workspace management for a variety of situations.

1.3.1.3. Configuration Hierarchy—Product Modules and Workspaces

Configuration identification of a system involves decomposition of the system into smaller, more manageable, modules. Roundtable supports the mapping of a logical configuration hierarchy to a physical configuration hierarchy.

The logical configuration hierarchy is the hierarchy of the objects in the repository. Each object belongs to a product module, and each product module belongs to a product. This defines a three-level, logical view of the object stored in the repository:

• Product

• Product module (one or more per product)

• Object (one or more per product module)

The logical configuration hierarchy provides a way to define the logical relationships of objects quickly. It also serves as a form of documentation for your system design. Generally, it is a good practice to define your product modules along the functional boundaries of your system. For example, if you develop a general accounting application, you may have product modules for general ledger, accounts payable, and accounts receivable.

The physical configuration hierarchy is the definition of workspace contents, down to the specific directories in which to store objects. Each workspace represents a collection of object versions. Roundtable manages a table of these object versions, called the configuration list. The following fields define the unique key for objects in this table:

• Workspace ID (Wspace-id)

• Object type (PDBASE, PFILE, PFIELD, PCODE, or DOC)

• Object name

In conjunction with the object type and object name above, the following fields are included in the configuration list, allowing the unique identification of the object version contained in the workspace:

• Object Version

• Object Pmod

Refer to the following diagram:

Each entry in the configuration list also specifies a workspace module. Workspace modules map objects belonging to a product module, associated with the workspace module, to a specific directory structure. (The directory structure is always specified relative to a root directory for the workspace.) Each product module is associated with only one workspace module, but many product modules can be associated with that workspace module. This allows objects from multiple product modules to coexist in the same directory if necessary. This functionality allows the effective management of custom systems.

The following diagram illustrates a simple system:

There is a one-to-one correspondence between the workspace module name and the directory name associated with the workspace module. In addition, there is a simple one-to-one correspondence between the workspace module name and the product module name. When you design a new system, you should retain these simple relationships.

The following diagram demonstrates a slightly more complex system:

The subdirectory aprpt contains accounts payable reporting procedures. This example illustrates the need to create a workspace module and product module for each subdirectory in the system.

You might want to map objects that appear in the same physical directory to different product modules. The following diagram shows this approach:

So you can see by these examples, it is possible to map any level of directory structure to workspace modules in the Roundtable environment.

The Configuration Control Board (CCB) plays a central role in the configuration control process. It is often comprised of both buyer and seller representatives and is responsible for making decisions about the changes to be made to the system definition during the course of the project. The CCB approves, monitors, and controls:

To ensure the success of an SCM effort, it is important to adopt a formal SCM plan. A typical Configuration Management Plan contains the following checklist:

There are many good texts on SCM that provide information on how to implement a full SCM plan and define and assign the responsibilities of the CCB. A common-sense approach to implementing a CCB is usually enough, unless the software project is huge or is for the military. For work done under government contract, find out which of the many SCM standards documents the contract requires and implement those standards. The standards cover every phase of the software project life cycle, and even provide sample forms and report formats to facilitate communication during the project.

Configuration auditing is the process of confirming that all system components that should be in a given baseline are in the baseline. The checklists in the next few sections illustrate some of the questions asked during the audit process for sample baselines. When a baseline audit is completed, the baseline is said to be sanctioned. Roundtable provides workspace, product, and task reports that identify the status of each registered component (object). It also provides textual information describing the component and its version identification. Use these reports to address some of the questions on the configuration audit checklists.

Configuration auditing is the mechanism management uses to ensure that a software project is on track and building what is actually required. Some argue that a given software project has so much R&D content that configuration auditing is not useful. This is not the case at all. If the team must use exploratory engineering to refine the product definition, this should usually be done without the overhead of full configuration auditing. However, it is dangerous and foolhardy to commit to the development of a product if its required concepts, design, and implementation strategies cannot be stated at the level of detail required by the configuration audit process.

Configuration status accounting ensures that a complete and accessible record of the changes to a software system and reasons for such changes are available. Most programmers do configuration status accounting without knowing they do it, by keeping a programmer's notebook and inserting comments in the source code. The objective in configuration status accounting is to record why, when, and by whom a change is made. Configuration status accounting is often a reporting function that pulls the required information out of data stores created and managed by the configuration control tools in the SCM system.

Roundtable provides extensive configuration status accounting through the implementation of task and workspace management. Essentially, no change can be made to the software without it being tracked as part of a task in a specific workspace.

Each distributed development group runs its own copy of the Roundtable system and has an independent repository where configuration information is stored. Each repository is identified by a unique site number. A site number of 0 is allowed. It is treated in a special manner and is the default value on first-time installations of the Roundtable system. The site designated with the number 0 is called the central site.

Each additional site in the distributed development network of repositories will have unique site numbers in the range of 1 to 999. A site with a number other than 0 is called a partner site. The site numbers can be assigned in any order but cannot be changed once assigned.

Site numbers are used to provide a unified naming convention for information belonging to each site. This is accomplished by using the site number as a separate key field in some repository tables and by using the site number as a code prefix for other tables. This identification of information by site provides the foundation for the sharing of information among distributed repositories.

Much of the information you place in the configuration repository must be identified by a user supplied code. The format of this code is important and is validated to conform to the following rules:

Using this strategy, the system is able to identify the originating site of each record in the distributed network. The system allows only the originating site to modify a record.

The names of products, product modules, and subtypes are examples of items in the Roundtable system that are affected by site numbering rules.

The system provides the ability to do a special form of deployment to partner sites. Deployments to partner sites include selected repository information dumped to text file format. A utility called the Partner Site Load utility reads this repository information into the partner site repository.

The process of deploying to a partner site is no different that deploying to a customer as discussed earlier, but the type of site must be set to "partner". Partner sites can deploy to other partner sites and to the central site. The central site can deploy to any partner site.

A site receives the deployment package and runs the partner site load utility to update the repository with the new information. The receiving site will usually manage a receipt workspace that represents the latest configuration received. When a receipt workspace is used it must also be updated from the deployment.

Deployments represent the configuration of a workspace at a given release level. A deployment to a partner site is comprised of two components:

A receipt workspace is a read-only copy of the workspace that exists at the sending site. It cannot be altered at the receiving site. However, information can be imported from the receipt workspace into a local workspace. Importing objects from a receipt workspace into locally managed workspaces is performed by the import process.

Many vendors provide source to customers so that the customer’s development staff can enhance and extend the vendor's application. When the customer also has the Roundtable system, it is possible for the vendor to deliver partner site deployments to the customer. Partner site deployment facilitates the integration of application upgrades to the customer in a controlled and managed way. Refer to the following diagram:

As the vendor develops new enhancements to the Sports product, they are delivered to the customer as partner site deployments. Partner site deployments contain both repository information and the normal remote site update package.

At site 1, the customer imports from the Sports Ver1 workspace into the 001Devel workspace. Where necessary, the customer can replace objects in the application with customized objects (variants) to modify the vendor’s application. These custom objects are protected from overwrite in future importation processes. The customer can also extend the functionality of the application by adding new objects to the application.

The diagram shows the vendor's application deployment workspace with a name of Sports Ver 1. This is done to emphasize that the releases received by a remote site in this manner are usually incremental releases, often called dot releases. When a vendor wants to distribute a new major version of a software application, it is sometimes necessary for both the vendor and the customer to manage a legacy system for a period of time. The following diagram shows how this might be done:

In the preceding diagram the new Sports Ver 2 application is delivered to the customer in a new receipt workspace, and the workspace promotion strategy is changed at the customer’s site to do integration and development with the new application. Legacy systems generally require minor maintenance and modifications, and this can be done in the 001Test workspace. The major work of integrating the new functionality of Sports Ver 2 is performed in the 001Devel workspace.

When the integration of the new system is completed, the legacy system can be dropped as shown in the following diagram:

In the preceding section you saw how it is possible for an application system to be delivered into a receipt workspace at the customer site. Objects are then imported from the receipt workspace into the customer's development workspace. Note that the customer can replace objects in the application system with custom objects (variants) as required in the development workspace without fear that these will be overwritten during future imports.

This protection from overwrite is accomplished by creating custom products and product modules that belong to the customer site. The new objects created to replace an object in the vendor's application are created under a product module belonging to the customer’s site. The import process will not overwrite an object in the target workspace when the object’s product module is different from that found in the source workspace. This protects the custom objects from being overwritten.

To replace an object with a custom object in the application:

1.10.5.1. Distributed Development Scenario # 1

One simple form of distributed development occurs when a single organization has two development sites that cannot be connected to a central configuration repository. For this example, assume that a cooperative software development effort is pursued by two development teams separated geographically. Team A is located in India and team B is located in California.

Each team has one configuration repository and one or more workspaces relating to their different responsibilities. The teams have the following responsibilities:

Team A - India

• Primary Development

• Unit Testing

Team B - California

• System Testing

• Deployment to Customers

• Support

The following diagram describes the distributed development process with a workspace network map:

The preceding workspace network map shows six workspaces. The objects in the Devel and Test1 workspaces at site 0 can be modified by the members of team A at site 0. The objects in the 001Test2 workspace at site 0 cannot be modified by team A, Instead, only the partner site load utility can modify the contents of the 001Test2 workspace because it is a receipt workspace. A receipt workspace is always a read-only workspace as indicated by the RO designation in the diagram.

The objects in the Test1 workspace at site 1 cannot be modified by team B. Again, only the partner site load utility can modify the contents of the Test1 workspace because it is a receipt workspace.

The purpose of each of these workspaces is defined by the workflow of the teams:

Workspace	Work Performed
Devel	Primary development area.
Test1	Updates are imported from Devel into Test1. Unit testing is performed in this area. Deployments to the partner site in India are performed from this workspace.
001Test2	Updates are imported from Test1 into 001Test2. System testing and emergency fixes are performed in this workspace. Objects fixed in this workspace begin as a copy of the object imported from Test1. These object copies belong to a product module that is owned by site 1. Deployments for site 0 are made out of the 001Test2 workspace. This makes it possible for the development team at site 0 to see any fixes made to the software application by team B at site 1. By using the visual difference facility team A can identify what changes should be incorporated into the system.
001Ver1	Deployments to create product packaging are made from this workspace.

1.10.5.2. Distributed Development Scenario # 2

A more complex form of distributed development occurs when a single organization has two development sites that cannot be connected to a central configuration repository and primary development is shared. For this example, assume that a cooperative software development effort is pursued by two development teams separated geographically. Team A is located in India and team B is located in California.

Each team has one configuration repository and one or more workspaces relating to their different responsibilities. The teams have the following responsibilities:

Team A - India

• Primary Development Accounting

• Unit Testing Accounting

Team B - California

• Primary Development Operations

• Unit Testing Operations

• System Testing for full system

• Deployment to Customers

• Support

The best way to describe the distributed development process is with a workspace network map as shown below:

The workspace network map above shows seven workspaces. The objects in the Devel and Test1 workspaces at site 0 can be modified by the members of team A at site 0. The objects in the 001Test2 workspace at site 0 cannot be modified by team A. Instead, only the partner site load utility can modify the contents of the 001Test2 workspace because it is a receipt workspace. A receipt workspace is always a read-only workspaces as indicated by the RO designation in the diagram.

The objects in the Test1 workspace at site 1 cannot be modified by team B. Again, only the partner site load utility can modify the contents of the Test1 workspace because it is a receipt workspace.

The purpose of each of these workspaces is defined by the workflow of the teams:

Workspace	Work Performed
Devel	Primary development area for Accounting. Used by team A at site 0. The Operations code developed by team B at site 1 is imported from the workspace 001Test2 into the Devel workspace. Thus the Devel workspace contains the entire system. Members of team A can only modify objects that belong to product modules owned by site 0.
Test1	Updates are imported from Devel into Test1. Unit testing is performed in this area. Deployments to the partner site 1 are performed from this workspace.
001Devel	Primary development area for Operations. Used by team B at site 1.
001Test2	Updates are imported from Test1 into 001Test2. System testing and emergency fixes are performed in this workspace. Objects fixed in this workspace begin as a copy of the object imported from Test1. These object copies belong to a product module that is owned by site 1. Deployments for site 0 are made from the 001Test2 workspace. This makes it possible for the development team at site 0 to see any fixes made to the software application by team B at site 1. By using the visual difference facility team A can identify what changes should be incorporated into the system.
001Ver1	Deployments to create product packaging are made from this workspace.

In Module View, the Object Browse contains objects belonging to the Module selected from the TreeView. By default, Roundtable uses Group codes (user defined values that can be entered for each object) to sort the objects in the Object Browse. You can assign the same Group code to a set of closely related objects so they appear together in the Object Browse.

Follow these steps to use Module View.

The Object Browse contains the following fields:

The Task View fills the Object Browse with objects belonging to the Task specified in the Task drop-down list.

Follow these steps to use Task View.

The Object Browse contains the following fields:

	Completed objects are included in this view based upon user preference.

The Lab View fills the Object Browse with objects belonging to the Lab associated with the Task specified in the Task drop-down list.

Follow these steps to use Lab View:

The Object Browse contains the following fields:

The Roundtable Tabletop includes both xref and where-used views which allow for easy viewing of the relationships between objects in the selected Workspace.

In the Version List View of an object, the Object Browse is filled with all versions of the selected object regardless of the Workspace in which the versions were created. Each row in the Object Browse shows a different version of the object. This makes it possible to quickly review the changes made to the object in all Workspaces.

Follow these steps to use Versions List View.

The Object Browse contains the following fields:

In the Version Ancestry View of an object, the Object Browse lists the object version currently assigned to the Workspace, followed by the ancestry for the selected version - regardless of the Workspace or Product Module in which the ancestor versions were created. The ancestry is displayed in reverse order (the selected version, followed by its immediate ancestor, followed by that version's immediate ancestor, and so forth).

Follow these steps to use Versions Ancestry View.

The Object Browse contains the following fields:

	If the object has been moved from another Product Module using Roundtable 9.1A or later, the versions of the object in the other Module appear in red.

In the Object History View, the browse table is filling with a complete history of each action taken on the selected object in the current Workspace.

Follow these steps to use the Object History View:

The Object History View contains the following fields:

The Backups View fill the Object Browse with backups that have been created for the selected object.

Follow these steps to use the Backups View:

The Object Backups View contains the following fields:

The Informal Object Xref is a cross-reference that shows each informal object used by a selected object. Informal objects include items that are not explicitly tracked as objects by Roundtable.

Follow these steps to use Informal Object Xref.

In the Recent Views List, the Object Browse displays a history of the navigation you have performed in a Workspace through the selection of various views on various objects.

Follow these steps to use Recent View.

Entries are created in the recent list each time you change the current view. The list can contain up to 20 views.

The Spec folder contains the specification of the object version selected in the Object Browse. The specification information includes the object's version information, a brief synopsis of the object's function and the status of the object. The Spec Tab is available for all objects.

For more detailed information, see Section 6.3.1, “Spec Folder Description”.

The Config folder contains the configuration of the object currently selected in the Object Browse. This configuration information determines how operations on the object are handled in the Workspace. This folder is only shown for PCODE and DOC type objects. Most of the fields are not enabled for DOC type objects.

For more detailed information, see Section 6.4.1, “Config Folder Description”.

The Note folder contains the update history note of the object version selected in the Object Browse. Each time you close a file you have modified, Roundtable prompts you for this note. This tab is available for all objects.

For more detailed information, see Section 6.3.3, “Note Folder Description”.

The Task folder contains information about the Task under which the object version selected in the Object Browse was created. This tab is available for all objects.

For more detailed information, see Section 6.3.2, “Task Folder Description”.

The Dbase folder associates a physical database with the PDBASE object selected in the Object Browse. The information in this folder specifies where the database resides and the connection parameters required to connect to the database. The Connect Order field allows you to specify the order in which multiple databases in a Workspace are connected. The first application database connected in a Workspace is connected with the DICTDB alias.

For more detailed information, see Section 6.6.5.1, “Dbase Folder Description”.

The Table folder contains the PFILE associated with the PFILE object selected in the Object Browse.

For more detailed information, see Section 6.6.6.1, “Table Folder Description”.

The Field folder contains the attributes of a field defined by a PFIELD object. This folder is available when a PFIELD object is selected in any view.

For more detailed information, see Section 6.6.7.1, “Field Folder Description”.

From the Tabletop, you can search for any type of object assigned to the currently selected Workspace.

When Roundtable is running, the OpenEdge AppBuilder redirects all of its file open, save, save-as, and close activities to the Tabletop. For example, when you choose File → Open from the AppBuilder menu bar, the Roundtable Open Object window appears as shown below.

Also, the caption of the title bar of the Tabletop window changes to "ADE FILE OPEN". Select an object as described in "Loading an Object into AppBuilder Directly from the Tabletop". If necessary you can check out the object before choosing to open it.

When Roundtable is running, the OpenEdge Procedure Editor redirects all of its file open, save, save-as, and close activities to the Tabletop. For example, when you choose File → Open from the Procedure Editor menu bar, the Roundtable Open Object window appears as shown below.

Also, the caption of the title bar of the Tabletop window changes to "ADE FILE OPEN". Select an object as described in "Loading an Object into a Procedure Editor Window Directly from the Tabletop". If necessary you can check out the object before choosing to open it.

Often, an application includes non-ABL source files. Bitmaps are a good example of this. You must have defined a Subtype that uses an ABL procedure, such as rtb/p/rtb_open.p, to launch an appropriate editor for the file based on the file's extension. This procedure queries the Windows registry to check what application is associated with files having the extension of the file selected and then launches that application against the selected file.

	External applications launched by Roundtable can write changes to the files loaded into them even if these files are not checked out! This can lead to problems for other users in the system and possible loss of the changes made to the file. Do not save changes made to read-only objects in external applications.

The most common way of organizing system components is to group source files by Product Module definitions. This is common because structured design methodologies involve the top-down decomposition of a software application by function. The functional hierarchy translates naturally into a hierarchical directory structure. For example, in an accounting package with an accounts payable Product Module and an accounts payable Workspace Module, your directory structure might look like this:

This simple configuration hierarchy easily maps into the three-level configuration hierarchy provided by Roundtable. The /abc_system directory becomes the Workspace root path and each subdirectory is then mapped as shown below:

Another common way to arrange directory structures is by the types of components found in the system. This organization is typical when many discrete components are reused across functional boundaries in a software application system. A directory structure organized by component type might look like this:

This configuration hierarchy maps into the product and Product Module configuration hierarchy provided by Roundtable, as shown below:

In this mapping, objects that belong to multiple Product Modules coexist in the same subdirectory. If you are developing your system from scratch, do not use this type of directory hierarchy in your application. Instead, use a functional hierarchy if possible.

It often makes sense to combine a functional hierarchical system architecture with one based on component types. A combined directory structure may look like this:

This configuration hierarchy can be mapped into Roundtable as shown below:

If you have an especially complex configuration hierarchy, use Subtypes to model some subdirectory organization rules. You define Subtypes to ascribe attributes to PCODE objects. One of the attributes you can define is a subdirectory in which a file associated with the PCODE object will be stored.

Consider again the directory structure from the previous section:

This configuration hierarchy can be mapped into Roundtable more simply with the use of Subtypes as shown below:

When you create a new PCODE object in a module, Roundtable constructs part of the path to the object based on the Product Module assignment. It then constructs the rest of the path based on the Subtype you assigned to the object. For example, if you created a new data entry program called order.p for the AR Product Module and assigned it a Subtype of EditProc, Roundtable performs the following logic to decide what directory to put it in:

Using Subtypes in this manner can be useful when it is necessary to map an existing configuration hierarchy. However, you should avoid this style of configuration hierarchy because it leads to duplication in the Subtypes. In the example above, there might be no difference between the EditProc and BatchProc Subtype specifications except for their associated subdirectories.

For more detailed information on Subtypes, see Section 3.11, “Subtypes”.

Products and Product Modules are managed in the Roundtable Products window:

Follow these steps to add a new product:

You can only change the product description field for a product. If you want to change the product code, delete the product and re-add it.

Follow these steps to edit a product description.

You must delete all Product Modules within a product before you delete the product itself.

Follow these steps to delete a product.

The Product Report prints a list of the contents of the product.

Follow these steps to print the report:

The following fields are found in the Product Report window:

After you create a product, follow these steps to add the Product Modules:

You can change the Product Module description field but not the Product Module code. To change a Product Module code, delete the Product Module and re-add it with the new code. You cannot delete a Product Module if any objects have been assigned to it.

Follow these steps to edit a Product Module description.

If you have ever used the Product Module, you cannot delete it (even if you aren't using the Product Module now).

Follow these steps to delete a Product Module.

The Product Module Report prints a detailed report of the objects in a Product Module, including the object code, description, version number, status, Subtype, and additional notes for each object.

Steps to print the Product Module Report:

The following fields are found in the Product Report window:

You can access the Workspace Module Definitions window using the following steps:

You may edit any of the fields in the Workspace Module definition except the name of the module. However, Roundtable will not rename directories or move objects to accommodate your changes. A Workspace Module definition defines the physical location of objects under the Workspace root or Product directory. If you change the source directory specification you will have to manually move any affected source code in each Workspace that contains a module defined by the Workspace Module definition. If you change the .r Code Directory you should delete the affected .r code and then re-compile the affected module. Use of the Naming Code field is optional and the affect of changing it application specific.

You may safely change the Description of the Workspace Module definition.

You may access the Workspace Module Definitions window by choosing the Maintenance button in the Products Window as shown in the following steps:

You can delete a Workspace Module definition that has not been assigned to any Product Module.

You can access the Workspace Module Definitions window by choosing the Maintenance button in the Products Window as shown in the following steps:

Use the following Code Subtype window to define Code Subtypes:

The following fields are found in the Subtype Window:

Field	Description
Subtype	The Code Subtype name.
Assigned	A toggle box that indicates whether an object with the currently selected Subtype exists. Once a Subtype has been assigned to an object, the Subtype cannot be deleted and some editing operations are disallowed.
Inactive	A toggle box that indicates whether the selected Subtype is inactive. Inactive Subtypes can no longer be used as a Subtype when creating new Objects.
Name Program	A fill-in for the pathname of a naming program. The use of a naming program is entirely optional. See Section 3.11.10, “Name Programs” for more information on naming programs.
Build Program	A fill-in for the name of the build program that creates source files for objects of this Subtype. The build program can be simple or complex. For example, a build program can be a full-blown screen generator or it can copy a template into the source file. The use of a build program is entirely optional. See Section 3.11.11, “Build Programs” for more information on build programs.
Edit Program	A fill-in for the name of the edit program. For example, if objects of this Subtype are to have a specific format, the edit program can be a custom editor. See Section A.2, “Edit Program: rtb/p/rtb_open.p” for an example of an edit program. See Section A.3, “Managing Application Data with the Edit Program” for a full description of the edit program.
Program	A toggle box that indicates whether objects of this Subtype are OpenEdge-compilable programs (Include files are not considered programs).
r-code Dir	The relative r-code directory for the Subtype. The path for r-code is determined as follows: If r-code directory defined for Workspace Module only: <wspace-path> + <module-rcode-path> + object.r If r-code directory defined for Subtype only: <wspace-path> + <subtype-rcode-path> + object.r If r-code directory for both Workspace Module AND Subtype: <wspace-path> + <module-rcode-path> + <subtype-rcode-path> + object.r Roundtable will not move .r code for you if you change the value of the .r code directory for this Subtype. If you change this value, you will have to move any Subtype .r code manually, or recompile programs of this Subtype.
Subtype Parts	A Subtype may be comprised of up to ten system files. The first nine of these files are called parts and are user-defined. The tenth file is used for the .wrx generated by the OpenEdge AppBuilder for window procedures that use OCX controls.
Description	A fill-in for the description of the Subtype part.
Directory	A fill-in for the directory, relative to the Workspace Module directory, where the part file is stored. Leave this field blank if the part is stored directly in the Workspace Module directory.
Template	A fill-in for the full path and filename of a template file used to build the part file. This optional field is used only in conjunction with the build program. See Section 3.11.11, “Build Programs” for more information on build programs.
Suffix	A fill-in for the suffix added to the end of the part filename (prior to the extension). If left blank, no suffix is added to the object's name.
Extension	A fill-in for the extension of the part (for example, "p" for a program). This optional field is commonly used to enforce a naming convention. For instance, a .p extension is used for most OpenEdge procedures created with the Procedure Editor and a .w extension is used for most procedures generated by AppBuilder.
Defaults	These toggle-boxes correspond to the object properties on the Config tab of the Object Properties window. When new objects of the Subtype are created, the object's properties will default to the properties defined here For more detailed information, see Section 6.4.1, “Config Folder Description”.

In pre-version 9 OpenEdge programming environments, multiple code parts are not commonly used. Typically, you define Subtypes with only one part each. Possible Subtype definitions Include:

	It is not necessary to define a secondary Subtype part to store WRX files as part of your windows programs. Roundtable can automatically find and store WRX files as a part of your PCODE object without requiring you to define a multi-part Subtype. See Section 6.4.10, “WRX Files” for a more complete description of how this works.

OpenEdge code (PCODE) objects are assigned a user-defined Subtype that controls the naming, management, creation, and storage of one to nine text files (parts) belonging to the object. Consider the following simple Subtype definition:

This Subtype describes programs that consist of a single text file with a ".p" extension.

In the following example, a simple include file Subtype is defined:

Multi-part objects require a bit more complex definition. In this example, an ADM2 SmartDataObject is defined:

Without the SDO Subtype, the three files that comprise an SDO would have to be separate objects, making them cumbersome to manage. By formalizing the relationship among these text files, Roundtable can treat them as a single object.

Using Code Subtypes can help enforce coding standards and vastly reduce the number of objects tracked in your system. They can also make training new programmers on your system much easier because Roundtable reminds them of the requirements of each Subtype.

Suffix naming is less flexible than extension naming because the length of the suffix may reduce the length of the base name usable by the programmer. For example, a two-character suffix of "-d" leaves only six characters available for the base name if you want to conform to the eight-character DOS naming convention.

When you add a PCODE object, Roundtable tests the naming conventions based on these fields. For example, if you designate ".p" as the extension for the program Subtype part, you cannot create a Program part with a suffix of ".u". Roundtable displays an error message until you enter the correct suffix.

Code Subtypes should be created before you set up the Workspace sources or add PCODE objects to your OpenEdge application. After creating the Code Subtypes, use them to create PCODE objects. You can also edit and delete Subtypes (until assigned) and print the Code Subtypes Report.

First, follow these steps to enter the basic information for the Subtype.

Optionally, edit the Subtype Defaults as required. Choose File → Exit to close the window.

You can edit some of the fields of a Subtype after it has been created.

Follow these steps to edit a Subtype.

Note that you cannot delete a Subtype after it has been assigned to one or more objects. The Assigned toggle box at the top of the Subtypes window indicates whether the Subtype has been assigned.

Follow these steps to delete a Subtype:

The Code Subtypes Report provides a detailed review of each Code Subtype. The report includes all the fields listed on the Roundtable Code Subtypes window.

Follow these steps to print a Code Subtypes report:

A specialized naming program can be associated with a Subtype. The sample program below takes the naming code defined in the module definition and appends a four-digit number to it.

For example, if the module naming code was ord then the default names for objects created in the module would be ord0001.p, ord0002.p, etc. Naming programs provide only default names; the user always gets a chance to modify the object name. The sample program works by finding the object with the highest value, then increments that value by one. This is helpful if you want to leave gaps in the number scheme. For example, if you manually named an object ord0100.p, the next object name supplied by the naming program would be ord0101.p.

Any name program that you use must define the input and output parameters illustrated in the sample program below.

/*
Sample Name Program -- 
 Generate new object name using module counter
Input Parameters:
 pcPmod - Product module.
 pcObjectType - Object type (PCODE).

Output Parameters:
 pcObject - Object name generated by build program.
 pcError - Non-blank on error.
*/

DEFINE INPUT PARAMETER pcPmod AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER pcObjectType AS CHARACTER NO-UNDO.
DEFINE OUTPUT PARAMETER pcObject AS CHARACTER NO-UNDO.
DEFINE OUTPUT PARAMETER pcError AS CHARACTER NO-UNDO.

DEFINE VARIABLE iNum AS INTEGER NO-UNDO.
DEFINE VARIABLE iIdx AS INTEGER NO-UNDO.
DEFINE VARIABLE cLastObject AS CHARACTER NO-UNDO.
DEFINE VARIABLE lNoCount AS LOGICAL NO-UNDO.
DEFINE VARIABLE cName AS CHARACTER NO-UNDO.

FIND rtb.rtb_pmod
 WHERE rtb.rtb_pmod.pmod = pcPmod NO-LOCK.

FIND FIRST rtb.rtb_moddef
 WHERE rtb.rtb_moddef.module = rtb.rtb_pmod.module NO-LOCK.

FIND FIRST rtb.rtb_ver
 WHERE rtb.rtb_ver.obj-type = pcObjectType
  AND rtb.rtb_ver.object BEGINS rtb.rtb_moddef.naming-code
 NO-LOCK NO-ERROR.
 ASSIGN iNum = 0
  cLastObject = "".

OBJECT-PASS:
DO WHILE AVAILABLE rtb.rtb_ver:
 cLastObject = rtb.rtb_ver.object.
 cName = rtb.rtb_ver.object.
 cName = ENTRY(1,cName,"."). /* strip any extension */
 lNoCount = FALSE.
 DO iIdx = 4 TO LENGTH(cName):
  IF NOT CAN-DO("0,1,2,3,4,5,6,7,8,9", 
	SUBSTRING(cName,iIdx,1)) THEN DO:
   lNoCount = TRUE.
   LEAVE.
  END.
 END.
 IF NOT lNoCount THEN iNum = 
	MAX(INTEGER(SUBSTRING(cName,4)),iNum).
 FIND NEXT rtb.rtb_ver
  WHERE rtb.rtb_ver.obj-type = pcObjectType
   AND rtb.rtb_ver.object BEGINS rtb.rtb_moddef.naming-code
   AND rtb.rtb_ver.object <> cLastObject
  NO-LOCK NO-ERROR.
END. /* OBJECT-PASS */
iNum = iNum + 1.
pcObject = SUBSTRING(rtb.rtb_moddef.naming-code,1,3) + 
	STRING(iNum,"9999").
IF iNum > 9999 THEN
 pcError = "Counter limit exceeded.".
ELSE
 pcError = "".

A specialized build program can be associated with a Subtype. A build program creates the source file parts of an object being created for the first time.

A simple build program can be commands that copy a template specified in a code Subtype into the new object part files. If you are ambitious, you could tie a build program to your own program generator.

Because a build program needs to know quite a bit about the Workspace, task, and specific object you are working with, Roundtable provides the following input parameters:

Optionally, if you have build programs that were developed for releases of Roundtable prior to 9.1D that use the Urtb* shared variables, you may use them by changing the LEGACY preprocessor value in rtb/p/rtb_runbuildprog.p. This procedure is used by Roundtable to run your build program(s) and is distributed as unencrypted source.

Maintain users in the User Maintenance window:

This window allows you to add or delete users, and edit user names. The 'sysop' user has unlimited access to all system functions.

The 'sysop' user can grant Administrator privilege to other users. A user with Administrator privilege has access to all system functions as well as grant the Administrator privilege to other users.

	When Roundtable is first installed, the 'sysop' user is automatically created.

	Roundtable users are stored in the _user table of the Roundtable database.

The following table describes the fields of the User Maintenance Window:

Follow these steps to add a user.

Follow these steps to edit a user.

Follow these steps to delete a user.

You can only change your password if users have been defined in Roundtable. Follow these steps to change your password:

Use this window to define a permission group that you will later assign to one or more users in specified workspaces. Each permission group contains is identifed with a name that you provide and a list of allowable system activities.

The browse contains a single column displaying each of the currently defined group access codes. When you select a group access code, the data to the right of the selection list indicates the security privileges defined for that code. The following table describes the meaning of each toggle box:

Use the Workspace Security window to associate one or more users with one or more Security Groups in the selected Workspace.

The first column contains a list of users, and the second column contains a list of security groups assocated with the user(s).

In the example window, the users bob, jeff, and tanya have the permissions granted by the Manager group. The user richard has the cumulative permissions granted by the Dbadmin and Manager groups.

Follow these steps to add a new Workspace user group assignment:

Follow these steps to edit a new Workspace user group assignment:

Follow these steps to delete a Workspace user group assignment.

If you are logged into the system as anyone other than the sysop user you may view your access privileges for the currently selected Workspace by following these steps:

You start by loading the Pre-Prod Workspace first because it contains the earliest version of the system. Assuming that you have already defined your Subtypes, products, and Product Modules, follow these steps. See Section 3.14, “Defining Your Application”.

Follow these steps to create a Test Workspace in Roundtable and populate it:

Follow the same steps as outlined in the Test Workspace, except that you copy object definitions from the Test Workspace into the Devel Workspace.

Now that you have the Devel, Test, and Pre-Prod workspaces registered into Roundtable's repository, you can specify the normal flow of system changes. This is done from Workspace Sources.

Roundtable can manage many Workspaces. For example, quality assurance, testing, and development should be done in different Workspaces. Multiple Workspaces can aid in the quality assurance strategy, but more is not necessarily better. Consider the timing impact of each additional Workspace when planning your overall development and quality assurance strategy. Use the following guidelines:

When running Roundtable in a distributed AppServer configuration, it is possible that the AppServer process in which the Roundtable server is running cannot access the physical Workspace directory via the same path as the Roundtable client.

For example, your physical Workspace directory may exist on a Unix machine in /u2/devel that you access via a mapped SMB share (//unixshare/devel) from your client machine.

To run the Roundtable server in an AppServer session on the Unix machine, the Roundtable server must be able to read from and write to the physical Workspace directory. To accomplish this, Roundtable allows you to override the default Workspace path and specify an alternate server Workspace path. In the example above, the Roundtable client would access the physical Workspace directory via the default path (//unixshare/devel), while the Roundtable sever would access the physical Workspace directory via the alternate server path (/u2/devel).

Roundtable Workspaces are defined in the Workspaces window:

The following fields can be found in the Workspace Window:

Follow these steps to create a new Workspace:

	To specify an alternate path to the physical Workspace directory, select the Server Path tab folder, check the 'Server Path Override' toggle and repeat the previous steps.

You can change the description, Xref Level, R-code, or S-code fields for a Workspace at any time; however, you cannot change the Workspace ID.

	Changing the Xref Level, R-code, or S-code after you have assigned and compiled an object has no immediate effect on objects in the Workspace. You must recompile for the Xref Level and R-code to take effect.

Follow these steps to edit a Workspace:

You can delete a Workspace if you have sufficient security access and no one else is currently working in the Workspace. Note that deleting a Workspace does not delete any completed objects from the repository. A Workspace is simply a list of object versions that defines a configuration of your software application and a related set of application components in the directories specified in the Workspace paths. However, once you delete the Workspace, the configuration is lost and cannot be reclaimed. Although tasks done under the Workspace are not deleted, they may be far less available for casual review if the Workspace to which they belong is deleted. In addition, all Release, deployment, and general histories of the Workspace are deleted.

	Deleting a Workspace removes all source code at the operating system level. Work-in-process code may be deleted and will not be recoverable.

Follow these steps to delete a Workspace.

Marking a Workspace as hidden removes it from the Workspace list on the Tabletop in GUI and the Workspace Selection screen in TTY.

Follow these steps to hide a Workspace:

Marking a Workspace as archived removes it from the Workspace list (hidden Workspace) and removes all source from the Workspace directory. Since the Workspace is archived and not deleted, all Xref information is retained in the repository.

Follow these steps to archive a Workspace:

Use the Workspace populate process to restore or remove source from a Workspace directory. A Workspace is a configuration of object versions defined by the configuration list stored in the repository. This makes it possible to restore the source of a Workspace by extracting the appropriate object version's files from the repository.

There are two common situations where it is necessary to use the populate process. The first is disaster recovery. For example, if a Workspace directory was deleted, the populate process can be used to restore its contents. Only the latest completed version of each object is restored. If work-in-process objects existed and had a status of Central, this work would be lost. In fact, the populate process does not even try to restore work-in-process objects to ensure that they are not overwritten in the populate process.

The second situation involves the use of the Workspace and Workspace module S-code flag. This flag indicates whether source (and other object files as well) should be stored in the Workspace. Set this flag to No, then run the populate process to remove source from the Workspace. Set this flag to Yes, then run the populate process to restore source in the Workspace.

A short cut can remove the source from a Workspace if no work-in-process objects exist. Change the S-code flag to No, then delete the source manually. This is a quick way to free disk space when a Workspace has not been used for some time and you want to keep the configuration of the Workspace indefinitely.

Follow these steps to run the Workspace populate process:

Follow these steps to print a Workspace report.

The Workspaces Changes Report shows changes in a Workspace between to events (inclusive). The following window allows you to specify the information to include in the Report:

The Workspace Event History Report shows events that match the criteria that you specify in the following window:

The Workspace Report shows information about a Workspace and, optionally, objects assigned to the Workspace. The following window allows you to specify the information to include in the Report:

The Workspace Differences Report shows the differences between the contents of any two Workspaces. The Workspace Difference Report window appears as follows:

The following fields can be found in the Workspace Differences Report dialog box:

After you create a Workspace, you define its contents by assigning product modules to it. Assign product modules using the Workspace Sources window.

Follow these steps to add a Workspace source.

Follow these steps to delete a Workspace source.

Roundtable keeps objects in the Roundtable repository. The repository stores all of the objects in the system and their definitions. The unique key for the object definition includes the following fields:

The object definition allows an object of the same type, name, and version to exist in two different product modules, creating an object variant. Although Roundtable stores all object variants in the repository and objects can exist in more than one Product Module, only one variation of an object can be assigned to any given Workspace when the Allow Non-Unique system flag is set to No. Each Workspace represents a collection of object versions. Roundtable manages a table of these object versions called the configuration list. The following fields define the unique key for objects in this table:

The difference between versions and object variants can be confusing at first. Consider the table below:

All of the objects in this table are stored together in the object repository. The first two show two versions of an object named menu.p. Remember that the unique key on objects stored in the repository includes the object type, Product Module, object name and version code. The last object is an object variant that belongs to a Product Module named cust1_ap. You must always remember to consider the Product Module when looking at an object version.

This example shows how you can use object variants. Assume you are creating an invoice-printing program for many different types of businesses. Most of these businesses can use your core (or generic) program, but the Videostore application needs a special variation. To handle this, you need to create two variations of the same program.

You begin by creating the core program, invprnt.p, in the development Workspace (refer to line 1, below). Then, import the core program into the Testing Workspace (line 2). After testing, import the program into two Workspaces, a core pre-production Workspace (line 3) and a Videostore Workspace (line 4). In the Videostore Workspace, you can create a custom variant of invprnt.p using the video_ap Product Module. You now have two variations of the same program (lines 3 and 4).

The Schema Update window is used to manage the schema update process - that is, the application of changes made to the logical schema to the physical Workspace database(s). From this window, you can initiate a build of an update list, maintain an existing update list, or delete an existing update list.

Pending changes to each physical database (the schema update list) are displayed in a treeview grouped first by database, sequences, then table changes. Each node in the treeview has a decorator to indicate the pending action to be taken (Add, Update, or Delete). The properties table allows you to view the committed and pending changes for each item in the treeview.

The following table describes the controls on the Schema Update Window:

The first step in updating the physical schema is to build the schema update list. The Build function locates all logical schema objects that have changed since the last time that the schema was updated and creates the schema update list.

Because a PFIELD can be assigned to several PFILE objects, a change to a single PFIELD object might affect the update of multiple tables.

After Roundtable generates the list of database tables and sequences that must be updated, it checks schema integrity. The integrity check looks for missing information such as a missing dump-name or primary index. It also checks for missing objects and other problems that would cause the table definition update to fail.

	To see which schema objects need to be updated before building the Schema Update List, print the Unapplied Changes Report. For more information on this report, see Section 4.8.12, “Unapplied Changes Report”.

	Sometimes tables are shown in the schema update list that do not actually need updating. These extra tables are sometimes included because Roundtable cannot resolve all cross-references to changes in the PFILE and PFIELD objects related to the table. Including these tables will not cause any problems in the schema update process.