RCCGetRecords - Get the real-time trace records

Use this request to obtain the trace records that matched the filters that were set by the RCCSetFilters request. The real-time data are stored in the form of cte trace records in the staging buffer that is shared between the application trace instance and the TCP/IP stack. The staging buffer is created during processing of the RCCOpen request. See Format of trace records for more information about the format of the trace records.

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

Guideline: If the trace collection has been started, your network management application should immediately invoke the RCCGetRecords request to start obtaining the trace records. A delay in invoking the RCCGetRecords request might result in lost trace records.

The trace records can be accessed in two modes:

Locate mode
Locate mode enables your application to access the trace records directly in the staging buffer. To use locate mode, indicate it on the RCCOpen request when you open a trace instance. If you are using locate mode, the RCCGetRecords request returns the starting address and length of the trace records in the staging buffer. On each subsequent invocation, the RCCGetRecords request frees the storage occupied by the trace records previously returned.
Rule: If you are using locate mode, your application must be executing in AMODE64 so that your application can process the records directly from the staging buffer.
Move mode
If you did not indicate to use locate mode on the RCCOpen request, the RCCGetRecords uses move mode. If you are using move mode, the RCCGetRecords request copies the trace records from the staging buffer to the output buffer that is specified in the RCCGetRecords input structure. After the records are copied to the output buffer, the staging buffer storage that the records used is freed for new trace records.

The input RCCGet structure must follow the RCCHeader structure in the input RequestResponseBuffer. You must set the following fields in the input RCCGet structure before invoking a request:

RCGREye
RCGRVer
RCGRLen
RCGRBufAlet - Required for move mode only.
RCGRBufLen - Required for move mode only.
RCGRBufAddr - Required for move mode only.

Waiting for trace records using RCGRWaitTime

If there are no records currently available, use the RCGRWaitTime field to specify whether the request should wait or just return. If you specify a wait value in milliseconds for the RCGRWaitTime field, but no trace records are available, the RCCGetRecords request waits until either a trace record is available or the wait time expires. If the millisecond interval expires and there are still no trace records available, the request returns to the application with a successful return value. Although you can specify the number of milliseconds, internal TCP/IP timers that are used to implement this function have a granularity of approximately 100 milliseconds. You can use the value in the RCGRBufUsed field to determine whether any trace records were returned in your buffer (for move mode) or any trace records are ready to be processed (for locate mode).

Waiting for trace records using an ECB

You can also specify that the NMI should post an ECB when trace records are available. The ECB address is specified as input to the RCCOpen request and belongs to your application.

Guidelines:

Your application must initially set the ECB to 0 before the application invokes the RCCStart request. After the trace starts, the application needs to reset the ECB to 0 after the application waits on the ECB and the ECB is posted.
Use the RCCGetRecords request to obtain all available trace records before you wait on the ECB for the first time.
You might want to wait on the ECB and a timeout value. If the traffic that you are tracing stops, the ECB is not posted.