28 Creating BRM Client Applications by Using the MTA Framework
This chapter describes the Oracle Communications Billing and Revenue Management (BRM) multithreaded application (MTA) framework and how to use the framework to create BRM multithreaded client applications.
Before using the MTA framework, you must be familiar with the following:
-
BRM flists and storable classes. See "Understanding Flists and Storable Classes".
-
PCM opcodes and PIN libraries. See "Understanding the PCM API and the PIN Library".
-
Error handling routines. See "Understanding API Error Handling and Logging".
About the BRM MTA Framework
You use BRM multithreaded application (MTA) framework to create customizable multithreaded BRM client applications. A multithreaded application uses multiple threads that run in parallel to process a single task. By using multiple worker threads, BRM MTAs are able to process jobs more quickly.
BRM MTAs use a standard program structure, making it easier to code and maintain. In each application, one main thread is responsible for getting data from the BRM database, and a number of worker threads process the job in parallel. The BRM MTA framework manages all thread handling seamlessly, allowing your application to ignore thread management.
Typically, you use a multithreaded BRM client application when you have a large job that can be grouped into batches and processed concurrently. For example, BRM's pin_deferred_act, pin_bill_accts, pin_collect, and pin_cycle_fees billing utilities use the MTA framework to retrieve information from the BRM database for the accounts that they process.
The BRM MTA framework is based on a multi-layered architecture that allows you to create customizable BRM MTAs. For information about this architecture, see "BRM MTA Framework Layers".
The BRM MTA framework provides function and opcode hooks that you implement to create customizable multithreaded applications. Each callback function and policy opcode is called at fixed places during application execution. For information about these execution stages, see "MTA Stages".
Information about the application, such as configuration settings and search flists are stored in a global flist. The global flist makes application information available to all three layers: Framework, Application, and Customization. For information about the global flist structure, see "MTA Global Flist Structure".
Function hooks are provided as MTA callback functions, which you use to implement your application's business logic in the Application layer. See "Creating a Multithreaded BRM Client Application".
Opcode hooks are custom policy opcodes that you write to customize the business logic in the Customization layer. See "Customizing BRM Multithreaded Client Applications".
Each callback function and policy opcode provides a specific functionality. For details, see "Using the BRM MTA Framework".
BRM MTA Framework Layers
The BRM MTA framework has three layers:
-
Framework layer
This layer is implemented at the application tier in the BRM four-tier architecture. This layer implements the main thread that controls application workflow. The main thread performs database searches, distributes jobs to worker threads, and calls the callback functions in the Application layer and the custom policy opcodes in the Customization layer.
-
Application layer
This layer is implemented at the application tier. This layer consists of the MTA callback functions. You use callback functions to implement your application business logic, such as calling billing opcodes to perform billing or generate invoices.
-
Customization layer
This layer is implemented at the Connection Manager (CM) tier. This layer consists of custom policy opcodes. You use policy opcodes to customize the application business logic implemented in the Application layer.
Figure 28-1 shows the architecture of the BRM MTA framework layers:
Figure 28-1 BRM MTA Framework Architecture
Description of ''Figure 28-1 BRM MTA Framework Architecture''
MTA Stages
Each BRM multithreaded application has a standard program structure and standard execution stages. The main thread manages the application workflow by calling the MTA functions and policy opcodes in a set order at each execution stage.
Figure 28-2 shows the BRM MTA execution stages and workflow.
Figure 28-2 BRM MTA Execution Stages and Workflow
Description of ''Figure 28-2 BRM MTA Execution Stages and Workflow''
MTA_CONFIG Execution Stage
Each BRM multithreaded client application requires a configuration file (pin.conf) and can have command-line parameters. The MTA framework performs default application configuration based on the information in the pin.conf file and command-line parameters. You can write custom policy opcodes to provide custom configurations.
The main thread calls the following MTA callback functions and the custom policy opcode hook in this order:
MTA_INIT_APP Execution Stage
Application initialization occurs after the application has been configured successfully. The main thread spawns a number of worker threads, and the application completes all tasks that are required before the main search execution is performed.
The main thread calls the following MTA callback functions and the custom policy opcode hook in this order:
MTA_INIT_SEARCH Execution Stage
During search initialization, the search flist is prepared. This flist is provided as the input to the search opcodes. You can write custom policy opcodes to modify the search flist.
The main thread calls the following MTA callback functions and the custom policy opcode hook in this order:
Search Execution
At the search execution stage, the main thread calls the search opcodes (PCM_OP_SEARCH, PCM_OP_STEP_SEARCH, and PCM_OP_STEP_NEXT) to find the objects or search results.
Note:
The search results are sent to the client a block at a time. The block size is equal to the fetch size specified in the application's pin.conf file. The search opcodes are called as many times as needed until all the search results are received. For more information, see "Configuring your Multithreaded Application".MTA_TUNE Execution Stage
After a block of search results is passed to the application, the results can be tuned or modified before they are distributed in batches to the worker threads for processing.
The main thread calls the following MTA callback functions and the custom policy opcode hook in this order:
Job Distribution
The basic purpose of a BRM multithreaded client application is to manage the distribution of a job to worker threads. After search execution and search results tuning, the main thread adds the search results to the job pool and notifies worker threads to begin processing.
MTA_JOB_DONE Execution Stage
After worker threads have been notified of an available job in the job pool, the main thread waits for notification back from the worker threads that their assigned jobs are completed. When all results from the main search have been processed and the job pool is empty, the next search cycle is executed until there are no more search results remaining in the database.
The main thread calls the following MTA callback functions and the custom policy opcode hook in this order:
MTA_EXIT Execution Stage
When there are no more jobs to process, the application terminates all threads, closes the database connection, and exits.
The main thread calls the following MTA callback functions and the custom policy opcode hook in this order:
MTA_WORKER_INIT Execution Stage
Worker threads are spawned at the application initialization stage. After initialization, the worker threads remain in wait mode until they are notified by the main thread of an available job in the job pool.
The following MTA callback functions and the policy opcode hook are called in this order by each worker thread:
MTA_WORKER_JOB Execution Stage
After worker threads have been notified of an available job in the job pool, they receive their assigned batch of search results and then call the main opcode to process the work. The input flist for the main opcode is prepared here prior to the opcode call.
The following MTA callback functions and the policy opcode hook are called by each worker thread in this order:
Worker Thread Job Execution
Each worker thread calls the "pin_mta_worker_opcode" callback function and passes the search results for processing.
MTA_WORKER_JOB_DONE Execution Stage
When worker threads have completed their assigned job, they notify the main thread and return to wait mode until more work becomes available.
After a worker thread has completed its job, it calls the following callback functions and policy opcode hook to perform any required tasks:
MTA_WORKER_EXIT Execution Stage
Worker threads are terminated when there are no more jobs for the application to process.
The following MTA callback functions and the custom policy opcode hook are called in this order by each worker thread to perform any tasks before the thread exits:
MTA Global Flist Structure
The BRM MTA framework includes a global flist that stores information specific to the application, such as configuration settings, search flists, and search results. Information stored in the global flist is accessed by the MTA callback functions and custom policy opcodes.
The global flist contains the following fields:
0 PIN_FLD_CONFIG_OBJ SUBSTRUCT [0] 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 0 PIN_FLD_SEARCH_FLIST SUBSTRUCT [0] 0 PIN_FLD_SEARCH_RESULTS SUBSTRUCT [0] 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0]
The PIN_FLD_CONFIG_OBJ substruct is populated with information from the /config/mta object. This information is used by the BRM MTA framework to determine which custom policy opcodes to call during application execution. For more information about the fields in the PIN_FLD_CONFIG_OBJ substruct, see "Configuring the MTA Policy Opcodes".
The PIN_FLD_APPLICATION_INFO substruct contains the application's configuration settings.
This substruct includes the following fields:
0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] 1 PIN_FLD_CHILDREN INT [0] 1 PIN_FLD_STEP_SIZE INT [0] 1 PIN_FLD_BATCH_SIZE INT [0] 1 PIN_FLD_FETCH_SIZE INT [0] 1 PIN_FLD_NUM_RETRIES INT [0] 1 PIN_FLD_FLAGS INT [0] 1 PIN_FLD_MAX_ERROR INT [0] 1 PIN_FLD_MAX_TIME INT [0] 1 PIN_FLD_HOTLIST_FILENAME STR [0] 1 PIN_FLD_MONITOR_FILENAME STR [0] 1 PIN_FLD_LOGFILE STR [0] 1 PIN_FLD_LOGLEVEL INT [0] 1 PIN_FLD_POID_VAL POID [0]/*Specifies the DB no.
where:
-
PIN_FLD_NAME is the application name.
-
PIN_FLD_FLAGS contains application bit flags. Flags can be added by Application layer and Customization layer developers. See pin_mta.h for the default MTA flags.
For details about all other PIN_FLD_APPLICATION_INFO substruct fields, see "Configuring your Multithreaded Application".
The PIN_FLD_SEARCH_FLIST substruct contains the search flist that is passed to the search opcodes.
This substruct includes the following fields:
0 PIN_FLD_SEARCH_FLIST SUBSTRUCT [0] 1 PIN_FLD_POID POID [0] 1 PIN_FLD_FLAGS INT [0] 1 PIN_FLD_TEMPLATE STR [0] 1 PIN_FLD_ARGS ARRAY [1] 2 PIN_FLD_XXX STR [0] 1 PIN_FLD_RESULTS ARRAY [0] 2 PIN_FLD_XXX POID [0] 1 PIN_FLD_FILENAME STR [0] 1 PIN_FLD_COUNT INT [0]
For details about these fields, see "Configuring your Multithreaded Application".
The PIN_FLD_SEARCH_RESULTS substruct contains the search flist that is passed to the search opcodes.
This substruct includes the following fields:
0 PIN_FLD_SEARCH_RESULTS ARRAY [0] 1 PIN_FLD_MULTI_RESULTS ARRAY [0] 2 PIN_FLD_RESULTS ARRAY [0] 3 PIN_FLD_XXX POID [0]
where:
-
PIN_FLD_MULTI_RESULTS is an array containing the search results. The number of results is equal to the step size specified in the pin.conf file.
-
PIN_FLD_RESULTS is an array that specifies the objects received from the database.
The PIN_FLD_EXTENDED_INFO substruct is reserved for the Customization layer.
The PIN_FLD_OPERATION_INFO substruct contains statistics and audit-related information.
This substruct includes the following fields:
1 PIN_FLD_PID INT [0] 1 PIN_FLD_HOSTNAME STR [0] 1 PIN_FLD_START_T TSTAMP [0] 1 PIN_FLD_THREAD_INFO ARRAY [0] 2 PIN_FLD_START_T TSTAMP [0] 2 PIN_FLD_END_T TSTAMP [0] 2 PIN_FLD_ERROR_INFO ARRAY [0] 3 PIN_FLD_ERROR_NUM INT [0] 3 PIN_FLD_SYS_ERROR_NUM INT [0] 3 PIN_FLD_ERROR_CODE STR [0] 3 PIN_FLD_ERROR_DESCR STR [0] 3 PIN_FLD_TRACKING_ID STR [0]
where:
-
PIN_FLD_PID specifies the process ID number.
-
PIN_FLD_HOSTNAME specifies the host where the application runs.
-
PIN_FLD_START_T specifies the process or main thread start time.
-
PIN_FLD_END_T specifies the process end time.
-
PIN_FLD_ERROR_NUM specifies the total number of errors for all threads.
-
PIN_FLD_SYSTEM_ERROR_NUM specifies the total number of system errors.
-
PIN_FLD_ERROR_CODE specifies the error code from the application pinlog file.
-
PIN_FLD_ERROR_DESCRIPTION is the description of the error from the application pinlog file.
-
PIN_FLD_TRACKING_ID specifies the correlation ID from the application pinlog file.
Using the BRM MTA Framework
The BRM MTA framework is compiled as a static library. It provides a set of callback functions as hooks that you implement to develop multithreaded client applications for BRM.
What the MTA Framework Includes
The MTA framework is included in the BRM SDK. For installation instructions and an overview, see "About BRM SDK".
The MTA framework includes the files listed in Table 28-1, in the BRM_SDK_Home directory:
Table 28-1 Files Included in MTA Framework
| File | Description |
|---|---|
|
/include/pin_mta.h |
MTA header file |
|
/lib/libmta.a |
MTA library file |
|
/bin/pin_mta_monitor |
Sample monitoring utility |
|
/source/apps/mta_sample/pin_mta_test.c |
Sample application using the MTA framework |
|
/source/apps/mta_sample/Makefile |
Makefile to build the sample application, pin_mta_test.c |
|
/source/apps/mta_sample/pin.conf |
Sample configuration file |
MTA Callback Functions
The BRM MTA callback functions (see Table 28-2) are hooks. You implement the functions in your application by providing application-specific contents.
Important:
You do not have to implement all of the callback functions; however, you must implement pin_mta_config to process application command-line parameters, pin_mta_init_search to specify search criteria, and pin_mta_worker_opcode to specify the main opcode call. You implement other functions as needed.Table 28-2 MTA Callback Functions
| Function | Description |
|---|---|
|
Can be used for default application configuration. |
|
|
Can be used for any tasks that are required before the application exits. |
|
|
Can be used for application initialization and all required tasks before execution of main search. |
|
|
Can be used for preparation of the search flist. |
|
|
Can be used for any tasks that are required after search results have been processed, such as validation and logging. |
|
|
Can be used for post-configuration tasks such as configuration validation and logging. |
|
|
Can be used for any tasks that are required before the application exits, such as validation and logging. |
|
|
Can be used for any post-initialization tasks such as initialization validation and logging. |
|
|
Can be used for any tasks that are required after search initialization, such as validation and logging. |
|
|
Can be used for any tasks that are required after search results have been processed, such as validation and logging. |
|
|
Can be used for any tasks that are required after search results have been tuned, such as validation and logging. |
|
|
Can be used to display application help information. |
|
|
Performs any cleanup tasks and logging after a worker thread exits. |
|
|
Can be used for any tasks that are required after worker threads are initialized, such as validation and logging. |
|
|
Can be used for any validation of the search results received by worker threads as well as any logging that is required. |
|
|
Performs any cleanup tasks and logging that are required after a worker thread completes its assigned job. |
|
|
Can be used for any filtration and tuning of the search results before the results are distributed to worker threads. |
|
|
Can be used to prepare application help information for display. |
|
|
Performs cleanup tasks and other functions required before a worker thread exits. |
|
|
Can be used for initialization of the worker thread. |
|
|
Can be used to prepare the main opcode input flist. |
|
|
Can be used for any functions that are required after a worker thread completes its assigned job. |
|
|
Executes the main opcode to process the job. |
MTA Helper Functions
Table 28-3 lists the MTA helper functions used to manipulate data in global flist data structures.
Table 28-3 MTA Helper Functions
| Function | Description |
|---|---|
|
Loads decimal fields from the pin.conf file. |
|
|
Loads integer fields from the pin.conf file. |
|
|
Loads string fields from the pin.conf file. |
|
|
Gets the global flist field; does not set the lock on the field; multithread unsafe. |
|
|
Gets the global flist field; sets the lock on the field to prevent access; multithread safe. |
|
|
Puts the global flist field to the flist specified; multithread safe. |
|
|
Releases the lock from the global flist field; multithread safe. |
|
|
Sets the global flist field to the flist specified; multithread safe. |
|
|
Gets the main thread context. |
MTA Policy Opcode Hooks
This section lists MTA policy opcode hooks.
All MTA policy opcodes use Transition: supports.
For information about the flist specification, see Opcode Flist Reference.
To customize your BRM multithreaded client application, you implement the MTA policy opcode hooks (listed in Table 28-4) in your application by providing application-specific contents.
Note:
You do not have to implement all of the policy opcodes. You specify your own policy opcode names. For example, for MTA_CONFIG policy opcode, you might use PCM_OP_MTA_POL_CONFIG.Table 28-4 MTA Policy Opcode Hooks
| Policy opcode | Description |
|---|---|
|
Called at MTA_CONFIG execution stage. Allows customization of the default application configuration. |
|
|
Allows processing of error notifications. |
|
|
Called at MTA_EXIT execution stage. Allows any processing that may be required before the application exits. |
|
|
Called at MTA_INIT_APP execution stage. Allows customization of the default application initialization. |
|
|
Called at MTA_INIT_SEARCH execution stage. Allows customization of the search flist. |
|
|
Called at MTA_JOB_DONE execution stage. Allows any processing that may be required at the completion of search results processing. |
|
|
Called at MTA_TUNE execution stage. Allows modification of the search results. |
|
|
Allows display of application help information. |
|
|
Called at MTA_WORKER_EXIT execution stage. Allows any processing that may be required before the worker thread exits. |
|
|
Called at MTA_WORKER_INIT execution stage. Allows customization of worker thread initialization. |
|
|
Called at MTA_WORKER_JOB execution stage. Allows modification of search results received by the worker thread and preparation of the input flist passed to the main opcode. |
|
|
Called at MTA_WORKER_JOB_DONE execution stage. Allows any processing that may be required at completion of the worker thread job assignment. |
Creating a Multithreaded BRM Client Application
Before you create a multithreaded BRM client application, you should have a good understanding of the BRM MTA execution flow and the global flist structure. See "About the BRM MTA Framework".
You create a multithreaded BRM client application by implementing the MTA callback functions in your application and by providing application-specific content.
These callback functions are called by the MTA framework at fixed execution points to configure, initialize, search, process data, and exit the application. For information about the syntax and description of these functions, see "MTA Callback Functions".
The BRM MTA framework supports three search options; see "Searching Different Data Sources".
For information about displaying usage information, see "Displaying Application Help Information".
For processing errors that occur during application execution, see "Error Notifications".
The sample file BRM_SDK_Home/source/samples/apps/c/mta_sample/pin_mta_test.c provides sample implementations of MTA callback functions. Use this as a code sample to build your own multithreaded application. For information on how to compile and run the sample application, see "About Using the PCM C Sample Programs" in BRM Developer's Reference.
For general information on creating new client applications, see "Adding New Client Applications".
Each BRM client application has its own configuration file (pin.conf). After you build your application, you need to create a configuration file. See "Configuring your Multithreaded Application".
To customize your multithreaded application, you implement the MTA policy opcode hooks. See "Customizing BRM Multithreaded Client Applications".
Searching Different Data Sources
The BRM MTA framework supports three search options: search for objects stored in the BRM database, search for objects stored in a file, and passing objects directly to the search opcode. You specify the search option in the PIN_FLD_SEARCH_FLIST substruct in the global flist.
To search for objects in the BRM database, you specify the POID of the /search object that defines the search template.
For example:
0 PIN_FLD_SEARCH_FLIST SUBSTRUCT [0] 1 PIN_FLD_POID POID [0] "/search/pin" –1 0 1 PIN_FLD_FLAGS INT [0] 0 1 PIN_FLD_TEMPLATE STR [0] "select X from /account where F1 = V1" 1 PIN_FLD_ARGS ARRAY [1] 2 PIN_FLD_FIRST_NAME STR [0] "name" 1 PIN_FLD_RESULTS ARRAY [0] 2 PIN_FLD_POID POID [0]
To search for objects in a file, you specify the name of the file where the objects are stored.
For example:
0 PIN_FLD_SEARCH_FLIST SUBSTRUCT [0] 1 PIN_FLD_FILENAME STR [0] "file name" 1 PIN_FLD_COUNT INT [0] 2
Important:
The file specified in PIN_FLD_FILENAME must be a text file and must have the same format as the search results flist.The following is an example of the text file:
0 PIN_FLD_RESULTS ARRAY [0] 1 PIN_FLD_ACCOUNT_OBJ POID [0] "/account" 123 0 0 PIN_FLD_RESULTS ARRAY [1] 1 PIN_FLD_ACCOUNT_OBJ POID [0] "/account" 345 0
To pass objects directly in the search flist, you specify the POIDs of the objects.
For example:
0 PIN_FLD_POID POID [0] 0.0.0.1 /account 1 0 0 PIN_FLD_RESULTS ARRAY [0] 1 PIN_FLD_ACCOUNT_OBJ POID [0] "/account" 123 0 0 PIN_FLD_RESULTS ARRAY [1] 1 PIN_FLD_ACCOUNT_OBJ POID [0] "/account" 345 0
Important:
When objects are provided in the search template, the data is taken from PIN_FLD_SEARCH_FLIST and put into PIN_FLD_SEARCH_RESULTS. Do not free memory from PIN_FLD_SEARCH_FLIST, otherwise the application will error out. If your application performs the search operation in a loop, add new data to PIN_FLD_SEARCH_FLIST node by preparing the flist in the pin_mta_init_search function. The application will exit as soon as no new data is provided in PIN_FLD_SEARCH_FLIST node.For information about the search flist and search results flist, see "MTA Global Flist Structure".
Displaying Application Help Information
The BRM MTA framework provides callback functions that you can implement in your application to display application help information. The usage callback function is called by specifying the -help parameter in the command line or when the application fails to configure or initialize because the command-line options specified were invalid or incomplete. When an error occurs during application configuration, the MTA framework sets the PIN_FLD_FLAGS field in the PIN_FLD_APPLICATION_INFO substruct in the global flist. For a list of all predefined flags, see pin_mta.h.
Note:
The command-line parameters -help, -verbose, and -test are processed by the MTA framework layer. When these parameters are specified with additional parameters (for example, -verbose xyz), the framework layer processes the -verbose parameter and ignores xyz. In this case, you might want to display a usage error message in your custom application. To do this, set the MTA flag in the pin_mta_config callback function as follows:mta_flags = mta_flags | MTA_FLAG_VERSION_NEW
When this flag is set, the MTA framework generates a usage error when the -help, -verbose, or -test parameter is specified with additional parameters.
To display application help information, the main thread calls the following callback functions and the policy opcode hook in this order for the -help, -verbose, or -test parameters:
You implement pin_mta_usage to prepare the help text message, and you implement pin_mta_post_usage to display the message. You can customize the help text by implementing the usage policy opcode hook.
Important:
You must set the PIN_FLD_DESCR field in the PIN_FLD_EXTENDED_INFO substruct in the global flist to the help text, so that it can be accessed by the usage policy opcode and pin_mta_post_usage.Depending on the parameter specified in the command line, the framework layer processes the parameters as follows:
-
-help: Sets the PIN_FLD_FLAGS field in the PIN_FLD_APPLICATION_INFO substruct in the global flist to MTA_FLAG_USAGE_MSG, calls pin_mta_usage and then pin_mta_exit, and displays the valid command line options on the standard output.
-
-verbose: Sets the PIN_FLD_FLAGS field in the PIN_FLD_APPLICATION_INFO substruct in the global flist to MTA_FLAG_VERBOSE_MODE, flushes the stdout buffer, and displays the number of data errors encountered, the total number of errors encountered, and the additional output for threads information on the standard output.
-
-test: Sets the PIN_FLD_FLAGS field in the PIN_FLD_APPLICATION_INFO substruct in the global flist to MTA_FLAG_TEST_MODE and displays the total number of prepared job units for batch processing and the total number of spawned worker threads on the standard output.
For information about the global flist, see "MTA Global Flist Structure".
The application usage policy opcode is called only if it's configured in /config/mta. See "Configuring the MTA Policy Opcodes".
Error Notifications
In a multithreaded application, errors can occur in the main thread or the worker threads. In BRM MTA, errors that occur in the main thread are handled differently than errors in the worker threads.
Generally, an error in the main thread is an indication of a serious problem that prevents the application from continuing its normal execution. When an error occurs in the main thread, the BRM MTA framework exits the application immediately.
Errors that occur in the worker threads are not as severe and therefore it is not necessary for the application to exit immediately. When an error occurs in a worker thread, the MTA framework checks to see if the maximum error threshold has been reached. The MTA framework exits the application when the number of errors in the worker threads exceeds the threshold.
When the application exits due to error conditions, the MTA framework calls the error notification policy opcode to allow exit processing that may be required at the Customization layer.
Important:
The error notification policy opcode is called by the BRM MTA framework only if it is configured in /config/mta. See "Configuring the MTA Policy Opcodes".You can implement the error notification policy opcode in your application to process errors. For information about the input and output flist, see "MTA_ERROR".
Customizing BRM Multithreaded Client Applications
Before you customize a multithreaded BRM client application, you should have a good understanding of the BRM MTA execution flow and the global flist structure. See "About the BRM MTA Framework".
The BRM MTA framework provides policy opcode hooks for customization of BRM MTAs. For example, you can create a custom billing utility by customizing BRM's pin_bill_accts MTA. You implement these policy opcode hooks by providing your business-specific contents.
These policy opcode hooks are called by the BRM MTA framework at fixed places during the application execution. Unlike the MTA callback functions, the MTA policy opcode hooks must be configured using the /config/mta object.
To customize a BRM MTA, you need to do the following:
Implementing the MTA Policy Opcodes
You use the MTA policy opcode hooks to customize multithreaded BRM client applications. They do not have default implementations; therefore, they aren't in the BRM System Facilities Modules (FM). You need to write a custom policy FM to include your custom policy opcodes.
The policy opcode hooks do not have predefined opcode names; you create your own. For example, you could name the MTA_CONFIG policy opcode PCM_OP_MTA_POL_CONFIG.
For more information about writing a custom FM, see "Writing a Custom Facilities Module".
Important:
The MTA policy opcode hooks have predefined input and output specifications. You must write your custom policy opcodes based on these specifications.For a list of all the policy opcodes and details about the input and output specifications, see "MTA Policy Opcode Hooks".
Configuring the MTA Policy Opcodes
The MTA policy opcodes are called by the main thread at specific execution stages in the application workflow. At application startup, the MTA framework reads the /config/mta object to determine if custom policy opcodes are implemented at the Customization layer.
You use testnap or Developer Center to populate the PIN_FLD_OPCODE_MAP array in the /config/mta object to specify the policy opcode names and the execution stages that these opcodes are called from.
For information about the fields and field types in /config/mta, see /config/mta.
Important:
The execution stage names are predefined. You must use these names when populating the PIN_FLD_FUNCTION field in the /config/mta object. Otherwise, the application will not load the object at startup and instead it will exit. For details about the policy opcode and its execution stage names, see "MTA Policy Opcode Hooks".In this example, the MTA application pin_mta_test calls custom policy opcodes at the MTA_CONFIG, MTA_INIT_ERROR, and MTA_USAGE execution stages:
0 PIN_FLD_CONFIG_MTA ARRAY [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_OPCODE_MAP ARRAY [0] 2 PIN_FLD_FUNCTION STR [0] "MTA_CONFIG" 2 PIN_FLD_NAME STR [0] "PCM_OP_MTA_POL_CONFIG" 1 PIN_FLD_OPCODE_MAP ARRAY [1] 2 PIN_FLD_FUNCTION STR [0] "MTA_ERROR" 2 PIN_FLD_NAME STR [0] "PCM_OP_MTA_POL_ERROR" 1 PIN_FLD_OPCODE_MAP ARRAY [2] 2 PIN_FLD_FUNCTION STR [0] "MTA_USAGE" 2 PIN_FLD_NAME STR [0] "PCM_OP_MTA_POL_USAGE"
In this example, the MTA application pin_mta_test calls custom policy opcodes at the MTA_INIT_SEARCH, MTA_TUNE, and MTA_WORKER_JOB_DONE execution stages:
0 PIN_FLD_CONFIG_MTA ARRAY [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_OPCODE_MAP ARRAY [0] 2 PIN_FLD_FUNCTION STR [0] "MTA_INIT_SEARCH" 2 PIN_FLD_NAME STR [0] "PCM_OP_MTA_POL_INIT_SEARCH" 1 PIN_FLD_OPCODE_MAP ARRAY [1] 2 PIN_FLD_FUNCTION STR [0] "MTA_TUNE" 2 PIN_FLD_NAME STR [0] "PCM_OP_MTA_POL_TUNE" 1 PIN_FLD_OPCODE_MAP ARRAY [2] 2 PIN_FLD_FUNCTION STR [0] "MTA_WORKER_JOB_DONE" 2 PIN_FLD_NAME STR [0] "PCM_OP_MTA_POL_WORKER_JOB_DONE"
In extremely rare cases, you might create a dynamic library to implement custom MTA callback functions that is not feasible by using the MTA policy opcodes.
You can use the /config/mta object to specify custom callback functions. In this case, you must populate the PIN_FLD_FUNCTION_MAP array to map the custom function name to the MTA callback function name. The function names specified in PIN_FLD_FUNCTION must match the default MTA callback function names. The MTA framework will call the custom callback function instead of the default callback function. For a list of all MTA callback functions, see "MTA Callback Functions".
important:
If custom functions are configured, the MTA framework calls the custom function in place of the default MTA callback function. In this case, the default functionality is lost.0 PIN_FLD_CONFIG_MTA ARRAY [0] 1 PIN_FLD_LIBRARY STR [0] "libpin_mta_test_lib.so" 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_FUNCTION_MAP ARRAY [0] 2 PIN_FLD_FUNCTION STR [0] "pin_mta_post_init_app" 2 PIN_FLD_NAME STR [0] "pin_mta_post_init_app_lib" 1 PIN_FLD_FUNCTION_MAP ARRAY [1] 2 PIN_FLD_FUNCTION STR [0] "pin_mta_post_tune" 2 PIN_FLD_NAME STR [0] "pin_mta_post_tune_lib" 1 PIN_FLD_FUNCTION_MAP ARRAY [2] 2 PIN_FLD_FUNCTION STR [0] "pin_mta_config" 2 PIN_FLD_NAME STR [0] "pin_mta_config_lib" 1 PIN_FLD_FUNCTION_MAP ARRAY [3] 2 PIN_FLD_FUNCTION STR [0] "pin_mta_init_search" 2 PIN_FLD_NAME STR [0] "pin_mta_init_search_lib" 1 PIN_FLD_FUNCTION_MAP ARRAY [4] 2 PIN_FLD_FUNCTION STR [0] "pin_mta_tune" 2 PIN_FLD_NAME STR [0] "pin_mta_tune_lib"
Configuring your Multithreaded Application
The sample configuration file in the BRM_Home/source/samples/apps/C/mta_sample/pin.conf directory specifies the configuration information for a multithreaded application to connect to the BRM database and process data. (BRM_Home is the directory in which you installed BRM components.)
For each multithreaded application that you create, you need to include a similar configuration file in your application's directory with entries specific to the application.
For a list of configuration file entries, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Note:
You can create additional configuration entries that are required for your MTA application.Applying Configuration Entries to Specific Utilities
To apply an entry to all the MTA applications, use pin_mta. For example:
-
pin_mta children 5
-
pin_mta fetch_size 10000
-
pin_mta per_batch 100
To apply an entry only to a particular MTA, use pin_application_name. For example, pin_bill_accts:
-
pin_bill_accts children 5
-
pin_bill_accts fetch_size 10000
-
pin_bill_accts per_batch 100
Using Multithreaded Applications with Multiple Database Schemas
To use a multithreaded application with a multischema BRM installation, you must change the multi_db entry in the application pin.conf file. For example, to use the global search feature to search across schemas, you must enable multischema support. Set the multi_db entry to 1 to enable multischema support.
MTA Policy Opcode Hooks
This section lists MTA policy opcode hooks.
MTA_CONFIG
This policy opcode allows customization of the default application configuration.
This policy opcode is called by the MTA framework at the MTA_CONFIG execution stage. It is called after pin_mta_config. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to perform custom application configuration. For example, you can write code to retrieve configuration parameters from a database object.
Important:
This policy opcode is called only if it is configured in the /config/mta object. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_ERROR
This policy opcode allows processing of error notifications.
This policy opcode is called by the MTA framework when an error occurs in the main thread or when the maximum error threshold has been reached for the worker threads. You set the maximum error limit in the application's pin.conf file. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to process error notifications at the Customization layer.
For example, you can write code to log appropriate error messages in the application's log file.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input from a worker thread.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 7 1 PIN_FLD_STEP_SIZE INT [0] 3 1 PIN_FLD_BATCH_SIZE INT [0] 2 1 PIN_FLD_FETCH_SIZE INT [0] 8 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_OBJ_TYPE STR [0] "/config/mta" 1 PIN_FLD_LOGFILE STR [0] "a.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_ATTRIBUTE INT [0] 8 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 157 1 PIN_FLD_OPS_ERROR INT [0] 1000 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_THREAD_INFO ARRAY [7] 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003 1 PIN_FLD_ERROR_INFO ARRAY [0] 2 PIN_FLD_ERROR_NUM INT [0] 1 2 PIN_FLD_SYS_ERROR_NUM INT [0] 0 2 PIN_FLD_ERROR_CODE STR [0] "PIN_ERR_NOT_FOUND" 2 PIN_FLD_ERROR_DESCR STR [0] "\t <location=PIN_ERRLOC_DM:4 class=UNKNOWN:0 errno=PIN_ERR_NOT_FOUND:3>\n\t <field num=0:0,0 recid=0 reserved=0 reserved2=0 time(sec:usec)=0:0>\n\t <facility=0 msg_id=0 version=0>\n" 2 PIN_FLD_TRACKING_ID STR [0] "1:plot:pin_mta_test:26291:7:8:1062547949:3"
MTA_EXIT
This policy opcode allows any processing required before the application exits.
This policy opcode is called by the MTA framework at the MTA_EXIT execution stage. This is when there are no more jobs to be processed. This policy opcode can also be called when an error occurs during application execution. This policy opcode is called after pin_mta_exit. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to process errors, perform logging, clean up procedures, or other functionality.
For example, you can write code to process errors and to log appropriate error messages in the application's log file.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003 1 PIN_FLD_THREAD_INFO ARRAY [8] 2 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003 2 PIN_FLD_END_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003 1 PIN_FLD_THREAD_INFO ARRAY [4] 2 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003 2 PIN_FLD_END_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_INIT_APP
This policy opcode allows customization of the default application initialization.
This policy opcode is called by the MTA framework at the MTA_INIT_APP execution stage. It is called after pin_mta_init. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to perform custom application initialization.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_INIT_SEARCH
This policy opcode enables customization of the search flist.
This policy opcode is called by the MTA framework at the MTA_INIT_SEARCH execution stage. It is called after pin_mta_init_search. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to modify the search flist that is passed to the search opcodes PCM_OP_SEARCH, PCM_OP_STEP_SEARCH, and PCM_OP_STEP_NEXT. In a multischema search, the search flist is passed to PCM_OP_GLOBAL_SEARCH, PCM_OP_GLOBAL_STEP_SEARCH, and PCM_OP_GLOBAL_STEP_NEXT.
For example, you can use this opcode to customize information in the search template.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_SEARCH_FLIST SUBSTRUCT [0] 1 PIN_FLD_POID POID [0] 0.0.0.1 /search/pin -1 0 1 PIN_FLD_FLAGS INT [0] 0 1 PIN_FLD_TEMPLATE STR [0] "select X from /data where F1 = V1 " 1 PIN_FLD_ARGS ARRAY [1] 2 PIN_FLD_HEADER_NUM INT [0] 155 1 PIN_FLD_RESULTS ARRAY [0] 2 PIN_FLD_POID POID [0] NULL poid pointer 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_JOB_DONE
This policy opcode allows any processing required at completion of search results processing.
This policy opcode is called by the MTA framework at the MTA_JOB_DONE execution stage. This is after the worker threads have completed their assigned jobs, there are no more search results to process, and the job pool is empty. This policy opcode is called after pin_mta_job_done. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to perform validation, logging, or other functionality that may be required.
For example, you can write code to analyze the percentage of a job that was processed successfully and to create a log of those threads that failed.
If another search is required, you can write code to loop through the search cycle again.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_TUNE
This policy opcode allows modification of the search results.
This policy opcode is called by the MTA framework at the MTA_TUNE execution stage. This opcode is called after pin_mta_tune. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to preprocess the search results before they are distributed to the worker threads for processing.
For example, you can write code to perform validation of the search results and to modify or filter the results.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_SEARCH_RESULTS SUBSTRUCT [0] 1 PIN_FLD_MULTI_RESULTS ARRAY [0] 2 PIN_FLD_POID POID [0] 0.0.0.1 /search/pin -1 0 2 PIN_FLD_RESULTS ARRAY [0] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data 1 1634 2 PIN_FLD_RESULTS ARRAY [1] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data 2 1631 2 PIN_FLD_RESULTS ARRAY [2] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data 3 1633 1 PIN_FLD_MULTI_RESULTS ARRAY [1] 2 PIN_FLD_POID POID [0] 0.0.0.1 /search/pin -1 0 2 PIN_FLD_RESULTS ARRAY [0] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data/sequence 300 151 2 PIN_FLD_RESULTS ARRAY [1] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data/sequence 302 1633 2 PIN_FLD_RESULTS ARRAY [2] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data/sequence 303 1631 1 PIN_FLD_MULTI_RESULTS ARRAY [2] 2 PIN_FLD_POID POID [0] 0.0.0.1 /search/pin -1 0 2 PIN_FLD_RESULTS ARRAY [0] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data/sequence 304 1279 2 PIN_FLD_RESULTS ARRAY [1] 3 PIN_FLD_POID POID [0] 0.0.0.1 /data/sequence 305 1277 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_USAGE
This policy opcode allows display of application help information.
This policy opcode is called when the user explicitly requests the application's usage information by specifying the -help parameter at the command line. This policy opcode is also called by the MTA framework during application configuration when it fails to configure the application using the command-line parameters specified. This policy opcode is called after pin_mta_usage. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to customize help information.
For example, you can write code to display a custom help message for custom command-line options.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_OPERATION_INFO SUBSTRUCT [0] 1 PIN_FLD_PID INT [0] 2485 1 PIN_FLD_HOSTNAME STR [0] "test" 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_WORKER_EXIT
This policy opcode allows any processing required before the worker thread exits.
This policy opcode is called by the MTA framework at the MTA_WORKER_EXIT execution stage. This is when the worker thread is notified that the application is about to exit. This policy opcode is called after pin_mta_worker_exit. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to perform any cleanup procedures or other functionality before the worker thread is terminated.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_THREAD_INFO ARRAY [4] 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_WORKER_INIT
This policy opcode allows customization of worker thread initialization.
This policy opcode is called by the MTA framework at the MTA_WORKER_INIT execution stage. It is called after pin_mta_worker_init. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement for customization of worker thread initialization.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_THREAD_INFO ARRAY [4] 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_WORKER_JOB
This policy opcode allows modification of search results received by worker threads and preparation of the input flist passed to the main opcode.
This policy opcode is called by the MTA framework at the MTA_WORKER_JOB execution stage. This is when the worker thread has received a batch of search results to be processed and the worker thread prepares the input flist that is passed to the main opcode responsible for processing the search results in the batch. This policy opcode is called after pin_mta_worker_job. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you implement to perform any processing required before the main opcode is executed.
For example, you can write code to modify the main opcode input flist or to modify the search results in the batch.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_IN_FLIST SUBSTRUCT [0] 1 PIN_FLD_POID POID [0] 0.0.0.1 /data 1 1634 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_THREAD_INFO ARRAY [4] 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA_WORKER_JOB_DONE
This policy opcode allows processing required after worker thread job completion.
This policy opcode is called by the MTA framework at the MTA_WORKER_JOB_DONE execution stage. This is when the worker thread notifies the main thread that it has completed processing the batch of search results and is waiting for the next batch. This policy opcode is called after pin_mta_worker_job_done. See BRM Developer's Reference.
By default, this policy opcode is an empty hook that you can implement to perform any processing that may be required after the worker thread has completed the assigned job.
For example, you can write code to validate or analyze the output flist from the main opcode call.
Important:
This policy opcode is called only if it is configured in the /config/mta. See "Configuring the MTA Policy Opcodes".Sample Input Flist
This is a sample input flist for pin_mta_test.c.
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/mta 15380 0 0 PIN_FLD_APPLICATION_INFO SUBSTRUCT [0] 1 PIN_FLD_NAME STR [0] "pin_mta_test" 1 PIN_FLD_CHILDREN INT [0] 2 1 PIN_FLD_STEP_SIZE INT [0] 5 1 PIN_FLD_BATCH_SIZE INT [0] 10 1 PIN_FLD_FETCH_SIZE INT [0] 100 1 PIN_FLD_NUM_RETRIES INT [0] 0 1 PIN_FLD_FLAGS INT [0] 2 1 PIN_FLD_MAX_ERROR INT [0] 5 1 PIN_FLD_MAX_TIME INT [0] 360 1 PIN_FLD_HOTLIST_FILENAME STR [0] "hotlist" 1 PIN_FLD_MONITOR_FILENAME STR [0] "monitor" 1 PIN_FLD_LOGFILE STR [0] "mta.pinlog" 1 PIN_FLD_LOGLEVEL INT [0] 3 1 PIN_FLD_POID_VAL POID [0] 0.0.0.1 /account 1 0 1 PIN_FLD_INCR_AMOUNT INT [0] 1 1 PIN_FLD_HEADER_NUM INT [0] 155 0 PIN_FLD_OUT_FLIST SUBSTRUCT [0] 1 PIN_FLD_POID POID [0] 0.0.0.1 /data/sequence 307 1278 1 PIN_FLD_HEADER_NUM INT [0] 156 0 PIN_FLD_EXTENDED_INFO SUBSTRUCT [0] 0 PIN_FLD_THREAD_INFO ARRAY [3] 1 PIN_FLD_START_T TSTAMP [0] (1070784000) Sun Dec 7 00:00:00 2003
MTA Callback and Helper Functions
The MTA callback and helper functions are listed here, in alphabetical order.
The MTA helper functions can be used to manipulate data in global flist data structures.
Important:
Multithread-safe helper functions can be used with all MTA callback functions. Multithread-unsafe functions cannot be used with pin_mta_worker thread functions.pin_mta_config
This function processes command-line arguments.
This function is called at application configuration for processing application-specific command-line arguments, configuration settings in the application's pin.conf file, or storable objects. It also sets the usage flag when there is an error during configuration, to halt application execution and display a help message.
void
pin_mta_config(
pin_flist_t *param_flistp,
pin_flist_t *app_flistp,
pin_errbuf_t *ebufp);
- param_flistp
-
A pointer to the flist containing information about the command-line parameters. Information from param_flistp is used to populate the PIN_FLD_APPLICATION_INFO substruct in the application's global flist.
Tip:
Removing elements from param_flistp as they are processed may help to recognize unexpected command-line options and to set the usage flag, if necessary. - app_flistp
-
A pointer to the flist containing application information received from the global flist substruct PIN_FLD_APPLICATION_INFO.
- ebufp
-
A pointer to the error buffer.
pin_mta_exit
This function shuts down the application.
This function is called when the application is about to exit. It is a hook for implementing functions that are required (such as validation) and logging.
pin_mta_get_decimal_from_pinconf
This function loads decimal fields from the pin.conf file and sets them to the PIN_FLD_APPLICATION_INFO substruct in the global flist.
Important:
This function is not multithread safe and can be used only in pin_mta_config.
void
pin_mta_get_decimal_from_pinconf(
pin_flist_t *app_info_flistp,
char *pinconf_name,
int32 field,
int32 optional,
pin_errbuf_t *ebufp);
- app_info_flistp
-
A pointer to the PIN_FLD_APPLICATION_INFO substruct in the global flist.
- pinconf_name
-
A pointer to the pin.conf file.
- field
-
The name of the field in the pin.conf file.
- optional
-
Specifies whether the field is optional or mandatory. If it is mandatory and does not exist in the pin.conf file, the error buffer is set.
- ebufp
-
A pointer to the error buffer.
pin_mta_get_int_from_pinconf
This function loads integer fields from the pin.conf file and sets them to the value in the PIN_FLD_APPLICATION_INFO substruct in the global flist.
Important:
This function is multithread unsafe and cannot be used with pin_mta_worker thread functions.
void
pin_mta_get_int_from_pinconf(
pin_flist_t *app_info_flistp,
char *pinconf_name,
int32 field,
int32 flag,
int32 optional,
pin_errbuf_t *ebufp);
- app_info_flistp
-
A pointer to the PIN_FLD_APPLICATION_INFO substruct in the global flist.
- pinconf_name
-
A pointer to the pin.conf file.
- field
-
The name of the field in the pin.conf file.
- flag
-
The PIN_FLD_FLAGS value in the PIN_FLD_APPLICATION_INFO substruct is set to this value. For a list of predefined MTA flags, see pin_mta.h.
- optional
-
Specifies whether the field is optional or mandatory. If it is mandatory and does not exist in the pin.conf file, the error buffer is set.
- ebufp
-
A pointer to the error buffer.
pin_mta_get_str_from_pinconf
This function loads string fields from the pin.conf file and sets them to the PIN_FLD_APPLICATION_INFO substruct in the global flist.
Important:
This function is multithread unsafe and cannot be used with pin_mta_worker thread functions.
void
pin_mta_get_str_from_pinconf(
pin_flist_t *app_info_flistp,
char *pinconf_name,
int32 field,
int32 optional,
pin_errbuf_t *ebufp);
- app_info_flistp
-
A pointer to the PIN_FLD_APPLICATION_INFO substruct in the global flist.
- pinconf_name
-
A pointer to the pin.conf file.
- field
-
The name of the field in the pin.conf file.
- optional
-
Specifies whether the field is optional or mandatory. If it is mandatory and does not exist in the pin.conf file, the error buffer is set.
- ebufp
-
A pointer to the error buffer.
pin_mta_global_flist_node_get_no_lock
This function gets the global flist field and does not lock the field.
Important:
This function is multithread unsafe and cannot be used with pin_mta_worker thread functions.
pin_flist_t*
pin_mta_global_flist_node_get_no_lock(
pin_fld_num_t field,
pin_errbuf_t *ebufp);
pin_mta_global_flist_node_get_with_lock
This function gets the global flist field and sets the lock to prevent access to the field. Used together with pin_mta_global_flist_node_release.
pin_flist_t*
pin_mta_global_flist_node_get_with_lock(
pin_fld_num_t field,
pin_errbuf_t *ebufp);
pin_mta_global_flist_node_put
This function puts the global flist field with the specified flist.
void
pin_mta_global_flist_node_put(
pin_flist_t *in_flistp,
pin_fld_num_t field,
pin_errbuf_t *ebufp);
pin_mta_global_flist_node_release
This function releases the lock from the global flist field. Used together with pin_mta_global_flist_node_get_with_lock.
Important:
Do not use this function to release locks unless the locks were set using pin_mta_global_flist_node_get_with_lock.pin_mta_global_flist_node_set
This function sets the global flist field with the specified flist.
void
pin_mta_global_flist_node_set(
pin_flist_t *in_flistp,
pin_fld_num_t field,
pin_errbuf_t *ebufp);
pin_mta_init_app
This function, called at application initialization, is a hook to implementing functionality that is required before the main search execution.
pin_mta_init_search
This function prepares the search flist.
This function is called at search initialization. It prepares the search flist that is passed as the input flist to the search opcodes. The search flist is prepared according to the search opcode input flist specification. This function can also be used to update the search flist for subsequent searches.
Important:
The select query should be designed to fetch a new set of records each time it is executed, otherwise pin_mta_search will return the same records each time, causing your MTA application to hang.One way to accomplish this is to update the objects in the database during processing by the worker threads so that these objects are not returned by the select query when it is executed again. For example, suppose a billing application uses the following select query to process accounts that have not been billed:
select bill_obj_id0 from account_t where actg_next_t <= current_time
The application updates the account by setting actg_next_t to the next cycle after the account is processed. When pin_mta_search is executed again, the select query returns a new set of accounts that have not been billed. Accounts that have already been processed do not meet the search criteria, therefore they are not returned in the result set.
Another way to ensure that new records are fetched each time would be to use order by in your select query so that the returned results are ordered. For example:
select bill_obj_id0 from account_t where actg_next_t <= current_time order by poid_id0
When you execute the query again, start from the previous search maximum poid_id. For example:
select bill_obj_id0 from account_t where actg_next_t <= current_time and poid_id > previous_maximum_poid_id order by poid_id0
This method does not require a database update as does the previous example; however, depending on the number of records being ordered, there might be a performance impact.
void
pin_mta_init_search(
pin_flist_t *app_flistp,
pin_flist_t **search_flistpp,
pin_errbuf_t *ebufp);
- app_flistp
-
A pointer to the flist containing application information from the global flist substruct PIN_FLD_APPLICATION_INFO.
- search_flistpp
-
A pointer to a pointer to a search flist.
Note:
The search flist allocated in this function is set to the PIN_FLD_SEARCH_FLIST substruct in the global flist. - ebufp
-
A pointer to the error buffer.
pin_mta_job_done
This function performs functions required at application job completion.
This function is called after all worker threads have finished processing the jobs assigned to them. It is a hook for implementing functionality that is required, such as validation and logging.
pin_mta_main_thread_pcm_context_get
This function gets the main thread context. This context can be reused by the main thread callback functions only.
Important:
This function is multithread unsafe and cannot be used with pin_mta_worker thread functions.pin_mta_post_config
This function performs post-configuration functions.
This function is called after application configuration. It is a hook to implement custom functions that are required after configuration, such as validation, providing results from the configuration policy opcode hook, and logging.
void
pin_mta_post_config(
pin_flist_t *param_flistp,
pin_flist_t *app_flistp,
pin_errbuf_t *ebufp);
pin_mta_post_exit
This function performs functions required before the application shuts down.
This is the last function called when the application is about to exit. It is a hook for implementing functions that are required, such as validation of results from the application exit policy opcode hook and logging.
pin_mta_post_init_app
This function performs post-application initialization functions.
This function is a hook for implementing functionality that is required after initialization, such as validation of results from the initialization policy opcode hook and logging.
pin_mta_post_init_search
This function performs post-search flist preparation functions.
This function is a hook for implementing functionality that is required after the search flist is prepared, such as validation of results from the search initialization policy opcode hook and logging.
void
pin_mta_post_init_search(
pin_flist_t *app_flistp,
pin_flist_t *search_flistp,
pin_errbuf_t *ebufp);
pin_mta_post_job_done
This function performs post-application job-completion functions.
This function is called after all worker threads have finished processing the jobs assigned to them. It is a hook for implementing functionality that is required, such as validation of results from the application job-completion policy opcode hook and logging.
pin_mta_post_tune
This function performs post-search functions for preprocessing search results.
This function is a hook for implementing functions that are required after the search results have been preprocessed, such as validation of the results from search results tuning policy opcode hook and logging.
void
pin_mta_post_tune(
pin_flist_t *app_flistp,
pin_flist_t *srch_res_flistp,
pin_errbuf_t *ebufp);
- app_flistp
-
A pointer to the flist containing application information received from the global flist substruct PIN_FLD_APPLICATION_INFO.
- srch_res_flistp
-
A pointer to the flist containing the search results flist received from the global flist substruct PIN_FLD_SEARCH_RESULTS.
- ebufp
-
A pointer to the error buffer.
pin_mta_post_usage
This function displays the help text prepared by pin_mta_usage and the usage policy opcode hook.
void
pin_mta_post_usage(
pin_flist_t *param_flistp,
pin_flist_t *app_flistp,
pin_errbuf_t *ebufp);
pin_mta_post_worker_exit
This function exits all worker threads.
This function is called when the application is about to exit and all worker threads must exit. This function is a hook for implementing functions that are required, such as logging.
void
pin_mta_post_worker_exit(
pcm_context_t *ctxp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
pin_mta_post_worker_init
This function performs post-worker thread initialization functions.
This function is called for each thread at thread startup. It is a hook for implementing functions that are required after worker thread initialization, such as validation of results from the worker thread initialization policy opcode hook and logging.
void
pin_mta_post_worker_init(
pcm_context_t *ctxp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
pin_mta_post_worker_job
This function performs post-worker thread job preparation functions.
This function is a hook for implementing functions that are required, such as validation of results from the worker thread policy opcode hook and logging.
void
pin_mta_post_worker_job(
pcm_context_t *ctxp,
pin_flist_t *srch_res_flistp,
pin_flist_t *op_in_flistp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
- ctxp
-
A pointer to the PCM context.
- srch_res_flistp
-
A pointer to the flist containing a subset of the global search results assigned to a worker thread.
- op_in_flistp
-
A pointer to the flist containing the main opcode input flist.
- ti_flistp
-
A pointer to the flist containing thread information.
- ebufp
-
A pointer to the error buffer.
pin_mta_post_worker_job_done
This function performs post-worker job completion functions.
This function is a hook for implementing functions that are required, such as validation or processing of results from the worker thread policy opcode hook.
void
pin_mta_post_worker_job_done(
pcm_context_t *ctxp,
pin_flist_t *srch_res_flistp,
pin_flist_t *op_in_flistp,
pin_flist_t *op_out_flistp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
- ctxp
-
A pointer to the PCM context.
- srch_res_flistp
-
A pointer to the flist containing a subset of the global search results assigned to a worker thread.
- op_in_flistp
-
A pointer to the flist containing the main opcode input flist.
- op_out_flistp
-
A pointer to the flist containing the main opcode output flist.
- ti_flistp
-
A pointer to the flist containing thread information.
- ebufp
-
A pointer to the error buffer.
pin_mta_tune
This function preprocesses search results.
This function is called after the main search execution for preprocessing the search results. The search results can be modified before the results are distributed to the worker threads.
void
pin_mta_tune(
pin_flist_t *app_flistp,
pin_flist_t *srch_res_flistp,
pin_errbuf_t *ebufp);
- app_flistp
-
A pointer to the flist containing application information received from the global flist substruct PIN_FLD_APPLICATION_INFO.
- srch_res_flistp
-
A pointer to the flist containing the search results flist received from the global flist substruct PIN_FLD_SEARCH_RESULTS.
- ebufp
-
A pointer to the error buffer.
pin_mta_usage
This function creates a help text message.
This function is called when the user requests help using the -help parameter or when an error occurs during application configuration. This function is a hook to prepare help text messages.
Important:
You must set the PIN_FLD_DESCR field in PIN_FLD_EXTENDED_INFO substruct in the global flist to the help text so that it can be accessed by the usage policy opcode for customization and by pin_mta_post_usage for displaying the message.pin_mta_worker_exit
This function exits all worker threads.
This function is called when the application is about to exit and all worker threads must exit. This function is a hook for implementing functions that are required, such as logging.
pin_mta_worker_init
This function performs thread initialization.
This function is called for each worker thread at thread startup. It is a hook for implementing functions that are required at worker thread initialization.
pin_mta_worker_job
This function performs functions required at worker thread job preparation.
This function is called every time a worker thread receives work for any preprocessing of the search results before the results are passed to the main opcode to be processed.
Tip:
This function provides the same functionality as pin_mta_tune. Because of parallel processing, preprocessing search results in the worker threads is more efficient when BRM is installed on a multiple-CPU host machine.
void
pin_mta_worker_job(
pcm_context_t *ctxp,
pin_flist_t *srch_res_flistp,
pin_flist_t **op_in_flistpp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
- ctxp
-
A pointer to the PCM context.
- srch_res_flistp
-
A pointer to the flist containing a subset of the global search results assigned to a worker thread.
- op_in_flistpp
-
A pointer to a pointer to the main opcode input flist.
- ti_flistp
-
A pointer to the flist containing thread information.
- ebufp
-
A pointer to the error buffer.
pin_mta_worker_job_done
This function performs functions that are required after the main opcode has processed the batch of search results.
This function is a hook to implementing functions that are required, such as the validation of main opcode results.
void
pin_mta_worker_job_done(
pcm_context_t *ctxp,
pin_flist_t *srch_res_flistp,
pin_flist_t *op_in_flistp,
pin_flist_t *op_out_flistp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
- ctxp
-
A pointer to the PCM context.
- srch_res_flistp
-
A pointer to the flist containing a subset of the global search results assigned to a worker thread.
- op_in_flistp
-
A pointer to the flist containing the main opcode input flist.
- op_out_flistp
-
A pointer to the flist containing the main opcode output flist.
- ti_flistp
-
A pointer to the flist containing thread information.
- ebufp
-
A pointer to the error buffer.
pin_mta_worker_opcode
This function executes the main opcode.
This function is called by the worker threads to execute the main opcode to process the search results. Worker threads call this function for every batch of work they receive.
void
pin_mta_worker_opcode(
pcm_context_t *ctxp,
pin_flist_t *srch_res_flistp,
pin_flist_t *op_in_flistp,
pin_flist_t **op_out_flistpp,
pin_flist_t *ti_flistp,
pin_errbuf_t *ebufp);
- ctxp
-
A pointer to the PCM context.
- srch_res_flistp
-
A pointer to the flist containing a subset of the global search results assigned to a worker thread.
- op_in_flistp
-
A pointer to the flist containing the main opcode input flist.
- op_out_flistpp
-
A pointer to a pointer to the flist containing the main opcode output flist.
- ti_flistp
-
A pointer to the flist containing thread information.
- ebufp
-
A pointer to the error buffer.