KcsLoadProfile() (KCMS Application Developer's Guide)

KCMS Application Developer's Guide

`KcsLoadProfile()`

KcsStatusId
 KcsLoadProfile(KcsProfileId *profile,
 		KcsProfileDesc *desc, KcsLoadHints loadHints)

Purpose

Use KcsLoadProfile() to load a profile and all of its resources into the system.

The function uses desc to determine where to get the data to generate the profile's resources in the system. (See "KcsProfileDesc" for an in-depth description of KcsProfileDesc.) It uses profile to return a reference to the loaded profile. This reference is needed by other API functions.

Your application can determine the length of the data read from the file by calling KcsGetAttribute() and supplying the icHeader attribute. The value of size in the icHeader structure is the size of the profile. (For the format of the icHeader structure, see "icHeader ".)

With the loadHints argument, 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:

The load hints are merely hints, which means the KCMS framework can ignore them. However, because the functionality 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 releases.
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.

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 KcsLoadProfile(), the current position is undefined. The application must reset the pointer before doing any other I/O.

After your application is finished with the profile, it should call KcsFreeProfile() to release the resources allocated by the profile.

Arguments

Table 4-15 KcsLoadProfile() Arguments


Argument	Description
`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()`.
`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 static storage mechanisms. The `KcsProfileDesc` structure (see "`KcsProfileDesc`") has a field that identifies which storage mechanism to use.
`loadHints`	The set of bits describing what, how, when, and where to load and unload profile. See "`KcsLoadHints` " for information on the KcsLoadHints data type. Also see "Operation Hint Constants" for constraints on the operations your application can specify to this function.

Returns

Table 4-16 KcsConnectProfiles() Return Strings


`KCS_SUCCESS`
`KCS_MEM_ALLOC_ERROR`
`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_X11_PROFILE_RO`

Example

Example 4-7 `KcsLoadProfile()`

    KcsFileId		scannerFd, monitorFd, completeFd;
     KcsProfileDesc	scannerDesc, monitorDesc, completeDesc;
     KcsProfileId 	scannerProfile, monitorProfile;
     KcsProfileId	profileSequence[2], completeProfile;
     KcsStatusId		status;
     KcsAttributeValue	attrValue;
     KcsAttributeName	i;
     KcsOperationType	op = (KcsOpForward+KcsContImage);
     u_long		failedProfileNum;
     extern void		kcs_timer(int);

     if (argc > 4) {
 	fprintf(stderr,"Usage : kcstest profile_1 profile_2 [save_profile]\n");
 	exit(1);
     }

 #ifdef FILE_DESC
     /* Open up the files from disk */
     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;
 #endif

 #ifdef FILE_NAME
     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;
 #endif

     /* Load the profiles */
     printf("Load scanner profile\n");
     kcs_timer(START);
     status = KcsLoadProfile(&scannerProfile, &scannerDesc, KcsLoadAllNow);
     kcs_timer(STOP);
     if (status != KCS_SUCCESS) {
 	fprintf(stderr,"Scanner KcsLoadProfile failed error = 0x%x\n", status);
 #ifdef FILE_DESC
 	close(scannerFd);
 	close(monitorFd);
 #endif
 	exit(1);
     }

     printf("Load monitor profile\n");
     kcs_timer(START);
     status = KcsLoadProfile(&monitorProfile, &monitorDesc, KcsLoadAllNow);
     kcs_timer(STOP);
     if (status != KCS_SUCCESS) {
 	fprintf(stderr,"MonitoKcsLoadProfile failed error = 0x%x\n", status);
 #ifdef FILE_DESC
 	close(scannerFd);
 	close(monitorFd);
 #endif
 	exit(1);
     }