Jargon Building Blocks^TM
Developer Guidelines
Version 2.3 - December 2000

Contents

Overview

This document discusses how to:

• Create tree menus or tabpanel/button menus for an application
• Link HTML help documents to "Help" choices in client apps
• Use the various security features to limit what a user can do
• Use job scheduling features to run reports in the background
• Use output routing options to print, fax, email, view and save reports
• Log all add/change/delete actions to database tables

Menus

• Run a client app
• Run another menu
• View a document in a browser
• Invoke a tasklist to do other actions

Tabpanel/Button Menus

• Open "menuskel.xml" in Jargon Writer and save as your menu name (e.g. "bmenu01.xml").

 
• Put the name of this menu, without the ".xml" suffix, in the "defaultValue" attribute of the "hMyAppName" field in the "fHidden" frame (e.g. "bmenu01").

 
• On buttons that are valid menu choices, change the labels and tool tips to meaningful menu choice descriptions. Remove or disable unused buttons, or if left active then link their ActionEvents to the "TLFuture" tasklist.

 
• For each button that represents a client app or menu to be run, change the name of the button to the name of the client xml file, without the ".xml" suffix (e.g. to run "myapp01.xml", name the button "myapp01"). Also link the button's ActionEvent to the "TLRunApp" tasklist (for regular application programs) or the "TLRunMenu" tasklist (for other menus). It is important to use "TLRunMenu" for menus in order to create the proper linkage that allows the "Return to Previous Menu" button to work correctly.

 
• To view documents in a browser or to run other tasklists, create a new tasklist in the Task Editor and link the button's ActionEvent to this new tasklist to accomplish the desired action.

 
• If you want to enable the security option that locks out menu choices for which the current user does not have security access, put a comma-separated list of the button names to be tested for security in the "defaultValue" attribute of the "hMyPrograms" field in the "fHidden" frame. Buttons for which the user does not have security access will be disabled by a host task that checks these names against the security matrix table.

Tree Menus

• Open "tmenuskel.xml" in Jargon Writer and save as your menu name (e.g. "tmenu01.xml").

 
• Put the name of this menu, without the ".xml" suffix, in the "defaultValue" attribute of the "hMyAppName" field in the "miscHidden" container (e.g. "tmenu01").

 
• On tree nodes that are valid menu choices, change the text (label) values and tool tips to meaningful menu choice descriptions. Remove unused tree nodes. You can add intermediate nodes to provide grouping of choices to make it easier for users to find things.

 
• If you also have a comparable menu that uses the tabpanel/button style, the tree menu template provides a menu choice that allows the user to switch to this other menu type. To enable this feature for this tree menu, put the name of the comparable "tabpanel menu" xml file, without the ".xml" suffix, in the "defaultValue" attribute of the "hAlternateMenuApp" field in the "miscHidden" container (e.g. "bmenu01").

 
• For each tree node that represents a client app to be run, change the name of the node to the name of the client xml file, with a "x_" prefix, but without the ".xml" suffix (e.g. "x_myapp01"). Also put the name of the client xml file, without the ".xml" suffix, into the UserData attribute value (e.g. "myapp01").

 
• For each tree node that represents another menu to be run, change the name of the node to the name of the menu xml file, with an "m_" prefix, but without the ".xml" suffix (e.g. "m_tmenu02"). Also put the name of the menu xml file, without the ".xml" suffix, into the UserData attribute value (e.g. "tmenu02"). It is important to use this "m_" prefix for choices that are menus, in order to create the proper linkage that allows the "Back" button to work correctly.

 
• To view a document in a browser, change the name of the node to any unique name with a "d_" prefix (e.g. "d_userguide"). Put the full URL or file pathname of the document in the UserData attribute value (e.g. "http://www.xyz.com/doc/userguide.htm" for a Web server file or "x:\doc\userguide.htm" for a local file on the network).

 
• To invoke a special tasklist from a node, change the name of the node to any unique name with a "t_" prefix (e.g. "t_LoadDefaults"), and put the tasklist name to be invoked into the UserData attribute value (e.g. "TLLoadDefaults"). Also create the tasklist in the Task Editor, making sure the names are identical (including upper/lower case). Note that the tasklist to be invoked by the menu choice can only be within the same menu program, not in another xml app or other menu, since there is nowhere to specify an app name, only a tasklist name, in the node data. Of course, the invoked tasklist can simply invoke yet another tasklist in another app, so that provides an easy way to invoke any tasklist in any app.

 
• If you want to enable the security option that locks out menu choices for which the current user does not have security access, put a comma-separated list of the node names to be tested for security in the "defaultValue" attribute of the "hMyPrograms" field in the "miscHidden" container (e.g. "x_myapp01,x_myapp02"). Nodes for which the user does not have security access will be removed by a host task that checks these names against the security matrix table. (The host task will remove the "x_" prefix, etc.) Note that this is different from tabpanel menus, where choices are still visible though disabled. In trees, they are removed and never seen by the user.

 
• After completing the menu tree, including adding any desired intermediate nodes that are used to group menu choices, use the Task Editor to modify the tasklists that fully expand and fully collapse the tree (TLExpandTree and TLCollapse). There should be one client task for each intermediate node to be expanded/collapsed.

 
• To initially expand some of the branches of the menu tree when the app starts (in order to show certain menu choices as the default view of the tree), add one or more client tasks to the menu's initial tasklist, using the tree method "expandNode(parentNodeName)" in each client task to show the contents of that node.

Online Help

• Create an HTML help document using your favorite HTML editor.

 
• Put the document somewhere under the directory specified in the "Help Base URL" location in the "Output Routing" tab of the System Control table.

 
• Use "Online Help Index" setup to add a record to the x_help database table.
  • Assign the app name as the "Help Key" (e.g. "myapp01").
  • Put the pathname of the document (relative to the above "Help Base URL") in the "Document File" field (e.g. "app1/myapp01.htm").
  • Select Document Type "Proc" (for Procedure)
  • Add a descriptive name in the Document Title
  • Put a space-delimited list of useful search keys in the Keywords field, for use by the Building Blocks automatic indexing feature.

Application Security

The granularity of security testing can range from very broad (allowing all users in user group "AR" to have full access to all functions in all programs in an "AR" application module), to very specific (allowing user "tom" to only view certain fields from the customer table and only from 8-5 Monday-Friday). The security matrix can be set up with any combination of general and specific rules, since the tests look on a hierarchical basis for the most specific rule up to the most general rule.

Security tests are done in the following order. Note in particular that, since users can belong to 2 or more user groups, if their security for a given function in a given procedure is only set up at the group level, then their security level for that function (add/delete/view/update) is the highest security level of ANY of the groups to which they belong. To prevent this behavior, simply add a security matrix record for that UserID and Procedure ID with the desired permission levels.

1. Find the security matrix record for this UserID and Procedure ID.
2. If no record found in previous step, find the record for this UserID and Application Module.
3. If no record found in previous step, then step through each User Group to which this user belongs.
   • For each User Group, try to find a record for this Procedure ID.
   • If none is found, try to find a record for this Application Module.
   • Grant the highest permissions found across all records, which may combine permissions from different groups (e.g. one group grants "Add" permission and another group grants "Delete" permission).

To enable any security testing, the following steps must be done:

• Enable the desired security testing options in the Security tab of the System Control setup.

 
• Add User Group, User, Application Module and Procedure records to identify each user who will log in and each xml and host program that will be run.

 
• When creating a new xml procedure directly in Jargon Writer, specify that all host tasks for that xml procedure will run in one host program that has the same name as the xml file, plus a ".p" suffix.

  For example, for myapp01.xml, all host tasks should run a host program named "myapp01.p". Some security tests work on the xml filename, while others work on the host program name (without the suffixes in both cases), so using a common naming scheme reduces the number of Procedure and Security Matrix records needed.

The following sections describe how to implement various security functions.

Disabling unauthorized menu choices

To use this feature:

• In System Control setup, in the Security tab, enable (check) the checkbox labelled "Disable choices on User menus for which no access is allowed".

 
• In each menu, make sure all menu choices to be tested are in the comma-separated list of values in the "hMyPrograms" hidden textfield (see above).

 
• In the security matrix, add records as needed to prevent certain users from accessing certain procedures. Menu choices will be disabled or removed if the security values found for this user/procedure have:

  add=no delete=no viewLevel=0 updateLevel=0

  Choices will also be disabled or removed if the user is prevented from running the procedure due to a "Secured Period" (date/time) restriction.

Block running of unauthorized programs

If not, the host task will exit after displaying a message box with the text "You are not authorized to run this Procedure". The same message will also be displayed in a textpane named 'tnStatus' (by default) unless it is suppressed or redirected to a different textpane component name (see below).

The security values that will result in this message are the same as for disabling the menu choices (see above).

To use this feature:

• In each host task, be sure the input host parameters include the hUserID, hPassword and hSessionID from the x00login hidden fields.

 
• At or near the top of each include file named in a host task, add the include reference "{jsx/testuser.i}". This will verify the User ID and password, verify the session ID and its status (if sessions are enabled), and will find the most specific security matrix values for this user and procedure.

 
• To suppress sending the message to a textpane, use "{jsx/testuser.i 'none'}".

 
• To send the message to a different textpane, put the textpane name as an include parameter with single quotes, e.g. "{jsx/testuser.i 'myTextPaneName'}".

Selective blocking of unauthorized actions

This feature is done in addition to the previous test that can block running the entire program. To block certain actions, add the include reference "{jsx/securchk.i action [textpane option]}" after the "{jsx/testuser.i}" reference near the top of the include file named in the host task.

The "action" is a required include parameter that can be a variable or single-quoted literal which contains any of the following values:

• add - not authorized if "Add Allowed" is not checked
• delete - not authorized if "Delete Allowed" is not checked
• update - not authorized if "Update Level" is zero (0)
• view - not authorized if "View Level" is zero (0)
• browse - not authorized if "View Level" is less than nine (9)

The [textpane option] is an optional parameter that can suppress or redirect the message being sent to a textpane (same syntax as in previous section).

Here is an example from a "set.i" routine generated by Jargon Replicator which tests security for the add/change/delete logic in a file maintenance program.

assign v-src = tEventSrc.
if v-src matches "*Delete*" then
   v-action = "delete".
else
if v-src matches "*Apply*" and hAction = "Update" then
   v-action = "update".
else
if v-src matches "*Apply*" and hAction = "New" then
   v-action = "add".

/* CHECK USERID AND PASSWORD, MSG AND RETURN IF ERROR */
{jsx/testuser.i}
{jsx/securchk.i v-action }

Field-level view and update permissions

By testing these values, an inquiry program could display all information when xf_SecurViewLevel = 9, but only display some of the information at lower values 1-8, and display nothing at level 0.

Similarly, a host task in an initial tasklist could use the "xf_SecurUpdateLevel" values to selectively disable certain input textfields in the client xml application, to prevent the user from changing the values displayed into those fields.

Two other variables named "xf_SecurAddAllowed" and "xf_SecurDelAllowed" are also available for use if you want to directly control the actions taken when a user is not allowed to add and/or delete records, instead of using the "{securchk.i 'add'}" or "{securchk.i 'delete'}" tests shown in the previous section.

Miscellaneous application-specific security tests

If security is found at the UserID level (by Procedure or Application), these values will be from that specific record. If security is found at the User Group level, these values will be from the LAST group record found, which can be tricky to set up correctly. Consequently,these miscellaneous values are best used at the UserID level, not at the User Group level.

As an example for using these fields, an application designer might test xf_SecurValue1 for a comma-separated list of valid department codes that this user is authorized to use. This list would be put into the "Security Value 1" field of the security matrix record for this User ID and Procedure ID.

Output Routing and Background Job Scheduling

This utility is normally run after the user has entered selection criteria for the report or batch update procedure and clicked a "Submit" button. The selection criteria window is then hidden and the scheduling and output routing options window appears. After making all desired selections and entries for output routing and job scheduling, the user again clicks a "Submit" button in this window, which then initiates several host tasks which either run the host procedure immediately online, or add it to a job queue for background processing.

If the procedure is run online and "View in Browser" output is selected, a "View" button will be enabled in the selection criteria window upon completion of the host procedure, and when clicked, will open a web browser with the URL of a temporary HTML file on the host system to view the report or other output from the host procedure.

A template "xrepskel.xml" is provided which has the necessary hooks to the "x99sched.xml" utility procedure. To use this feature:

• Open xrepskel.xml in Jargon Writer and save as your report filename (e.g. "myreport01.xml")

 
• Put your xml filename (without the .xml suffix) in the "hMyAppName" hidden textfield in the "hHidden" frame (e.g. "myreport01").

 
• Add textfields, combo boxes or other components to the main frame of your app to allow the user to enter any required selection criteria for the report or batch update procedure.

 
• Add these components as Host Input Parameters to the "HTFinal" host task within the "TLFinal" tasklist

 
• Change the program and include file parameters for the "HTFinal" host task to names of your choice.

 
• Generate the ".p" Progress procedure for this xml app and copy to host system.

 
• Copy the jsx/repskel.i to use as a template for the business logic for your report or batch update procedure.

This TLFinal tasklist does a host task which submits any entered selection criteria, along with the UserID, password,sessionID, Job number and background scheduling option, as host input parameters. If a background option was chosen, these criteria will be stored in the job tables by the host task and it will immediately return to the client, with a message that the job has been scheduled.

This design does not provide a means to do host-side editing of the selection criteria before putting the job into the job queue. However, this can be easily done with a few minor changes:

• Add a new tasklist which does a host task to edit the selection criteria (which will be host input parameters for this host task). This host task will become a second internal procedure within the ".p" program for this app. Write the ".i" include file business logic as you would for any other host-side editing procedure.

 
• If the edits are okay, the last step in the host logic should invoke the "TLSubmit" tasklist in this app, otherwise if there are edit errors it should send back a warning message box or some other indication of the invalid entries and NOT invoke the TLSubmit tasklist.

 
• Change the Submit button and menu item to link to this new tasklist instead of TLSubmit

Output Routing Options

• Host Printer(s)
• Email Recipient(s)
• Fax Recipient(s)
• View in Client Web Browser, with option for local printing
• Save as a named text file in a common or user-specific directory

E-Mail
A sample API (Application Program Interface) for Email output via the UNIX "mailx" utility is provided in the "jsx/api" directory as "unixmail.p". You can modify this model program or copy it to a new name to interface to the specific email software on your host system.

Enter the name of this API in the "Email API" entry on the Output Routing tab in the System Control setup procedure. The output routing program passes three input parameters to this API program:

1. The pathname of the report file
2. A comma-separated list of value pairs for each recipient -- (1) email address (2) name
   Example: tom@xyz.com,Tom Smith,joe@xyz.com,Joe Brown
3. The title to use as the email "Subject" line

Enter the name of this API in the "Fax API" entry on the Output Routing tab in the System Control setup procedure. The output routing program passes two input parameters to this API program:

1. The pathname of the report file
2. A comma-separated list of value triplets for each fax recipient -- (1) their fax telephone number (2) their organization name (3) their individual name.
   Example: "555-1212,XYZ Inc,Tom Smith,555-2323,XYZ Inc,Joe Brown"

Background Job Scheduling

Note that you MUST use the repskel.i structure and do "report" output in any batch update program, in order to enable background processing capability for this host task. (Of course, it could simply create a report file saying "Job so-and-so ran okay"). In specific, the various "jsx/out***.i" include files are where background jobs are released into the queue to be run at a later point by the background job processor.

A user's update level in the security matrix for "x99sched" determines what job scheduling options can be used. This security matrix record can be specific to this User ID or it can default to record(s) for the User Group(s) to which this user belongs. The special meanings assigned to this update level for the "x99sched" Procedure ID are:

9 = all background job scheduling options are allowed
7 = no recurring background job scheduling allowed
5 = no recurring background job scheduling or one-time background scheduling at a specific date/time (only immediate background jobs allowed)
3 = no background scheduling of any kind

A sample UNIX script is provided in "jsx/runbatch.sh". This script will be used in the job processor control panel to add additional background job processors on demand.

In the script, specify the full pathname to "jsx/x90jobproc.p" as the startup program for the background session, using the Progress "-p" option for "mbpro". Output from the background session should be directed to a "batch.log" file in the J/P logs directory specified in the System Control "Directory for JP Logs" entry.

You should also set up UNIX 'cron' entries (or equivalent means on WinNT/2000) to start one or more background jobs whenever the database server(s) are started, so they do not have to be started manually each time. These automatic methods should run the same script described above, if possible, to avoid potential problems when future changes are made to the startup parameters.

Maintenance Logging

This feature can also be used by application programs wherever desired. Information which is captured in each record in the "x_log" table includes:

• Date of action
• Time of action
• User ID
• Session ID
• Database Table Name
• Value of first key in primary index
• Value of second key in primary index
• Comments
• Log Action (add, update, delete)

Where a table has more than two fields in its primary index, such as the x_security table, multiple keys can be put into the two key value fields that are provided in the x_log table, with the key values separated by a "/" character or other delimiter that would not occur in the key values themselves.

To use this logging feature in an application program:

• Add a reference to "{jsx/x15logvar.i "myTableName"}" within the "common include file" for your host program. If you are logging activity to two or more tables, do not repeat this include file reference for the second and subsequent tables, as the variable references within it will cause compile errors. Instead, enter a temp-table definition like that in the x15logvar.i file, e.g.

  def temp-table ttmyTable2  no-undo like myTable2.

• Within the include file that adds, updates or deletes a database record, capture the values of key fields, action type and field names being changed (etc), then after the database action is completed, run jsx/x15addlog.p with seven input parameters: UserID, SessionID, table name, key1 value, key2 value, action, comments.

  Here is an example based on the Building Blocks setup program for the x_group table. Only selective (edited) portions are shown here. See the jsx/x04groupset.i procedure for a complete view of the code and where these portions are located.

  /* jsx/x04group.i Top-level include for jsx/x04group.p */
  {jsx/x15logvar.i "x_group"}
  
  
  /* x04groupset.i Add/update/delete one record in a table */
     assign v-logkey1     = tGroupID
            v-logcomments = tDescription.  /* For x_log */
     if v-action = "delete" then
        delete x_group.
     else
     if v-action = "add" or v-action = "update" then do:
       if v-action = "add" then
          create x_group.
       else
          /* save original record for noting field changes for x_log */
          buffer-copy x_group to ttx_group.
       {jsx/x04groupupdt.i}
       if v-action = "update" then
          /* get list of changed fields for x_log */
          buffer-compare x_group to ttx_group save result in v-logcomments.
     end.
     /* create x_log record */
     run jsx/x15addlog.p ( hUserID, hSessionID, "x_group",
                        v-logkey1, v-logkey2, v-action, v-logcomments ).
  
  

  ---

  Up to Top      Help Index