Using Jargon Replicator^TM

Contents

Introduction to Jargon Replicator

Generating Setup, Query and Browse Apps for DB Tables

Replicating Frames in Existing Progress 4GL Programs

Viewing Frame and Widget Attributes of Existing 4GL Programs

Running Jargon Replicator

• System Preferences (jrep.ini)
• Saving and Loading User Preferences
• Action Specs tab
• Additional Specs tab
• Frame Specs tab
• Browse Specs tab
• Final Approval tab

Advanced Techniques

• Rearranging and removing fields
• Creating Parent/Child Queries with Child records in a table

• Jargon Replicator Release Notes for the most recent changes and bug fixes.

• Developing Reusable Browses for tips on creating and using browse frames.

Introduction to Jargon Replicator

Jargon Replicator^TM provides several features to help developers quickly build GUI applications that can be used with Jargon Reader^TM and Jargon Writer^TM. By analyzing the information in existing Progress database schemas and in existing character-based Progress source programs, Jargon Replicator quickly creates "first-cut" client and host applications which can then be further enhanced as needed with Jargon Writer.

These applications can range from simple GUI frames with "get" and "set" client tasklists and host include files (available for later hookup), to fully-featured ready-to-run "file maintenance" programs that include reusable table-based browses. These file setup applications can be completely generated and running in literally a few minutes. Then, developers can use Jargon Writer to fine-tune the appearance and behavior of the generated applications.

For developers who are building a new application, Jargon Replicator can create file setup programs for all "master" tables (such as customers, employees, inventory items, etc.) that are highly functional, provide a consistent look and feel for end users, and can be completed very quickly (in a few hours or days). All that is required is a completed Progress database (Version 7 or higher) that defines the tables to be replicated, including fields, indexes, display formats and help messages.

Secondary tables with a "1-to-1" or "1-to-many" relationship can also be included in these programs, with the basic logic ready to be "hooked up" by the developer in a manner appropriate to the application's needs.

For developers who are converting an existing character application, Jargon Replicator can both create file setup programs from the existing database schema AND create GUI "lookalike" frames for existing Progress programs that use named character-based frames, to be used as a "first cut" of working GUI prototypes of existing transaction entry and other data input routines.
 

Jargon Replicator creates both host-side and client-side application files.

• For the host side, it generates a set of include files that are referenced within the host tasks built into the client app.
• For the client side, it creates a ".xml" file which the developer downloads from the host to the client (using "ftp", the Jargon Software RDU utility, or other means). Then, the developer opens the ".xml" file in Jargon Writer and clicks the "Generate 4gl" button, which generates the top-level ".p" program associated with the previously-generated host-side include files. This ".p" program is then uploaded back to the host, which completes the replication process. The application is now ready to be run, tested and revised.

Jargon Replicator can generate a variety of applications for any table in a Progress database schema. These generated applications can be:

• A read-only "query" application which includes buttons and menu items labeled "Display", "First", "Next", "Prev" and "Last" for selecting and navigating through records in a database table.
• A file maintenance "setup" application which includes the query functionality plus buttons and menu items labeled "New", "Copy", "Apply", "Cancel" and "Delete" that provide full add/change/delete functions.
• A "browse" frame that can be used by itself, or in combination with a setup or query application.  This browse provides a separate frame that uses a multi-row, multi-column table to display selected fields from a specified number of records at a time, plus a specs panel that allows users to quickly narrow their search to find a specific record in a table.
• Frames for secondary tables that are logically linked to the primary table in a "1-to-1" or "1-to-many" relationship may also be generated, either as separate client frames or as additional tabs in one tabpanel. The "get/set" logic for these secondary tables is generated for the host side. The developer can then hook up host tasks to reference this host logic by adding new client components (such as buttons) and linking events on these components to new host tasks on the client side.

• The fields of the table will be arranged in the specified number of columns and rows within one panel or within multiple tabs of a tabpanel.
• All fields that are components of the primary index (if any) of the table will be placed in a keys panel at the top of the client frame.
• Logical fields are converted to checkboxes.
• Character fields with a "view-as editor" clause are converted to textareas.
• All other fields are converted to textfields with the appropriate data edit type (character, date, decimal, integer).
• Any Progress help messages in the schema are converted to client tooltips.
• Progress display formats are optionally converted to client edit masks.
• Fields which are the leading components of table indexes become the first columns in the browse table and are made available as search keys in the browse specs panel (if generating a browse).

• A menubar with File(Exit) and Help(Help Topics, About) choices.
• A keys panel that contains the key fields in the primary index of the table, if any.
• A data panel that contains the data fields, which may be a simple single panel or a tabpanel.
• A button panel that includes buttons for "Help" and "Exit".
• A 2-line textpane used for status messages to the user (both client and host can display messages).
• A host communications status area at the bottom of each frame which displays a moving image and a message while information is being transferred between the client and host systems.

Jargon Replicator can quickly create GUI "lookalike" versions of character-based frames in existing Progress source programs, such as transaction entry, inquiry and report specification screens. The only requirement is that the frames must be "named" frames that use the "with frame xxx" syntax. If an existing character program has multiple frames, each frame can be converted to a separate client GUI frame, or each frame can be converted to a separate tab in a tabpanel within one common frame.

If the table contains any fields from database tables, those fields that are keys in the primary index of the first table referenced in the frame will be moved to the keys panel and removed from the data panel. The host side "get" and "set" include files will also be generated and ready to reference by modifying the generated client app within Jargon Writer.
 
 

Viewing Frame and Widget Attributes of Existing 4GL Programs

Jargon Replicator also includes a "view-only" operation mode, which lets the developer "walk through" each frame and widget (frame component) in an existing Progress program. This feature can be valuable to preview what will be converted, as well as to help determine the cause of any problems encountered during an attempt to replicate a program.

Each frame and its widgets (labels and fields) are displayed in multi-column rows in a scrolling table in the Replicator client app. All component attributes used by Replicator are shown in this table.
 
 

Running Jargon Replicator

Replicator can be run as a Jargon Reader application from a desktop shortcut icon, or as a Jargon ReaderX application from a link in a Web page, or it can be loaded into Jargon Writer and executed from there. When started, it displays a frame that includes a tabpanel with five tabs: "Action Specs", "Additional Specs", "Frame Specs", "Browse Specs" and "Final Approval".

At startup, a host task is also done as part of the startup tasklist, which queries the host to determine:

• any global system preferences, as specified in the "jrep.ini" preferences file
• the logical names of all attached databases
• the names of any existing developer preferences files (files with suffix ".4pr" in the preferences directory specified in "jrep.ini").

At any point, you can go back to a previous tab to change or correct any entries, until the "Begin Replication" button is clicked on the "Final Approval" tab. When replication is completed, a message box will be displayed. Then, you can download the generated ".xml" file, load it into Jargon Writer, and click "Generate 4gl" to create the ".p" program, which you upload back to the host. That's it!

System Preferences (jrep.ini)

Several "global" system preferences are defined with name/value pairs in a text file called "jrep.ini" in the application's working directory on the host. To initially create this file, copy ./jrep/model_jrep.ini to ./jrep.ini, then modify the values in ./jrep.ini for your environment. The preferences defined in jrep.ini are:

PreferencesDir - The directory name where user preferences (*.4pr files) are located. Default value is "./jrprefs/".

TemplatesDir  - The directory name where template files used by Jargon Replicator are located. Default value is "jrep/template/".

ExcludedFields - A comma-separated list of field names to always exclude from a generated program when building a setup, query, or browse application from a database table. You can also use Progress "matches" wildcard symbols in field names. For example, if most or all tables have "audit" fields named "date_created" and "date_changed", you could exclude these fields by setting ExcludedFields="date_created,date_changed".

EndTabFields - A comma-separated list of field names to always put on a final tab in a generated program when building a setup, query, or browse application from a database table. You can also use Progress "matches" wildcard symbols in field names. For example, if most or all tables have "user-defined" fields named "char-1", "char-2", "dec-1", "dec-2",  etc., then you could tell Replicator to place all such fields on the last tab of the tabpanel by setting EndTabFields="char-.,dec-.,date-.,log-.". Note that the period as a wildcard means that these names will match "char-1" "char-2" etc.

EndTabName - The name to assign to the last tab that contains EndTabFields (if any). Default is "Misc".

Each time you start Jargon Replicator, you can click the "Load Preferences" button at the bottom of the first tab ("Action Specs"), then select the name of an existing set of preferences from the combobox in the window which opens, and click "Submit". This will fill in values in various fields on the first two tabs, using values that you had previously saved in a preferences file on the host (usually in a subdirectory named "jrprefs/"). This will allow you to avoid re-keying the same values every time, especially for values that rarely change such as component prefixes, layout values, directory names, etc.

To save a set of preferences, fill in the first two tabs, then click the "Save Preferences" button at the bottom of the second tab ("Additional Specs") BEFORE clicking the "Submit" button on that tab. Then, in the frame which appears, enter a unique name for this preferences set and click the "Save" button. The values of the preferences fields will be saved under this name, with a ".4pr" file extension suffix automatically added.

On the host, preferences are saved and loaded in the subdirectory specified by the "PreferencesDir" entry in the "jrep.ini" system preferences file. The default value is the directory name "./jrprefs/". The directory specified by the PreferencesDir entry in jrep.ini must exist in the application working directory.

If there is a user preferences file named "default.4pr" in the preferences directory, then that default.4pr will be loaded when Replicator starts. This provides the ability to have a standard system-wide set of preferences values, which could include a custom images directory instead of "jrep/client". To create it, just run Replicator, set the values to whatever system defaults are desired (on the first two tabs), then click "Save Preferences" on the "Additional Specs" tab and save as "default.4pr".

The values on the first two tabs which are saved in and loaded from preferences files are:

• #Columns in frame
• Max. rows per panel
• Max. checkbox caption size
• #Pixels below rows
• #Pixels after label
• Min. browse column width
• Conversion Directory
• Deployment Directory
• Name for XML app
• Name for 4GL Program
• Title for First Frame
• Use Building Blocks?
• Log Debug Info?
• Label Alignment
• Copy Formats?
• Use Button Images?
• Image Directory
• Allow Partial Keys?
• Start in Browse?
• Initial Browse Action
• Subsequent Actions
• Frame prefix
• Panel prefix
• Label prefix
• Textfield prefix
• Checkbox prefix
• TextArea prefix

Action Specs tab

1. Select the "Replication Action" by clicking one of the five radio buttons:

• Create maintenance/query/browse for a database table
• Create query/browse for a database table
• Create browse only for a database table
• Replicate the frames in an existing program
• View frame and widget attributes in a program


2. Select the "Replication Method" by clicking one of the two radio buttons:
 

• "Convert frames as separate frames" will cause each replicated character frame or generated database table frame to be converted into a  separate frame in the client app
• "Convert frames to tabs in a tabpanel" will convert each replicated character frame or generated database table frame into a new tab (or set of tabs) in one tabpanel in one frame.


3. If replicating an existing Progress program, enter its Source Program pathname (either an absolute path or a path relative to the working directory on the host). Example: "payroll/entry.p" or "/home/src/ap/query1.p").

4. If creating an application for a database table, select the database name from the "Database Name" combobox. A host task will be triggered to get the names of the tables in the selected database. After the host task ends, select the desired table name from the "Table Name" combobox. If you select a different database than the currently displayed selection, there will be a host task to repopulate the table combobox with the tables of the newly selected database.

5. If doing step 4, you can optionally enter a comma-separated list of "Secondary tables" for which you want to create client frames or tabs with the fields of each secondary table entered. For example, if the primary table is "order", you might specify secondary tables "order-line,order-comments".

6. Enter an integer of 1 or greater in the "#Columns in frame" field. This is like the Progress "display <table> with n columns" syntax. Each column includes a label and a data field. The default is 2.

7. Enter the "Max. rows per panel". A good default is 10 rows. Larger values may create panels that are too large for an 800x600 Windows display.

8. Enter the "Max checkbox caption size". Any labels on logical fields that are no longer than this number of characters will be converted to a checkbox caption, which by default is placed to the right of the checkbox image. Longer labels will be left as labels placed to the left of the checkbox, which may be an appropriate layout for a long series of questions or lengthy options. The default is 20.

9. Enter the "#Pixels below rows". This provides vertical spacing between each row of column values within a frame, and may be increased from the default of 8 pixels (about one character in height) if the panel being created will only have a few rows and you want better proportional use of the screen space.

10. Enter the "#Pixels after label". This provides horizontal spacing between a label and the textfield to its right. The default is 5.

11. Enter the "Min. browse column width". This value establishes a minimum number of characters for the width of any column in a browse table. Columns will be defined as wider if their column titles or edit masks (formats) are longer than this value, but will never be defined as narrower than this value. The default is 12.

12. Click "Next" to proceed to the "Additional Specs" tab. Or, if you want to reset all values and start over, click the "Defaults" button to reset all fields to their default (preferences) values.

1.  Enter the name of the "Conversion Directory" where the generated files should be created. This can be an absolute path or a path relative to the application working directory.

2. Enter the name of the "Deployment Directory" where the application will be run when deployed. This directory name will be prefixed to all ".p" and ".i" filename parameters in host task definitions in the generated client app. This should normally be a relative directory path, for deployment portability reasons. This can be the same directory as the conversion directory.

3. Enter the "Name for XML app" for the client procedure to be created. Do NOT enter the ".xml" suffix in this field.

4. Enter the "Name for 4GL program" for the host ".p" Progress program to be created, including the ".p" suffix. This is the program that will be generated by Jargon Writer after the ".xml" file is downloaded.

5. Enter the "Title for First Frame". This will be the title displayed in the frame titlebar for the first (or only) frame in the client procedure. If a browse frame is also created, it will be titled "Browse for <entered title>".

6. Check the "Use Building Blocks" if the generated application should be made compliant with the Jargon Building Blocks^TM system infrastructure, which includes standard login, menuing and security features based on tables in an "xfiles" database. Applications generated with this option cannot be run on a standalone basis; they can only be run through the Building Blocks login and menu system.

7. Check the "Log Debug Info." checkbox if you want Replicator debugging information placed in the log text file in the host's conversion directory (named <appl>.log, where <appl> is the xml file name.

8. Select the "Label Alignment" option from the combobox for Left Aligned, Centered or Right Aligned  labels.

9. Check the "Copy formats?" checkbox if you want Progress data formats to be converted into client "edit masks", which control display formats for values received from host tasks and also control the type of values that users can enter in textfields.

10. Check the "Use Button Images?" checkbox if you want to use images on navigation buttons in generated query and browse frames. For queries, images are used on Display, First, Prev, Next, Last and Browse buttons. For browses, images are used on Select, Cancel, First, Back, Forward and Last buttons.

11. If using button images, enter the "Image Directory" (relative to the MediaRootDir or MediaRootURL startup parameter) where the images will be located. Default is "jrep/client" which is a subdirectory of the "./images" directory found in the working directory of a standard  Jargon Writer installation.

12. Check the "Allow Partial Keys?" checkbox if you want users to be able to retrieve a record by entering only the first few characters of the primary key of a record. Note that this option is usefull only on tables where the first key in the primary index is a character field. If this option is specified for integer, decimal, date or logical keys, it will be ignored but will not cause any problems.

13. Check the "Start in Browse?" checkbox if you want the client application to start by opening the browse frame and running a host task to populate it, thus giving the user an immediate list of records from which to choose. If this option is not selected, the application will start in the query or maintenance frame.

14. Select the "Initial Browse Action" that the "Browse" button should run the FIRST time that a user clicks it during a session. These choices correspond to the choices in the "Browse" menu of the menubar.

15. Select the "Subsequent Actions" that the "Browse" button should run on the second and all subsequent times that a user clicks it during a session.

16. Enter new prefixes for the six component types generated by Replicator: Frame, Panel, Label, TextField, Checkbox and TextArea. Or, accept the default prefix values. These prefixes are not required, but are a convenient, standard way to quickly determine the type of component from its name, which is useful when writing Progress host applications and remembering which "jsi/" include files to use for a given component.

17. If you wish to save the values on the first two tabs in a named User Preferences file, for use on future replications, click the "Save Preferences" button to open the Save Preferences window. Then enter a preferences filename and click "Save".

18. Click the "Submit" button to send these values to the host for editing. Any edits which fail will cause a message box to display. Otherwise, if the values pass editing, the host will bring up the next tab.

1. If you are creating an application for a database table, the frame values and the three checkboxes will be filled in automatically by the host task for each frame to be generated. If replicating an existing program, all named frames will be filled in if the host is a Unix system. If the host is an NT system, you must type the name of each frame that you want to replicate, which you can get by looking at the source code of the existing program.

2. For each frame line, you can change the "Abbr. in App", which is the abbreviation to use for naming the generated Progress include files and internal component names in the client app. This abbreviation should be kept short, ideally no more than 6-8 characters, although it is limited only by the host's file naming conventions. For example, if a frame is called "f-customer", a good abbreviation might be "cust". You can also change the default "Frame Title" for each client frame to be generated. The first title will default to the title you entered in the Additional Specs tab, but all other titles will default to the table name, which may not be a user-friendly title.

3. For each frame line when replicating existing programs, check the "Maint?", "Query?", and "Browse?" checkboxes as appropriate if you want the generated programs to have these components and tasks.

4. If you are replicating a program with many frames, and you only want to replicate one of them, it may be quicker to click the "Clear all entries" button, then type in the name and values for the frame you want. You can also delete each frame name that you do not want to replicate.

5. Click the "Submit" button to send these values to the host for editing. Any edits which fail will cause a message box to display. Otherwise, if the values pass editing, the host will bring up the next tab.

1. If you have checked the "browse" checkbox for any frames in the previous "Frame Specs" tab, you will be stepped through this "Browse Specs" tab for each browse frame requested. For each frame, the frame name and associated table name will be displayed in the first two fields.

2. Enter the "Number of rows per result set" to tell the host how many records (rows) to return on each browse request from the client. This result set will populate the scrolling browse table. The default is 100 rows per result set. To see the next 100 records, the user clicks "Forward". To see the previous 100 records, the user clicks "Back". Values larger than a few hundred rows should be used carefully with an eye to overall performance issues.

3. Enter, change or accept the "Field names for browse columns". For browses generated for a database table, these values will be filled in automatically from the leading components of each index for the table, plus any non-key fields needed to get a minimum of five columns. Non-key fields are taken in "Order" sequence of the table schema definition. There is a limit of 99 columns per browse for replication, although more can be added afterwards by using Jargon Writer to modify the generated app and by changing the host include files. Fields defined with non-zero extents will never be chosen as browse columns. You can also add, delete or reorder these fieldnames by using the buttons at the bottom of the fieldnames table.

4. To open a database schema inquiry to view and/or automatically select field names for the table named at the top, click an empty row in the fieldnames list (to specify where any selected fieldname should be placed) and then click the "Browse Schema" button. The Jargon Software Schema Inquiry window will open and will display the fieldnames for this database table. If you double-click a fieldname in the schema inquiry, it will be copied into the selected row of the Replicator fieldnames list. Note that the schema inquiry window remains open so that you can
select another open fieldname row, then double-click another fieldname from the schema inquiry window, as many times as needed. When the "Submit" or "Back" buttons on this tab are clicked, the inquiry window will automatically close.

5. Click the "Submit" button to send these values to the host for editing. Any edits which fail will cause a message box to display. Otherwise, if the values pass editing, the host will bring up the next tab.

1. Review all entries, then click "Begin Replication" to start the replication processing on the host. It will run for a short period (between a few seconds and several minutes, depending on host performance and application size).

2. When replication is completed, a status message box will appear, the replication tabs will be reset to their default values (preference values will be restored if they were previously loaded during this session), and the first tab will be brought to the top (made visible). At this point, you can continue with another replication process (for another database table or another existing Progress program), or you can end Replicator and complete the final steps for the current replication.

3. Use "ftp", or a combination of Jargon RDU and Notepad, or a similar file-transfer methodology to download the generated "<appl>.xml" file from the conversion directory on the host, to a subdirectory under "xml/" on the client.

4. Open the xml file in Jargon Writer.

5. Click "Generate 4GL" to generate the top-level ".p" program, which will be named as the 4GL Program Name entered on the "Additional Specs" tab. This program will be created under the "4gl/" subdirectory. Note that if the pathame of the ".p" program includes a subdirectory, then that subdirectory must exist under "4gl/" before clicking this button. For example, if the 4GL Program Name is "payroll/entry.p", then it will be created on the client as <Jargon Writer working directory>\4gl\payroll\entry.p".

6. Upload this generated program to the conversion directory on the host.

7. Compile, run, test and revise the generated program using Jargon Writer for the client app and a text editor of your choice for the host include files.

Advanced Techniques

As you gain experience with Jargon Replicator, you will find you can leverage this tool in ways that may not be obvious at first glance. Here are several examples.

Rearranging and removing fields

When generated a setup or query app for a database table, there may be a number of fields in the table that you don't want in the client window. Also, the order of the fields in the database table may not correspond to the way you want to group these fields in the user interface.

You could simply generate the app "as is", load the client procedure into Jargon Writer, then remove unwanted fields and use the drag and cut/paste features to rearrange fields and labels. However, this can take a while and also requires some work on the host side for fields that are removed (in the "disp.i" and "updt.i" include files).

There is a faster way to accomplish the same result, but it requires a little knowledge of how Replicator works. When you generate a setup or query for a database table, after you click the "Submit" button on the "Additional Specs" tab, the host task that is run will actually write a Progress program that displays all the fields for the selected table, in the Conversion Directory on the host.

For example, if your Conversion Directory is "test" and you are generating a query app for a table named "Customer", the program created by the host task will be "test/TCustomer.p". You can look at this table in any text editor (or the Progress editor) to see what it looks like. The "trick" is that you can also modify this program to remove or rearrange fields as desired, and have Replicator use the modified version, but only IF you do it at the right point in the process.

To use this technique (using the above example):

1. Fill in the parameters on the first two tabs, then click "Submit" on the "Additional Specs" tab.
2. WAIT for the host task to complete and the "Frame Specs" tab to appear.
3. BEFORE doing anything on the "Frame Specs", use RDU or a host text editor to modify the generated "test/TCustomer.p" program on the host.
4. THEN, complete the entries on the "Frame Specs" tab and click the "Submit" button on that tab, and continue as normal from there on.
5. The generated client and host procedures will now have only the fields you wanted, sequenced in the order you wanted. The amount of "tweaking" needed in Jargon Writer will be reduced significantly.

When generated a query app where you have a "Parent" table and one or more "Child" tables that have a many-to-one relationship to the Parent table, you might want to show all of the child records for a given parent record in a table format, especially if there are a relatively small number of child records per parent record.

For this design, the "secondary tables" feature in Replicator is not useful, since it will generate tabs containing a one-record display of all the fields for each child table (not a browse table). However, by generating browses separately for each child table, the desired result can be quickly reached by doing a little copying and pasting, and adding a little host code to tie things together.

For an example of such a query, see the "Human Resources" procedure in the new Sports2000 demo on the Jargon Software web site ( http://www.jargonsoft.com/jrxdemo.htm ). This has the "Employee" table as the parent table, showing one record per employee. For each employee, there are four child tables whose records are displayed in a table format: Benefits, Family Members, Timesheets and Vacations.

As the Online Help in this demo notes, this was created by using Replicator to create browse-only procedures for the four child tables and a query/browse procedure for the employee table. Then, four new tabs (and panels inside the tabs) were added to the tabpanel in the employee query, and the tables from the four child browse procedures were copied and pasted into these new tabs.

Finally, since most of the host code was already generated as well, we only needed to also display all the child records for the employee, using the four "<abbr>list.i" routines, whenever an employee record was displayed. Here is the code that was added to the "empget.i" include file to do that:

    /* Now do child tables for employee */

    {jsi/table/removeallitems.i &name='tblBenefits' }

    {jsi/table/removeallitems.i &name='tblFamily' }

    {jsi/table/removeallitems.i &name='tblTimesheet' }

    {jsi/table/removeallitems.i &name='tblVacation' }

    for each benefits of employee no-lock v-count = 0 to 9999:

      {demo2000/empbenlist.i}

    end.

    for each family of employee no-lock v-count = 0 to 9999:

      {demo2000/empfamlist.i}

    end.

    for each timesheet of employee no-lock v-count = 0 to 9999:

      {demo2000/emptimelist.i}

    end.

    for each vacation

       where vacation.empnum = employee.empnum

       no-lock v-count = 0 to 9999:

      {demo2000/empvaclist.i}

    end.

Remember to clear the tables before populating them, as shown above. Also note that the "v-count= 0 to 9999" phrase on the "for each" statements is needed for the "row number" parameter used in the various "<abbr>list.i" include files.