Real-time control NMI: Overview
- RCCOpen
This request creates a trace instance and returns a token to the application. The token represents this trace instance. The request verifies the application access to the security product resource profile for the request. This request also creates a 64-bit shared storage area for the NMI to use as a staging buffer on behalf of the application.
Before invoking the RCCOpen request, you must decide how you want to access the trace records. The trace records can be accessed in two modes:- Locate mode
If you use locate mode, you can access the trace records directly in the staging buffer. Because the staging buffer is comprised of 64-bit storage, your application must be running in AMODE64 to access the records.
- Move mode
If you use move mode, the trace records are copied to an output buffer that you provide when you invoke the RCCGetRecords request.
Rule: If you decide to use locate mode, you must indicate this in the input to the RCCOpen request and this setting cannot be modified later. The setting can be changed only by closing and reopening the trace instance.You must also decide whether you want to use an ECB to wait for trace records to become available. If you don’t use an ECB, you can use the RCCGetRecords request in one of the following ways:- You can specify a wait time value on the RCCGetRecords request.
- Your application can invoke the RCCGetRecords request until trace records are available.
Rules:- If you decide to use an ECB in conjunction with obtaining trace records, the ECB address must be specified in the input to the RCCOpen request and this setting cannot be modified later. The setting can be changed only by closing and reopening the trace instance.
- The specified ECB is posted only when the trace is active and the records are being written to the trace instance staging buffer. If the trace is stopped, the ECB is not posted.
- Locate mode
- RCCSetFilters
This request sets the trace types for which the application wants to collect real-time data and sets trace filters and options for each trace type. Currently the only trace types that are supported are packet trace and data trace. The request verifies that the application has access to the security product resource profiles for the trace types that are specified in the request.
- RCCStart
This request causes TCP/IP to start collecting real-time data for the application based on the filters and options for the trace instance.
- RCCGetRecords
This request enables the application to obtain the requested real-time data. If locate mode was requested as input to the RCCOpen request, the starting address and length of the real-time data in the staging buffer are returned to the application. If move mode is in effect, the real-time data is copied to an application-supplied buffer.
- RCCStop
This request causes TCP/IP to stop collecting real-time data for the application.
- RCCClose
This request closes the trace instance that is specified by the input token. The staging buffer is also freed for the trace instance.
- All of the NMI requests after RCCOpen, except for the RCCGetRecords request, must be invoked from the same address space and task as that of the invoker of the RCCOpen request; otherwise, the NMI request fails. Applications cannot invoke these subsequent requests from a forked process. These subsequent requests must be invoked under the same user ID as that of the invoker of the RCCOpen request.
- The RCCGetRecords request can be invoked from any task in the same address space as the invoker of the RCCOpen request, but must be invoked under the same user ID as that of the invoker of the RCCOpen request. The RCCGetRecords request cannot be invoked concurrently from more than one task.
See Real-time control NMI: Requests for detailed information about invoking each NMI request.