Timeout conditions

Note pad requests and connection requests have the potential to be long running. Depending on the request and the state of the system, it might take several seconds, perhaps minutes for a request to complete. These requests are processed asynchronously under a task in the XCF address space. The work unit that issues the request is suspended while XCF processes the request.

As it processes the request, XCF might need to establish a XES connection (using the IXLCONN macro) from the local system to one or more coupling facility structures. I/O accesses to the Coupling Facility Resource Manager (CFRM) Couple Data Set (CDS) might be needed. The performance of these I/O accesses to the CDS can be impacted by a number of factors, including size of the CDS and contention. In some cases, portions of the request could be processed by other systems in the sysplex, who in turn might need to establish their own XES connections to the relevant structures. All of this processing is transparent to your program, except possibly for the elapsed time.

When issuing the IXCNOTE macro to process a note pad request or a connection request, your program can specify the TIMEOUT keyword to limit the amount of time that your work unit remains suspended waiting for the request to complete. Given that these requests can be long running, you should in general provide generous timeout values. The default timeout values used by XCF can vary with the installed level of the XCF Note Pad Services. Typically the default XCF timeout values are on the order of several minutes.

If the timeout value is too low, your work unit might be resumed before the results of the request are known. If XCF determines that the request was either not processed, or that it can be safely reissued, the return and reason code will indicate that the request timed out. Otherwise the return and reason code will likely indicate that the result of the request is unknown (see Status unknown conditions). For the timeout case, consider reissuing the request, possibly with a longer time out value.

Note the following for note pad requests:

Create note pad and delete note pad are not considered by XCF to be requests that can be safely reissued. If these requests were to be reissued after a timeout, a reissued create request might be rejected because the note pad was in fact created by the original request. Similarly, a reissued delete note pad request might be rejected because the note pad was in fact deleted by the original request. Under the assumption that your program would treat these rejections as unexpected errors, XCF returns a status unknown condition instead of a timeout condition.
Query note pad is considered by XCF to be a request that can be safely reissued.

Note the following for connection requests:

Create connection requests can be safely reissued if they time out. Either the connection was not created at all, or XCF backed it out. The connection does not exist.
In general, pause connection requests are issued to either wait for a quiescing condition to be resolved, or to wait for the pending delete of a connection to finish. Pause connection requests are by their very nature long running since they are intended to wait for these conditions to clear, potentially for as long as the specified timeout value.
Resume connection requests are not considered by XCF to be requests that can be safely reissued. There are cases where the resume request times out even though the paused connection is in fact successfully resumed. A reissued resume request could then complete with a return and reason code indicating that the resume is pending. Under the assumption that some program might not expect this result, XCF returns a status unknown condition instead of a timeout condition.
Delete connection requests are not considered by XCF to be requests that can be safely reissued. If this request were to be reissued after a timeout, the reissued delete connection request might be rejected because the connection was in fact deleted by the original request. Under the assumption that your program would treat this rejection as unexpected error, XCF returns a status unknown condition instead of a timeout condition.
Note that the time needed to delete a connection could be impacted by the total number of notes in the note pad, the number of notes associated with the connection, and the number of nonpersistent notes that need to be deleted on behalf of the connection.