File Maintenance Generator

File Maintenance and Object Inheritance

When new panels are generated using the File Maintenance Generator, a file maintenance object with the following base structure is created or referenced (if existing):

! demo.pvc - File Maintenance Object
! Generated by File Maintenance on 29/03/19
!
DEF CLASS "demo"
!
LIKE "*win/fm_maint"
!
! Properties
PROPERTY _Update_Option$="R"
PROPERTY _New_Option$="0"
PROPERTY _Clear_Option$="0"
PROPERTY _Auto_Save_Option$="0"
PROPERTY _Confirm_New_Rec$="0"
PROPERTY _Acknowledge_Writes$="0"
PROPERTY _Confirm_Deletes$="1"
PROPERTY _Acknowledge_Deletes$="1"
!
END DEF

Initially, this object contains only the properties that correspond to the options in the Step 2: Properties panel for controlling the behavior of some of the file maintenance functions. The object also inherits the *win/fm_maint object, which contains methods necessary for the standard file maintenance functions to work. Objects in PxPlus have method names that correspond to the various controls on the panel. For this reason, any embedded panels that are selected in the File Maintenance Generator to replace the standard browse and action buttons must name these controls as follows:

Browse Buttons: BUTTON_FIRST, BUTTON_PRIOR, BUTTON_NEXT, BUTTON_LAST

Action Buttons: BUTTON_WRITE, BUTTON_DEL, BUTTON_CLEAR, BUTTON_CANCEL

The *win/fm_maint inherited object inherits the *nomads and *win/flmaintio objects and contains the following public methods:

	SetupMessages( )	DefaultChange( )
	PreLoad( )	DefaultInitialize( )
	PostLoad( )	DefaultFolderPostLoad( )
	DefaultOnFocus( )	OnExit( )

Browse Buttons:

	Button_First( )	Button_Prior( )
	Button_Last( )	Button_Next( )

Action Buttons:

	Button_Write( )	Button_Clear( )
	Button_Del( )	Button_Cancel( )

Interface Methods: (See Interface Methods below)

	FM_Init( )=1	FM_Post_Write( )=1
	FM_Post_Display( )=1	FM_Pre_Remove( )=1
	FM_Post_Read( )=1	FM_Post_Remove( )=1
	FM_New_Record( )=1	FM_Wrapup( )=1
	FM_Pre_Write( )=1

While any of these methods may be overridden in a user-defined object that inherits *win/fm_maint, the nine Interface Methods have been included to facilitate this.

In many file maintenance applications, it may be desirable to add "custom" code. The Interface Methods are run at various key points in the file maintenance process and simply return success. However, if methods of the same names are added to a user-defined file maintenance object, these methods will be run instead and can be coded to do whatever is necessary for the application. In some cases (as noted below), returning failure will change the file maintenance program behavior.

Interface Method	Description
FM_Init( )	This method is run after the Pre-Load logic for the panel. If it fails, CMD_STR$ is set to END, and the file maintenance panel will *not* be displayed.
FM_Post_Display( )	This method is run near the end of the main panel Post-Display logic and might be used to set initial values of variables or open additional data files. The return value is *not* checked.
FM_Post_Read( )	This method is run whenever a record is read from the data file being maintained, whether a particular key was entered or returned from a lookup, or a browse button was pressed. Failing this method will result in the next record (or prior record) being read instead, allowing particular records to be skipped. Adding this method but returning success could allow additional related data from other data files to be read as well.
FM_New_Record( )	This method is run when a new record key has been entered. The return value is *not* checked.
FM_Pre_Write( )	This method is run after a record is checked for any required fields but before the Write is actually done. Failing this method will result in the record *not being updated*. It is designed to be used for additional validation. It is assumed that, if the method is failed, some message box would probably be coded within the method to describe the reason for the record not being updated. Passing the method (or simply not including this method) allows the record to be updated.
FM_Post_Write( )	This method is run after the record has been updated and might be used to also update a related data file, sort file, etc. The return value is *not* checked.
FM_Pre_Remove( )	This method is run when the Delete button is pressed – before a possible confirm-delete question is displayed and before the record is deleted. It can be used to check other criteria before the record is deleted; e.g. checking history data files before deleting a customer record. Failing this method will preclude the record from being deleted. As with the FM_Pre_Write( ) method, a message box should be included to indicate why the record was not removed.
FM_Post_Remove( )	This method is run after a record is removed and can be used for various purposes, including removing data from related data files. The return value is *not* checked.
FM_Wrapup( )	This method is used to accomplish housekeeping tasks such as closing any secondary files that might have been opened or dropping any secondary objects that may have been instantiated. Since it happens when the object is about to be dropped, the return value is *not* checked.

Example:

The below example of a Demo class demonstrates a file maintenance object in which the FM_Post_Display, FM_Pre_Remove and FM_Wrapup methods have been added to allow a history file to be opened, checked prior to a delete and closed.

! demo.pvc - File Maintenance Object
! Generated by File Maintenance on 29/03/19
!
DEF CLASS "demo"
!
LIKE "*win/fm_maint"
!
! Properties
PROPERTY _Update_Option$="R"
PROPERTY _New_Option$="0"
PROPERTY _Clear_Option$="0"
PROPERTY _Auto_Save_Option$="0"
PROPERTY _Confirm_New_Rec$="0"
PROPERTY _Acknowledge_Writes$="0"
PROPERTY _Confirm_Deletes$="1"
PROPERTY _Acknowledge_Deletes$="1"
!
! Methods
FUNCTION FM_Post_Display()DEMO_POST_DISPLAY
FUNCTION FM_Pre_Remove()DEMO_PRE_REMOVE
FUNCTION FM_Wrapup()DEMO_WRAPUP
!
END DEF
!
DEMO_POST_DISPLAY:
OPEN (HFN,IOL=*,ERR=*NEXT)"Demo_History";
LET hist_fl=LFO
!
RETURN
!
DEMO_PRE_REMOVE:
IF NOT(hist_fl) \
   THEN RETURN 1
!
! _KEY$ is the key to be removed, key_len = length of key segment
LET hist_exists=0
SELECT * FROM hist_fl BEGIN PAD(_KEY$,key_len,$00$) END PAD(_KEY$,key_len,$00$)+$FE$
LET hist_exists=1
NEXT RECORD
!
IF NOT(hist_exists) \
   THEN RETURN 1
!
MSGBOX "Record '"+_KEY$+"' cannot be deleted because there is historic data still on file.","Unable to delete", \
        "!"
RETURN 0
!
DEMO_WRAPUP:
CLOSE (hist_fl,ERR=*NEXT);
LET hist_fl=0
!
RETURN

File Maintenance Generator

See Also