cObject
---BusinessProcess
Business Processes are used to contain and execute the statements to perform a batch process on an application's database tables, together with the data dictionaries containing the business rules applicable to the process.
This sample batch process creates ten test customers. The process cannot be interrupted. If an error occurs during the save, an error message will be displayed and the process will stop.
Object CreateCustomers is a BusinessProcess
Set Process_Title To "Let's add some test customers"
Object Customer_DD is a Customer_DataDictionary
End_Object
Procedure onProcess
Integer i
Handle hoServer
Boolean bNotOK
Move (Customer_DD(Self)) to hoServer
For i from 1 to 10
Send Update_Status ("Adding Test Customer #" *String(i) *"of 10"))
Send Clear of hoServer
// add any data we need into our DD Buffer
Set Field_Changed_Value of hoServer FIELD Customer.Name to "Test"
Set Field_Changed_Value of hoServer FIELD Customer.Etc to "Etc."
Get Request_Validate of hoServer to bNotOk
If (bNotOk) ;
Procedure_Return
Send Request_Save of hoServer
If (Err) ;
Procedure_Return
Loop
End_Procedure
End_Object
Filename.bp file:
Object name is a BusinessProcess
//Set properties
:
//Create process's DDO structure
:
Procedure OnProcess
:
End_Procedure
End_Object
End of file filename.bp
Filename.vw file:
Object oReportName is a ReportView
:
#INCLUDE filename.bp // include the batch-process plug-in name
//User-interface object
Procedure DoIt // assume some button sends this
Send DoProcess of ObjectName
End_Procedure
End_Object
End of file filename.vw
BPOs can also be added to normal views to handle special batch-update conditions. Just plug in the BP and send DoProcess to it.
Object oViewName is a dbView
#INCLUDE filename.bp // include batch-process plug-in name
Procedure DoIt // assume some button starts this
Send DoProcess of (Name(Self))
End_Procedure
:
//Create view's DDO structure
:
//Create DEOs
:
End_Object
It is important to understand the difference between the OnProcess and DoProcess messages. It is expected that you will start a BPO process by sending the message DoProcess to the object. This is how the process is started. However, you will very rarely ever augment or change the DoProcess procedures - that is the job of OnProcess.
OnProcess is the event that we expect you to customize to actually run the process. That is where you drop your custom code. You will never explicitly send the message OnProcess. That is what DoProcess is used for.
If you are calling OnProcess directly, very little will work properly. When you do this, you are not allowing the BPO to initialize itself before starting and to de-initialize itself upon completion. You will get no status panel, no error redirection (which is crucial), and no status logging.
Restated:
You create a business process exactly like you create a report view. The business process is just a different type of plug-in. Business processes automatically support status panels (which optionally support cancellation) and error redirection handling (during processing, all errors are redirected to the BusinessProcess object). BPOs also support a message protocol for logging process activity.
A BPO consists of a non-visual object that contains a DDO structure and the logic to run the process. Normally a process is called by sending the message DoProcess. This is a predefined message that intializes the object (Start_Process), sends the event message onProcess, and then closes the process (End_Process).
The heart of the process is the onProcess procedure. It is the main processing loop. By default it does nothing and it is expected that you will place your process code in this procedure. You should try to process all database activity through the DDO structure. To do this, you must send messages to the appropriate DDO. These messages will most-likely include:
The first time a DDO is used, it performs some initializations. These initializations can change the status of the DDO (latching on to a buffer or clearing a buffer), which might also change the contents of a table's record buffer. If you are performing a DD record find (e.g., Find, Request_Find, Request_Read) with a DataDictionary that is the part of a BusinessProcess (BPO), you should send a Clear_All to the DDO at the start of the process. This makes sure that the DDO structure is initialized before you perform any manual buffer changes prior to your DDO find request. Just clearing the buffer with a find command will not suffice.
For Example:
Send Clear_All of oCustomer_DD // do this at the start of the process
Move 5 to Customer.Customer_Number
Send Request_Find to oCustomer_DD Ge Customer.File_Number 1
While (Found)
Send ProcessDDRecord
Send Request_Find to oCustomer_DD Gt Customer.File_Number 1
Loop
By default, request_save does not perform field validation. You must get Request_Validate to the DDO to perform field validation. Request_save is then sent if the field validation was OK (returned 0). Note the validate_save is always called as part of request_save. We separate the field validation from saving because this is a batch process and you may wish to optimize this process by not performing field validation on every field in every DDO that is part of the save. We provide the ability to do the validation, but give you the flexibility to skip it.
During a batch process, all errors are redirected to the BPO. When an error occurs, the message Error_Report is sent to the BPO. Depending on how several properties are set, the BPO will handle the error in different ways. If Display_Error_State is true, the error will get redirected to the standard DataFlex error object, which will cause the error message to be displayed in a message box. Since you normally do not want interactive error messages displayed during a batch process, this property defaults to false. If a status-log object is defined and Status_Log_State is true, errors will get logged in the status file. Error_Report does this by sending the message Error_Status_Log. If status logging is not enabled, the program code could send this message itself. In addition, the message OnError is sent. You can use this to handle custom errors any way you want. Finally, errors set the Err indicator true. You can use this information within your batch-processing loop to determine how and whether a process should continue.
By default, Cancel_Check stops the status panel if an error has occurred or the user has clicked the Cancel button to stop the process. To resume the status panel's display when resuming processing, send Resume_Status.
Since you control the processing loop, you can control whether and how the process should be canceled. A message is provided which you may use that will check for a cancel (from the status panel) or an error (from the error). A complete interface is provided to support this.
Status Logging Status logging refers to a defined interface for sending information to a status-logging object. Various properties and methods are created within BPOs to support easy status logging. The program must set the property Status_log_Id to the object ID of the status-log object. It can then set the property Status_Log_State to true. When true, a log entry is sent when a BPO process is started, a BPO process is ended, and when an error occurs. Additional status lines can be sent by sending the message Log_Status passing the text to be logged.
The actual interface to the status-log object consists of two public messages: Log_Status and Log_Clear. It is the status-log object's responsibility to do something useful with these messages. The prototype log object provided with DataFlex (found in StatLog.pkg and StatFLog.pkg) writes a log entry consisting of date, time, and comment to a simple table. It is expected that you may wish to expand upon this logging process by extending the table (e.g., adding a user name), its indexes, by moving the log file to another filelist entry, or by expanding the interface (e.g., add ability to review the log, sort by user name). The log object was purposely kept simple. It does however provide basic multi-user logging.
By default, Cancel_Check stops the status panel if an error has occurred or the user has clicked the Cancel button to stop the process. To resume the status panel's display when resuming processing, send Resume_Status.
pbSmartRelate controls whether DataDictionaries perform relates on parent tables that are not connected to the DDO (DataDictionary Object) structure. By default, this is set to True in the DataDictionary class , meaning that relates on parent tables not in the DDO structure are not performed.