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:

User ID
Password
System name, if a different one is specified
IP address, when the system names are different.
See System object attributes list for a list of system object attributes.

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.