CICS_EpiListSystems

CICS_EpiListSystems

NameSpace
Systems
List

Purpose

The CICS_EpiListSystems function returns a list of CICS® servers that are candidates to act as servers for EPI requests. There is no guarantee that a communications link exists between the CICS Transaction Gateway and any server in the list, or that any of the servers is available to process requests.

The list is returned as an array of system information structures, one element for each CICS server. See CICS_EpiSystem_t for the contents of the structure.

EPI applications should call this function immediately after each CICS_EpiInitialize call made to determine which CICS servers are available.

Parameters

NameSpace
A pointer reserved for future use. Ensure that this is a null pointer.
Systems
A pointer to a number. On entry to the function, this number specifies the number of elements in the array specified in the List parameter. This value should accurately reflect the amount of storage that is available to the EPI to store the result. On return, it contains the actual number of servers found.

The EPI uses this parameter for both input and output.

List
An array of CICS_EpiSystem_t structures that are filled in and returned by the function. The application should provide the storage for the array and must set the Systems parameter to indicate the number of elements in the array. The first name in the list is the default server. However, the way in which the default is defined is operating system dependent.

The EPI uses this parameter only for output.

Return codes

CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_MORE_SYSTEMS
There was not enough space in the List array to store the details of all the CICS servers found. The supplied array has been filled, and the Systems parameter has been updated to contain the total number of servers found, thus allowing you to reallocate an array of suitable size and try the function again.
CICS_EPI_ERR_NO_SYSTEMS
No CICS servers can be located. In this case, the value returned in Systems is zero.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_NULL_PARM
Systems is a null pointer.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NORMAL
The function completed successfully. The number of systems found is at least one, and does not exceed the value supplied as input in the Systems parameter.