Real-time control NMI: Overview

The real-time data is stored in the form of trace records in the staging buffer that is shared between the application trace instance and the TCP/IP stack. To obtain the trace records, a network management application invokes the NMI requests in the following order:

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.
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.

Rules:

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.

Application abend exit

After the RCCOpen request is successfully processed, your application is associated with a specific TCP/IP stack. If this TCP/IP stack is stopped, your application task might be terminated with an ABEND422. You can provide an abend exit for this abend.

Disablement of the NMI

If certain error conditions occur, the NMI is disabled. Message EZD2014I is issued to the console indicating the cause of the disablement. The DISPLAY TCPIP,,TRACE command output also indicates that the NMI is disabled. If your application receives a return code of ETCPERR and a reason code of JrDisabled, this indicates that the NMI is disabled. If your application has an open trace instance, the application should invoke the RCCClose request to close the trace instance. The TCP/IP stack must be recycled to reset the disabled condition.