cwbCO_GetNextSysName

Purpose

Get the name of the next system from a list of systems.

Syntax

 
unsigned int CWB_ENTRY cwbCO_GetNextSysName(
                             cwbCO_SysListHandle listHandle,
                             char               *systemName,
                             unsigned long       bufferSize,
                             unsigned long      *needed);

Parameters

cwbCO_SysListHandle handleList - input

Handle to a list of systems.

char *systemName - output

Pointer to a buffer that will contain the system name. This buffer should be large enough to hold at least CWBCO_MAX_SYS_NAME + 1 characters, including the terminating NULL character.

unsigned long bufferSize - input

Size of the buffer pointed to by systemName.

unsigned long *needed - output

Number of bytes needed to hold entire system name.

Return Codes

The following list shows common return values.

CWB_OK

Successful Completion.

CWB_INVALID_API_HANDLE

Invalid system handle.

CWB_INVALID_POINTER

Pointer to system name or pointer to buffer size needed is NULL. Check messages in the History Log to determine which are NULL.

CWB_BUFFER_OVERFLOW

Not enough room in output buffer to hold entire system name. Use *needed to determine the correct size. No error message is logged to the History Log since the caller is expected to recover from this error and continue.

CWBCO_END_OF_LIST

The end of the system list has been reached. No system name was returned.

CWB_NOT_ENOUGH_MEMORY

Insufficient memory; may have failed to allocate temporary buffer.

CWB_API_ERROR

General API failure.

Usage

If the system list passed in was created using the API cwbCO_CreateSystemListHandle, then the system returned is configured in the currently active environment, unless between these API calls the user has removed it or switched to a different environment. If cwbCO_CreateSysListHandleEnv was called to create the system list, then the system returned is configured in the environment passed to that API, unless the user has since removed it.