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.