.\" pragma ident "@(#)KcsConnectProfiles.3	1.4  04/21/95"
.TH KcsConnectProfiles 3 "21 April 1995" "" "KCMS Library"
.SH NAME
KcsConnectProfiles \- Connect a sequence of profiles together
.SH SYNOPSIS
.ft B
.nf
#include <kcms/kcs.h>
#include <kcms/kcstypes.h>
.fi
.sp
.br
.ft B
.nf
KcsStatusId KcsConnectProfiles(
		KcsProfileId		*resultProfileId, 
		unsigned long		profileCount, 
		KcsProfileId		*profileSequence, 
		KcsOperationType	operationLoadSet,
		unsigned long		*failedProfileIndex)
.fi
.ft R
.SH MT-LEVEL
MT-Unsafe
.SH DESCRIPTION
.B KcsConnectProfiles()
is used to combine several existing 
profiles into a new profile or to restrict the functionality of a 
single existing profile to make it more efficient. This function 
cannot create a new profile 
.I from scratch.
.LP
If the call succeeds, 
.B KcsConnectProfiles()
generates a new 
profile from the sequence of existing profile(s). The reference to 
this new profile is stored in the resultProfileId argument. 
Once you have this reference, you can free the resources used by 
the input profiles of profileSequence if they are no longer 
required by the application. (Use 
.B KcsFreeProfile(3)
to release resources.)
.SH ARGUMENTS
.TP
.SB resultProfileId 
The reference to the resultant profile, returned if the function 
executes successfully.
.TP
.SB profileCount
The number of profiles to be connected.
.TP
.SB profileSequence
An array of the identifiers of the profiles to be connected.
.TP
.SB operationLoadSet
One or more flags symbolizing the kind of information in the 
resultant profile. It also describes what/how/when/where to 
load/unload the resulting resultProfileId.
.TP
.SB failedProfileIndex
.B KcsConnectProfiles()
returns an integer into failedProfileIndex. This value has meaning only when 
.B KcsConnectProfiles()
returns a status value other than 
KCS_SUCCESS. If the function fails, this index helps the 
application to identify which input profile caused the failure. If 
the index contains 0, the first profile in profileSequence had 
problems. If it contains 1, the second profile in 
profileSequence had problems, and so on. Often the 
problem in making the resultant profile is that the profiles 
specified in profileSequence could not be connected. In this 
case, the index returns an integer symbolizing the latter profile in 
a failed connection pair. For example, if the first profile and 
second profile in the sequence were mismatched, the index 
would contain 1 (for the second profile).
.SH RETURN VALUES
Upon successful completion KCS_SUCCESS is returned. Otherwise
one of the following errors will be returned.
.SH ERRORS
.nf
KCS_PROF_ID_BAD
KCS_MEM_ALLOC_ERROR
KCS_CONNECT_PRECISION_UNACCEPTABLE
KCS_MISMATCHED_COLORSPACES
KCS_CONNECT_OPT_FORCED_DATA_LOSS
.fi
.SH SEE ALSO
.BR KcsFreeProfile (3)
.BR KcsLoadProfile (3)
.BR KcsOptimizeProfile (3)
.BR KcsSaveProfile (3)
.br
.BR "KCMS Application Developers Guide"
.SH NOTE
If you have minimized a profile's load operation/state with 
KcsOptimizeProfile(3), only that particular load operation/state is saved with 
KcsSaveProfile(3). Therefore, operations not included in the profile will 
not be available the next time the profile is loaded.
.SH EXAMPLE
.nf
KcsProfileDesc		scannerDesc, monitorDesc, completeDesc;
KcsProfileId		scannerProfile, monitorProfile;
KcsProfileId		profileSequence[2], completeProfile;
KcsStatusId		status;
KcsErrDesc 		errDesc;
u_long			failedProfileNum;

/* file names input as program arguments */
scannerDesc.type = KcsSolarisProfile;
scannerDesc.desc.solarisFile.fileName = argv[1];
scannerDesc.desc.solarisFile.hostName = NULL;
scannerDesc.desc.solarisFile.oflag = O_RDONLY;
scannerDesc.desc.solarisFile.mode = 0;

monitorDesc.type = KcsSolarisProfile;
monitorDesc.desc.solarisFile.fileName = argv[2];
monitorDesc.desc.solarisFile.hostName = NULL;
monitorDesc.desc.solarisFile.oflag = O_RDONLY;
monitorDesc.desc.solarisFile.mode = 0;

status = KcsLoadProfile(&scannerProfile, &scannerDesc, KcsLoadAllNow);
if(status != KCS_SUCCESS) {
	KcsGetLastError(&errDesc); 
	printf("Scanner LoadProfile error: %s\\n", errDesc.desc);
	exit(1);
}

status = KcsLoadProfile(&monitorProfile, &monitorDesc, KcsLoadAllNow);
if(status != KCS_SUCCESS) {
	KcsGetLastError(&errDesc); 
	printf("Monitor LoadProfile error: %s\\n", errDesc.desc);
	exit(1);
}

/* See if we can combine them */
profileSequence[0] = scannerProfile;
profileSequence[1] = monitorProfile;
status = KcsConnectProfiles(&completeProfile, 2, profileSequence, op,
		&failedProfileNum);
if(status != KCS_SUCCESS) {
	KcsGetLastError(&errDesc); 
	printf("ConnectProfile error: %s\\n", errDesc.desc);
	fprintf(stderr, "Failed in profile number %d\\n", failedProfileNum);
	exit(1);
}
.fi