Welcome!

PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

Using The PFC Application / Utility Services

Using The PFC Application / Utility Services

In this month's column I'll present a simple Òhow toÓ on the PFC application and utility services, along with a simple description and code example for each service. They're among the least used in the PFC, but I've found them to be the most useful. These services are error, debug, and SQLSpy.

Error Service

WHAT IT DOES
The error service gives the application a standard interface in which to display error messages to the user and then log to a disk file. In addition, the service allows the error to be e-mailed to a system administrator (if a MAPI compliant e-mail system exists on the system).

HOW YOU USE IT
Like any application service, the developer must first turn it on. Type the following code in the inherited application manager object pfc_open event:

This.of_SetError(TRUE)

When the application manager is closed, the error service is automatically shut off. The developer can do the following with the error service:

  • Replace messageboxes within the application with more standard ones supplied by the error service.
  • Determine what errors are written to the error log.
  • Determine who gets e-mailed when an error occurs.
  • Load error messages from a disk file or database.

SHORT DISCUSSION
The primary job of the error service is to provide a standard set of error messages to an application. In most applications, if a validation or system error occurs, developers usually notify the user via a messagebox. One problem with this is that the text the developer includes within the messagebox may differ from the same error message written by another developer. With this in mind, the error service provides a single place where error messages are kept. Now instead of each developer coding his or her own messagebox, one call to the error service will display the messagebox. This guarantees consistent error notification throughout the application. In addition, error messages can now be held in one place rather than scattered throughout the code. If the verbiage or severity of an error has changed, the error message can be maintained in one stop.

The error service function that displays a messagebox, of_message(), is very flexible. The user can override the title and pass arguments to the messagebox generated by the error service. Passing arguments is beneficial when the error message to be displayed has an argument. For example, "Cannot save data until <blank> is entered."

When using a database as your error-message source, a second transaction object is needed to connect to the database that contains error-message information. This scenario ap-plies when SQLCA (if used) is already in use and pointing to a different database that's being used by the application. If your application connects to only one database, and that database contains the error-message table, then the second transaction object wouldn't be required.

DISPLAYING ERROR MESSAGES
Several options that relate to the error message display are available:

  • Display messages in a messagebox or PFC prebuilt dialog.
  • Set a time-out value so the message- box (or dialog) will close after a specified time if not responded to.
  • Choose not to display messages (override the error service).

TYPES OF ERROR DISPLAYS
Error messages may be displayed either in a messagebox or in the PFC prebuilt dialog. The command buttons and icons that appear on both are determined at runtime when a message is initiated using the function of_Message(). Icon choices include the following:

  • Information!
  • StopSign!
  • Exclamation!
  • Question!
  • None!
The acknowledgment button choices include:
  • OK!
  • OKCancel!
  • YesNo!
  • YesNoCancel!
  • RetryCancel!
  • AbortRetryIgnore!

USING THE DIALOG BOX
When using the PFC prebuilt dialog, the user can include a user input button and/or a print button. If used, the end user may input additional notes and/or send the error information to a printer. When the input button is clicked, the dialog expands to include an additional area for end-user input. To use the PFC prebuilt dialog box, call the of_SetStyle() function:

gnv_app.inv_error.of_SetStyle(1)

AUTOMATICALLY CLOSING THE ERROR MESSAGEBOX

You may choose to automatically close the error message if the user doesn't respond within a specified number of seconds. To do this you need to call the of_SetTimeout() function. The following line of code will close the error dialog in 10 seconds if the user doesn't respond.

gnv_app.inv_error.of_SetTimeOut(10)

This feature is available only when the PFC dialogs are used to display the error message.This function won't cause dialogs to close if a standard PowerBuilder messagebox is used.

WRITTING ERROR MESSAGES TO A LOG FILE

You may choose to have error messages of a specific severity (or higher) automatically written to a text file. For example:

// Specify the name of the log file
gnv_app.inv_error.of_SetLogFile("c:\errors\errlog.txt")

// Specify the severity of messages at which logging starts gnv_app.inv_error.of_SetLogSeverity(8)

The error file will be created if it doesn't already exist, as will the log file since it's appended to, not overwritten.

USING THE ERROR SERVICE
In this code example I'll enable the application error service. After turning the service on, I'll add the code to retrieve the error messages from a disk file, specify a log file to write error messages to, and code an error-service messagebox. This is the first step in enabling the error service. To do this, add the following code to the n_cst_myappmanager pfc_open event:

This.of_SetError(TRUE)
This.inv_error.of_SetPreDefinedSource("c:\pfctut\errors.txt") This.inv_error.of_SetLogFile("c:\pfctut\errorfile.txt") This.inv_error.of_SetLogSeverity(4)

CODE DESCRIPTION
The following function turns on the error service:

This.of_SetError(TRUE)
This function informs the error service that the error messages are contained in a tab-delimited file on the local drive:
This.inv_error.of_SetPreDefinedSource("c:\pfctut\errors.txt")

This file is then imported into a DataStore to be used by the error service until it's destroyed when the application closes. The format of the file is: Example

The PFC includes the d_defined-messages dataobject that contains columns that correspond to the information above. This dataobject is used to hold the error information if the error message source is either a text file or a database. Also, by default, the standard PowerBuilder messagebox is used to display error messages.

CODE DESCRIPTION
The error service uses the following file to keep a log of all errors that have occurred that are over the threshold error amount.

This.inv_error.of_SetLogFile("c:\pfctut\errorfile.txt")

The following line of code sets the error log threshold. On a scale of one to 10, one is the least severe server error while 10 is the most severe. In this case the severity is set to four. Error messages with a severity less than four won't be written to the error log file.

This.inv_error.of_SetLogSeverity(4)

Now that we've set up the error service, I can get the error message by simply calling a method on the object. The code below will show error message Ò100Ó as it appears in the flat file (or the database).

gnv_app.inv_error.of_message("100")

The messagebox shown in Figure 1 should display.
In a real application the of_message function would be placed in a DataWindow itemerror or itemchanged event. But for the sake of simplicity test the messages in a commandbutton clicked event.

WHAT IT DOES
The debug service allows the application to write messages to a debug log. This debug log can be opened and closed throughout an application. The programmer determines what and when messages are written to the debug log.

HOW TO USE IT
Like any application service, the developer must first turn it on. In the application manager object pfc_open event, type the following code:

This.of_SetDebug(TRUE)

When the application manager is closed, the debug service is automatically destroyed. The developer can do the following with the debug service:

    Write messages to the debug window.
  • Turn on the SQLSpy service from within the debug service.
  • Control the opening and closing of the debug log window.
  • Clear the log window of messages.
  • Print the contents of the debug window.
  • Inquire of the opened status of the debug window.

SHORT DISCUSSION
Unlike the error service, the debug service doesn't actually write to a disk file. The debug messages are held in a DataWindow within the debug window. Also, the developer can write messages to the debug log anywhere in a script. The function that writes to the debug window, of_message(), is usually called during critical portions of the application. For example, it's common to write to the debug log when windows open and close, and after data is retrieved from the database.

The debug window is a main window, not a sheet window. It can easily be ÒburiedÓ behind other windows in your application, including the MDI frame. If you want the debug window to be Òon top,Ó call the function of_setalwaysontop().

After turning the service on, you need to add the code to write entries to the debug window and then open and close it. To enable the debug service, add the following code to the n_cst_myappmanager pfc_open event:

This.of_SetDebug(True)
This.inv_debug.of_message("Debug Log Turned On")

CODE DESCRIPTION
The following function turns on the debug service:

This.of_SetDebug(True)

The next function writes an entry to the debug log:

This.inv_debug.of_message("Debug Log Turned On")

It's the only function that can be used to add entries to the debug window. Click on the debug command button to display the debug window (see Figure 2).

Any time you want to display the debug log, simply use the following code:

gnv_app.inv_debug.of_OpenLog(TRUE)

SQL Spy Service

WHAT IT DOES
The SQLSpy service allows the application to display and save SQL statements that are submitted to the database.

HOW YOU USE IT
Like any application/utility service, the developer must first turn it on. In the inherited application manager object pf_open event, type the following code:

gnv_app.inv_debug.of_SetSQLSpy(TRUE)

When the application manager is closed, the SQLSpy service is automatically destroyed. The developer can do the following with the SQLSpy service: Set a disk (log) file to keep a history of SQL statements.

  • Print the contents on the SQL history.
  • Control the opening and closing of the SQLSpy service window.
  • Clear the SQLSpy service history.

SHORT DISCUSSION
The SQLSpy service is a debug service for DataWindows. Whenever a DataWindow sqlpreview event is fired, the sqlsyntax is written to the SQLSpy service. The SQLSpy window is a main window, not a sheet window. It can easily be ÒburiedÓ behind other windows in your application, including the MDI frame. If you want the SQLSpy window to be Òon top,Ó call the function of_setalwaysontop().

To enable the SQLSpy service, the following code must be added to the n_cst_myappmanager pfc_open event:

gnv_app.inv_debug.of_SetSQLSpy(TRUE)

After turning the service on, code will be added to open the SQLSpy window and observe its contents.

To display the contents of the SQLSpy DataWindow, simply call the method to open it. The following code can be put in any event:

This.inv_debug.inv_sqlspy.of_openSQLSpy(TRUE)

The window in Figure 3 will keep a running history of all SQL statements to be submitted to the database.

Conclusion
The three services discussed above provide developers with a good set of development tools. Unlike the window and DataWindow services, the utility and application services were created with the developers in mind. Throughout the development cycle, these services will be very useful.
Next month I'll cover the application caching service. This service allows developers to store commonly used data in memory, thus saving database retrieves.
Thank you to Ron Van Zant from United Orange Growers in Gainesville, Florida, for this month's topic.

More Stories By Bob Hendry

Bob Hendry is a PowerBuilder instructor for Envision Software Systems and a frequent speaker at national and international PowerBuilder conferences. He specializes in PFC development and has written two books on the subject, including Programming with the PFC 6.0.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.