cwbCO_CreateSystemLike

Purpose

Create a new system object that is similar to a given system object. You may either provide a specific system name for the new system object, or specify NULL to use the given system object's name. All attributes of the given system object are copied into the new one, with the following exceptions:

Syntax

 
UINT CWB_ENTRY cwbCO_CreateSystemLike(
                             cwbCO_SysHandle     systemToCopy,
                             LPCSTR              systemName
                             cwbCO_SysHandle    *system);

Parameters

cwbCO_SysHandle systemToCopy - input
Handle that was returned by a previous call to either cwbCO_CreateSystem or cwbCO_CreateSystemLike. It identifies the iSeries™ system. This is the object that will be "copied."
LPCSTR systemName - input
Pointer to a buffer that contains the NULL-terminated name of the iSeries system to use in the new system object. If NULL or the empty string is passed, the name from the given system object is copied into the new system object. If a system name is specified, it can be the host name, or the iSeries system's dotted-decimal IP address. If the name that is specified is not a valid iSeries system host name or IP address string (in the form "nnn.nnn.nnn.nnn"), any connection attempt or security validation attempt will fail.
cwbCO_SysHandle *newSystem - output
The system object handle of the new system object is returned in this parameter.

Return Codes

The following list shows common return values.

CWB_OK
Successful completion.
CWB_INVALID_POINTER
A pointer that is supplied to the API is not valid.
CWB_INVALID_SYSNAME
The system name is not valid.
CWB_RESTRICTED_BY_POLICY
A policy exists that prohibits the user from creating a system object for a system not already defined in the System List.
CWB_NON_REPRESENTABLE_UNICODE_CHAR
One or more input Unicode characters have no representation in the codepage that is being used.

Usage

When you are done using the new system object, you must call cwbCO_DeleteSystem to free resources that the system object is using.

The state of the new system object might not be the same as that of the given system object, since user ID and password validation has not been performed yet for the new one. Also, the new system object has no connections associated with it, whereas the given system object may. Because of this, even though you might not be able to change attributes of the given system object because of its state, you might be able to change the attributes of the new system object because of its possibly different state.