*PLUS/OBJ/WRAPUP Wrapup setup routine
 

This functionality is a +PxPlus Exclusive
Invocation: oHandle = NEW ( "*plus/obj/wrapup", program_entry$, param$ FOR { FILE fileno | WINDOW | PROGRAM | OBJECTobjid | CONTROL ctlid } )

Where:

oHandle The variable, which will receive the handle to the Wrapup object. Generally, this will not be used unless you wish to add additional parameters/properties to be passed to the wrapup logic. (See example below)
program_entry$ The string contains the name of the program and/or entry point to be called when the wrapup event occurs. If the entry point is in the current program, the program_entry$ can simply start with a semi-colon.
param$ A parameter string to be passed to the program_entry$ logic or, if no program/entry point specified, a directive to be executed when the wrapup occurs.
fileno The channel number of the file that when closed will initiate the wrapup logic.
objid The handle/id of the object that when deleted/dropped will initiate the wrapup logic.
ctlid The id, of the graphical control, that when deleted will initiate the wrapup logic.
   
Description The "*plus/obj/wrapup.pvc" object provides a simple means to establish 'Wrapup' procedures for any program exit, window/file closure or control/object release. This module allows you to establish a piece of code to execute or a routine to call whenever a wrapup related event occurs.

You can specify either the name of program/entry point to be called when the wrapup event occurs and an optional parameter to pass to it, or if the program/entry point is empty the system will simply issue an EXECUTE of the parameter field.

Whenever the program;entry is called it is passed two parameters. The first is the parameter string that was passed to the object creation when the NEW ( ) function was called. The second parameter is the object identifier of the wrapup object itself. The wrapup object allows the user to add additional properties so you pass additional values to the wrapup routine by simply assigning a value to a property in the wrapup object. The wrapup routine can access these properties using the object ID that will be passed as the 2nd param to the wrapup routine.
   
Timing of Event To have the event occur just prior the close of a file:

x = NEW( "*plus/obj/wrapup", "program;entry", "param" FOR FILE nnn)

To have the event occur before the current window is closed/dropped:

x = NEW( "*plus/obj/wrapup", "program;entry", "param" FOR WINDOW)

To have the event occur just before End/Exit/Return from current program:

x = NEW( "*plus/obj/wrapup", "program;entry", "param" FOR PROGRAM)

To have the event occur just before specified object is deleted/dropped:

x = NEW( "*plus/obj/wrapup", "program;entry", "param" FOR OBJECT objid)

To have the event occur just before specified control is deleted from the screen:

x = NEW( "*plus/obj/wrapup", "program;entry", "param" FOR CONTROL ctlid)
   
Passing additional values The wrapup object allows new properties to be dynamically created in the application. For example, if you wanted to save the original precision for subsequent restoration in the wrapup:

   oWrap = NEW("*plus/obj/wrapup",";Wrapup" FOR PROGRAM)
   oWrap'sv_prc = prc
   PRECISION 5

This would create a new property in the wrapup object so that in the Wrapup routine the original value could be retrieved using the 2nd parameter passed as in:

Wrapup:
   ENTER *,oWrap
   PRECISION oWrap'sv_prc
   EXIT
   
Examples If your program needed to set a system parameter, such as KR, but wanted to make sure it would be reset once the program was done regardless if the program exited normally or took and error exit:

Using EXECUTE:

   x = new("*plus/obj/wrapup","","SET_PARAM 'KR'="+STR(PRM('KR')) FOR PROGRAM)
   SET_PARAM 'KR'

When the program exited, the system would then EXECUTE the command to restore the 'KR' setting to its original state.

Using a Wrapup routine:

   x = new ("*plus/obj/wrapup",";Reset_KR" FOR PROGRAM)
   x'kr_value = PRM('KR') ! Create a property in the object
   SET_PARAM 'KR'
   
      ...
   
Reset_KR:
   ENTER *,objid
   SET_PARAM 'KR'=objid'kr_value
   RETURN

Either of these approaches assures that no matter how the program terminated, the parameter would be reset.