ReportWriter provides a number of subroutines and functions that you can overload, or override, with your own routines. You can name these routines anything you want, but you must register the name with ReportWriter using the RW_METHOD subroutine.
Some of these routines perform functions that you can adapt to your own requirements. For example, the RW_PRTCLOSE_METHOD routine supplied with ReportWriter closes the channel and submits the temporary report file to the default printer queue with the Synergy DBL LPQUE statement. You can overload this routine with one that prompts the user for a printer to which output should be sent instead of automatically printing to the default printer.
Other routines do nothing and are simply called to enable you to do any processing you desire at that point in the program. For example, if you want to map the open filename from AROxxx.ism to the actual data filename, which is based on the customer number, you can replace the empty RPS_FILNAM_METHOD routine with one that makes the necessary filename substitution.
The user-overloadable routines enable you to provide or modify the processing of user-defined file types, file definition open filenames, printer output channels, environment fields, user-defined data type fields, selection list item information, and report initialization.
You must put your overloaded routines in an ELB (or shared image on OpenVMS). You can either set the logical RWUSRLIB to point to this ELB, or, if you are using the external subroutine interface, you can pass the ELB name as a parameter to %RW_INIT. (See Accessing ReportWriter by external subroutine interface.) On OpenVMS, ReportWriter will call OPENELB on the shared image that is specified with RWUSRLIB or passed to %RW_INIT before attempting to call the routines.
ReportWriter user-overloadable routine names begin with “RW_”or “RPS_” and end with “_METHOD”. You will never call these routines directly; they are called only by ReportWriter. The following routines can be overloaded at runtime:
|
|
Overloading a user-overloadable routine in ReportWriter
| 1. | Write your customized routines, including RW_INIT_METHOD. (A sample routine is included with your Synergy/DE distribution in the file overload.dbl.) |
| 2. | If you’re not using the external subroutine interface to call ReportWriter, name the RW_INIT_METHOD routine USR_RW_INIT. |
If you are using the external subroutine interface, you can optionally pass the user_init argument to %RW_INIT to specify a different name for RW_INIT_METHOD.
| 3. | Compile the Synergy DBL source file(s) containing your customized routines. |
| 4. | If your customized routines are in more than one source file, use the librarian to create an OLB: |
|
On… |
Use this command… |
|---|---|
|
Windows and Unix |
dblibr -c library_file.olb source_1 source_2, … |
|
OpenVMS |
libr /create library_file source_1,source_2, … |
| 5. | Create an ELB or shared image file that contains your routines: |
|
On… |
Do this… |
|---|---|
|
Windows and Unix |
Link your routines as follows: dblink -l library_file library_file.olb |
|
OpenVMS |
Follow the guidelines in Building shared images. Edit the file rwusrbld.com. If you have changed the routine names from those specified in the documentation, find the “procedure” and “universal” entry for each routine and change it appropriately. Delete or comment out any unused entries. |
| 6. | Distribute the ELB or shared image, as well as ReportWriter, with your application. Set the RWUSRLIB environment variable to the full path and filename of the ELB or shared image you created in step 5. (You may want to add this step to your setup scripts.) Or, if you’re using the external subroutine interface to call ReportWriter, you can pass the user_routine_elb argument to %RW_INIT to specify a logical that points to the ELB or shared image. |
See Error messages (XCALL interface and overloading) for a list of error messages that might be generated.
Limitations of overloading
ReportWriter always overloads any EHELP_METHOD subroutine with TKP_HELP during processing.
If your application overloads the UI Toolkit close method subroutine (ECLOSE_METHOD), ReportWriter saves your close method’s address and logs its own close method. If the close method is called, ReportWriter explicitly calls your close method first. If your close method returns a_cancel as a nonzero value, the close method will be aborted. If a_cancel is returned as 0, ReportWriter will perform all tasks necessary for shut-down. If the user is prompted to save the report, Cancel is not an option in the message box. If your application doesn’t overload the close method, the user gets a Cancel option if prompted to save the report.
Overloading a UI Toolkit routine in ReportWriter (OpenVMS only)
On OpenVMS, if you are overloading ReportWriter routines with Toolkit routines that access Toolkit methods, and those methods don’t support an ELB (shared image) argument, you have to link the Toolkit methods so that ReportWriter can find them at runtime. You do this by creating a new ReportWriter main routine that wraps the ReportWriter executable and includes “dummy” calls to your overloaded Toolkit methods. When you link the new main routine with the shared image that contains your methods, you enable OpenVMS to find your methods within the image’s link map.
For example, say you want to use RW_PRTOPEN_METHOD and display a list of available printers. To build the Toolkit list, you would write a Toolkit list load method and register it with L_METHOD. Your version of RW_PRTOPEN_METHOD might look something like this:
subroutine MY_RW_PRTOPEN_METHOD . . . ; Register your list load method xcall L_METHOD (list_id, D_LLOAD, "MY_PRINTER_LIST") ; Begin list processing
MY_PRINTER_LIST is the Toolkit list load method you wrote. The Toolkit routine L_METHOD does not provide a way to register the shared image that MY_PRINTER_LIST resides in. Therefore, a call to MY_PRINTER_LIST must be included in your new ReportWriter main routine:
main MY_RPT
proc
xcall rpt_main ; Call ReportWriter program. This is equivalent to
; typing $RUN RPT:RPT.EXE at the command line
stop ; Processing stops here, so following not called
xcall MY_PRINTER_LIST ; Dummy call to your Toolkit list load method
endmain
After you write the main routine, compile it and link it with the SYNRPT shared image and the shared image you created that contains your methods. Then, use this new executable when you run ReportWriter instead of the distributed ReportWriter executable.
|
The RPT_MAIN subroutine is supported only for the use described above. Do not use it in any other way. |
