.\" pragma ident "@(#)KcsLoadProfile.3	1.3  04/21/95"
.TH KcsLoadProfile 3 "21 April 1995" "" "KCMS Library"
.SH NAME
KcsLoadProfile \- Load a profile into the system
.SH SYNOPSIS
.ft B
.nf
#include <kcms/kcs.h>
#include <kcms/kcstypes.h>
.sp
KcsStatusId KcsLoadProfile(
			KcsProfileId	*profile, 
			KcsProfileDesc	*desc, 
			KcsLoadHints	loadHints)
.fi
.SH MT-LEVEL
MT-Unsafe
.SH DESCRIPTION
Use 
.B KcsLoadProfile()
to load a profile and all of its resources into the system.
.PP
The function uses desc to determine where to get the data to 
generate the profile's resources in the system. It uses profile 
to return a reference to the loaded profile; this reference is 
needed by other API functions.
.PP
You can determine the length of the data read from the file by 
calling KcsGetAttribute(3) and supplying the 
KcsAttrProfileLength attribute.
.PP
With the loadHints argument, 
.B KcsLoadProfile()
allows the application to suggest how the KCMS framework manages the 
memory and other resources associated with a loaded profile. 
Although this is a flexible mechanism, these caveats apply:
.PP
As the name suggestions, the load hints are merely hints, and 
a the KCMS framework can ignore them if it deems necessary. 
However, because the functionalities of various CMMs loaded 
by the KCMS framework cannot always be determined, your 
application should supply the load hints anyway. 
Furthermore, even if a CMM loaded by the KCMS framework 
does not support a particular load hint in its current release, it 
may support it in future release.
.PP
If the application supplies a hint that indicates that the profile 
is to be loaded at a time other than now, it must keep the 
described mechanism open to allow for data access at a future 
and somewhat arbitrary time. For example, if the application 
specifies KcsLoadWhenNecessary and the desc argument 
describes a file, and the application uses a KcsFileId, it 
cannot close the file until it first frees the profile. This allows 
the KCMS framework to read any necessary data to load the 
profile at any time.
.PP
After you are through with the profile, call KcsFreeProfile(3)
to release the resources allocated by this profile.
.SH ARGUMENTS
.TP
.SB profile
The identifier of the profile returned after the profile is loaded 
into memory. This value serves as an argument to all other 
functions, such as KcsEvaluate(3).
.TP
.SB desc
The location of the profile's static storage, needed to obtain the 
data required to generate the profile's resources. It is specified as 
a union of independent mechanisms. The KcsProfileDesc 
structure has a field that identifies which mechanism to use.
.TP
.SB loadHints
The set of bits describing what/how/when/where to 
load/unload profile. 
.SH RETURN VALUES
Upon successful completion KCS_SUCCESS is returned. Otherwise
one of the following errors will be returned.
.SH ERRORS
.nf
KCS_MEM_ALLOC_ERROR
KCS_IO_WRITE_ERR
KCS_IO_READ_ERR
KCS_IO_SEEK_ERR
KCS_SOLARIS_FILE_NOT_OPENED
KCS_SOLARIS_FILE_RO
KCS_SOLARIS_FILE_LOCKED
KCS_SOLARIS_FILE_NAME_NULL
KCS_X11_DATA_NULL
KCS_X11_PROFILE_NOT_LOADED
KCS_PROF_ID_BAD
KCS_PROF_FORMAT_BAD
.fi
.SH NOTE
If you use the KcsFileId entry in the file part of the 
KcsProfileDesc union, KcsFileId marks the "current position" within an 
open file. After a call to 
.B KcsLoadProfile(), 
the current position is undefined. The application must reset the pointer 
before doing any other I/O.
.SH SEE ALSO
.BR KcsCreateProfile (3)
.BR KcsGetAttribute (3)
.BR KcsModifyLoadHints (3)
.BR KcsSaveProfile (3)
.br
.BR "KCMS Application Developers Guide"
.SH EXAMPLE
.in +3
.nf
KcsFileId	scannerFd, monitorFd;
KcsProfileDesc	scannerDesc, monitorDesc, completeDesc;
KcsProfileId 	scannerProfile, monitorProfile;
KcsProfileId	profileSequence[2], completeProfile;
KcsStatusId	status;
KcsErrDesc	errDesc;

/* the profile file names are provided on the command line */

/* This example requires the application to open the profile */
scannerDesc.type = KcsFileProfile;
scannerFd = open(argv[1], O_RDONLY);
if (scannerFd == -1) {
	perror("Failed to open scanner profile");
	exit(1);
}
scannerDesc.desc.file.openFileId = scannerFd;
scannerDesc.desc.file.offset = 0;

monitorDesc.type = KcsFileProfile;
monitorFd = open(argv[2], O_RDONLY);
if (monitorFd == -1) {
	perror("Failed to open monitor profile");
	exit(1);
}
monitorDesc.desc.file.openFileId = monitorFd;
monitorDesc.desc.file.offset = 0;
.fi
.sp 3
.nf
/* This example lets the KCMS library open (and close) the profiles */
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;
.fi
.sp 3
.nf
/* Loading the profiles is the same whichever "open" method is used */
status = KcsLoadProfile(&scannerProfile, &scannerDesc, KcsLoadAllNow);
if (status != KCS_SUCCESS) {
	KcsGetLastError(&errDesc); 
	printf("Scanner LoadProfile error: %s\\n", errDesc.desc);
	/*
	 * If the application opened the files, 
	 * the application must close them
	 */
	close(scannerFd);
	close(monitorFd);
	exit(1);
}

status = KcsLoadProfile(&monitorProfile, &monitorDesc, KcsLoadAllNow);
if (status != KCS_SUCCESS) {
	KcsGetLastError(&errDesc); 
	printf("Monitor LoadProfile error: %s\\n", errDesc.desc);
	/*
	 * If the application opened the files, 
	 * the application must close them
	 */
	close(scannerFd);
	close(monitorFd);
	exit(1);
}
.fi
.in -3