Release 6.3.4
Part Number A96501-01
 Contents |
 Index |
| Oracle Express Spreadsheet Add-In User's Guide Release 6.3.4 Part Number A96501-01 |
|
This chapter describes how Express callouts work in the API of Express Spreadsheet Add-In.
This chapter includes the following topics:
An Express callout is an Express program that contains custom logic related to a particular database activity. This program will be run by the add-in when a specified event, associated with a key point in database processing, occurs.
For example, you can choose to run a callout program before the add-in writes permanent changes to the database (that is, before the add-in sends an UPDATE command to Express).
The callout program must use arguments provided by the add-in as input. Typically one of the arguments is the name of the target database.
The add-in expects that the callout program will return the following two values in the SNAPI fetch buffer:
In order to specify when Express callout programs will run, you must register them. You can use one or both registration techniques, which are described in the following table.
If you register callout programs both automatically and programmatically, two callout programs run for each event. For example, suppose you automatically register a PostAttach callout program and you call the XPSetPostAttachCommand method. After a database is attached, the automatically registered callout program runs, then the program specified by the XPSetPostAttachCommand method runs.
If you register the same callout program for the same event both automatically and programmatically, the program runs twice.
To register callout programs automatically, create a registration variable in the data database, as explained in the following procedure.
Example: If your POSTATTACH program is called XP.MYPostAttach, enter this program name in the XSA.CALLOUTS variable for the POSTATTACH value.
To register callout programs programmatically, use one of the Express callout methods of the API.
In the Help system for Express Spreadsheet Add-In's API, search for "Registering Express Program Callouts."
In this example, assume that when a user chooses Commit from the Express menu, you want to insert custom logic to write changes to the data.db database rather than allow the add-in to perform the default behavior of sending an UPDATE command to Express.
You can accomplish this task by using the Express callout method XPSetPreCommitCommand with programmatic registration.
Write an Express program called PL.COMMIT to perform the desired custom logic. This program has the following requirements:
In a VBA procedure, after writing commands to perform various spreadsheet operations, programmatically register your program as an Express callout argument for the XPSetPreCommitCommand method. The following excerpt demonstrates sample code.
Sub x( ) < Commands for spreadsheet operations> . . . Call XPSetPreCommitCommand ("PL.COMMIT") End Sub
When a user chooses Commit from the Express menu, the add-in automatically runs the callout program and supplies the name of the target database, as shown in the following call.
Call PL.COMMIT ('DATA.DB')
When the callout program finishes performing its custom logic, it places return values in the SNAPI fetch buffer, as shown in the following example.
FETCH FALSE FETCH 'Your update processing completed successfully.'
When the add-in receives the FALSE return value, it does not send an UPDATE command to Express.
A CustomWriteCommand callout is an Express program that lets you replace the default behavior for writing changes to the database. To make this program available to the add-in, you must register the program by calling the XPSetCustomWriteCommand method.
Your program runs in Express when the user chooses Write from the Express menu. Your program must use the arguments provided by the add-in as input.
String. The name of the target database.
String. The write-back QDR script as a multiple-line argument.
Your program should return two values in the SNAPI fetch buffer:
A PostAttachCommand callout is an Express program that lets you insert custom logic associated with attaching a database. To make this program available to the add-in, you must register the program by calling the XPSetPostAttachCommand method.
Your program runs in Express immediately after the add-in attaches any database. Your program must use the argument provided by the add-in as input.
String. The name of the database.
Your program should return two values in the SNAPI fetch buffer:
A PostUpdateCommand callout is an Express program that lets you insert custom logic after the add-in writes permanent changes to the database (that is, performs an UPDATE command in Express). To make this program available to the add-in, you must register the program by calling the XPSetPostUpdateCommand method.
Your program runs in Express immediately after the add-in writes permanent changes to a database whose attach mode was switched from read-only to read/write. Your program must use the argument provided by the add-in as input.
String. The name of the database.
Your program should return two values in the SNAPI fetch buffer:
A PreCommitCommand callout is an Express program that lets you insert custom logic for writing permanent changes to the database. To make this program available to the add-in, you must register the program by calling the XPSetPreCommitCommand method.
Your program runs in Express immediately before the add-in writes permanent changes to the database (that is, sends an UPDATE command to Express). Your program must use the argument provided by the add-in as input.
String. The name of the target database.
Your program should return two values in the SNAPI fetch buffer:
A PrePageChangeCommand callout is an Express program that lets you insert custom logic before changing to a different page in the query. To make this program available to the add-in, you must register the program by calling the XPSetPrePageChangeCommand method.
Your program runs in Express immediately before the add-in changes to a different page in the query. Your program must use the arguments provided by the add-in as input.
String. The Express name of the dimension in the page whose status will change.
Integer. The current setting of the dimension in status. For example, if the dimension is set to the first value in status, the value of this argument is zero.
Integer. The position to which the page change will set the dimension. For example, the add-in will send the following command to Express if the user changes the PRODUCT page control from the first PRODUCT value in the list to the seventh PRODUCT value in the list.
call your.prepage.cmd('PRODUCT', 0, 6)
Your program should return two values in the SNAPI fetch buffer:
A PreRefreshCommand callout is an Express program that lets you insert custom logic before the add-in refreshes data from a database. The refresh can occur either as a result of a successful writeback of data or by the user choosing the Refresh menu option. To make this program available to the add-in, you must register it by calling the XPSetPreRefreshCommand method.
Your program runs in Express immediately before the add-in refreshes data from a database. Your program must use the argument provided by the add-in as input.
String. The name of the database.
Your program should return two values in the SNAPI fetch buffer:
A PreUpdateCommand callout is an Express program that lets you insert custom logic before the add-in writes permanent changes to a database (that is, sends an UPDATE command to Express). To make this program available to the add-in, you must register it by calling the XPSetPreUpdateCommand method.
Your program runs in Express immediately before the add-in writes permanent changes to a database whose attach mode was switched from read-only to read/write. Your program must use the argument provided by the add-in as input.
String. The name of the database.
Your program should return two values in the SNAPI fetch buffer:
|
 Copyright © 1997, 2002 Oracle Corporation. All Rights Reserved. |
|
