Kbase 15815: Modifying ADM support code
| Autor |
Progress Software Corporation - Progress |
| Acesso |
Público |
| Publicação |
5/10/1998 |
|
Modifying ADM support code
Modifying the ADM support code
------------------------------
When developing an application using the Progress
ADM, it is best to leave the underlying support
code in its original state as shipped by Progress.
Solutions that work within the original framework
are recommended by Progress Technical Support; however,
there may be times when your application demands
functionality that is not provided and you may choose
to alter the underlying code. In these cases,
there are some guidelines that should be followed.
***DO NOT CHANGE the original code shipped with
Progress as you will need to compare new versions provided
by Progress with the original version to determine if changes
have been made. You may then wish to incorporate those changes
into your customized version of the code. Below, are 2
examples of how to make these changes and preserve the original
adm code.
How to augment the default ADM code
-----------------------------------
Use the ADM-DISPATCH-QUALIFIER so that you can create
your own prefix for routines in order to add functionality
to the original version of it. This will change it for each
and every object that includes it as opposed to the local
version which is just for one .w.
You can define ADM-DISPATCH-QUALIFIER to be 'custom'
(or any other prefix that you may wish to use)
so that you can write your own routine and name it, for example,
custom-open-query. Progress will first search for the local
prefix and then the custom and then the adm. If it finds the
custom it will run that one and not the adm version unless you
specifically tell it to do so (see step 2 below).
Here are some specific steps for the example of "wrapping"
your changes around the default adm-open-query that is found in
{src/adm/method/record.i}:
1. Create a new Method Library (a selection off of the UIB NEW
button) to create a new record.i. Save this NEW record.i in
a src/adm/method directory relative to the PROPATH so that
it is found ahead of the /dlc/src/adm/method version.
For example, save it in /mydlc/src/adm/method and make sure
your PROPATH includes c:/mydlc BEFORE c:/dlc.
2. In this new record.i, create a new procedure called
custom-open-query and place your code in that procedure.
After you have added your code,
RUN DISPATCH IN THIS-PROCEDURE(INPUT 'open-query':U)
to invoke the default adm-open-query when you are ready.
Note: you can replace the default adm-open-query totally
by omitting the above RUN DISPATCH statement; however, this
adds another level of procedure lookup. A better way to
totally replace the adm-open-query with your own version is
illustrated below in the section "How to replace a default
ADM procedure".
3. Be sure to include the original record.i using the full
{/dlc/src/adm/method/record.i} pathname in your new record.i.
This can be done in the UIB by pressing the Method Libraries
button in the Procedure Settings dialog of this new record.i.
4. Define ADM-DISPATCH-QUALIFIER in the definitions section
of your browse.w, smart.i or browse.i depending on how
inclusive you want this change to be. For instance, if you
want all smartQueries and smartBrowses to have this new
custom-open-query, then you can define the prefix in
the definitions section of smart.i. If you want it to ONLY
be available to smartBrowse objects then define it in
browse.i. If you want it only available to one browse.w
then define it in the definition section of the browse.w only.
Refer to ADM architecture section for further information.
In our example, we will include it in smart.i. First, create a
new MLI and save it in c:\mydlc\src\adm\method\smart.i.
Include the original smart.i as a method library in
the new smart.i (see step 3 above for details).
In the definitions section of smart.i, define the
ADM-DISPATCH-QUALIFIER like this:
&scoped-define ADM-DISPATCH-QUALIFIER custom
NOTE: 'custom' is an example and any name you choose can
be used here-- just remember to name your new
procedure with the same prefix.
How to REPLACE a default ADM procedure
--------------------------------------
Use the EXCLUDE-... pre-processor constant to exclude
compilation of the original version and to include your own
version into the product. Steps for implementing this can be
found in the UIB Developer's Guide in section 13.3.3. Here
is an example on how to replace the default adm-open-query
with one of your own:
1. Make a copy of record.i and save it in
c:\mydlc\src\adm\method.
2. Create a new structured include file called newinc.i
by choosing the NEW button from UIB main window and
selecting Structured Include, OK. The reason for using
a structured include as opposed to a new method library
include (MLI) is that the MLI automatically checks
for the EXCLUDE- preprocessor before defining new
procedures and the structured include does not. This
means that you will not inadvertantly EXCLUDE your
new procedure of the same name by mistake.
3. In the newinc.i (in the Definitions section), exclude all
of the internal procedures that you want to replace; for
example:
&GLOBAL-DEFINE EXCLUDE-adm-open-query YES
4. In the newinc.i (in the PRocedures section) write your own
version of adm-open-query and use the SAME NAME as the
original internal procedure. This version will be included
because it is not wrapped in a conditional Preprocess
statement.
5. In the record.i that is saved in c:\mydlc\src\adm,
reference the newinc.i. You can do this by bringing up
the record.i source, pressing Procedure button, pressing
Method libraries button and adding the newinc.i. Put in
the full pathname of the library.
6. Make sure your propath includes c:\mydlc before c:\dlc
7. Recompile any smartObjects that will reference record.i.
ADM Architecture
----------------
The diagram below shows how SmartObjects are built upon the adm
include files. Any changes made to the underlying include files
affects anything above it. For example, a change to record.i will
affect all viewers, browsers, and queries. Whereas a change to
viewer.w will affect all viewers.
___ ___ ___ ___ ___ ___ ___ ___
| | | | | | | | | | | | | | | |
SmartObject |.w | |.w | |.w | |.w | |.w | |.w | |.w | |.w |
Masters |___| |___| |___| |___| |___| |___| |___| |___|
_________ _________ _________ __________
| | | | | | |cntnrwin.w|
Templates | viewer.w| |browser.w| | query.w | |cntnrfrm.w|
|_________| |_________| |_________| |cntnrdlg.w|
|__________|
_________ _________ _________ __________
Object | | | | | | | |
Specifics | | | | | | | |
| viewer.i| |browser.i| | query.i | |containr.i|
|_________| |_________| | | | |
_____________________ | | | |
| tableio.i | | | | |
|_____________________| |_________| | |
_________________________________ | |
| record.i | | |
|_________________________________| |__________|
______________________________________________
ADM Core | smart.i/attribut.i |
|______________________________________________|
Support Policy
--------------
Refer to knowledgebase entry: 16918 ADM Modification Support Policy
In some cases, you may decide to change the underlying code to
overcome a Progress bug that you have encountered. This is a
choice that only you can make but the guidelines in the knowledgebase
entry mentioned above as to what is supported and what isn't still
applies. It is always best to call Progress Technical Support when a
bug has been found so that it can be logged and fixed in the original
This will ensure better quality in the Progress product and also
eliminate the need for you to keep track of versions
and changes as they occur in your Application as well as the
Base Product.
Other References
----------------
UIB Developer's Guide Chapter 13 Section 3
Kbase 16167, "Statement to Programmers on New Releases of ADM code"
Progress Software Technical Support Note # 15815