CICS_EpiListSystems
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 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 must 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 must provide
the storage for the array and must set the Systems parameter
to indicate the number of elements in the array.
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.