Setting the Scalars for a New Job Folder

After creating a Job folder, your application can set the scalars for the folder. Each type of Job folder has its own set of scalars. Note that not all scalars need to be set. For example, the Job ID scalar is automatically set by the SMS system when the Job folder is committed to the site database.

To set the scalars for the new folder, use the SmsSetScalar function to set the value of a scalar.

To set the value of a scalar, both the scalar and its folder must have an access right of ACCESS_MODIFY or ACCESS_CREATE. If you do not have ACCESS_MODIFY to the scalar, SmsSetScalar returns an SMS_SCALAR_NO_UPDATE value. If you do not have access to the folder, the SmsSetScalar returns an SMS_FOLDER_NO_UPDATE value.

To get information (such as name, data type, access rights, and so on) about all scalars within a folder, use the SmsDescribeFolder function.

The SmsSetScalar function takes two parameters:

Example

//***********************************************************
// Function to list set of available packages,
// prompt for package ID, verify the package ID
// entered by the user, and set the Package ID scalar 
// for an F_INSTALLJOB folder.
//***********************************************************


SMS_STATUS SetPackageIDScalar(HANDLE hJobFolder, // Job folder handle.
                              HANDLE hConnect)      //    Connection handle.
{
//***********************************************************
//****** Get a valid package ID.
//***********************************************************
// The package ID must be for an existing package that has
// Workstation properties set. Therefore, open a package 
// container and populate it with a Package filter set to Workstation.
// Use the package container to get the list of available packages
// and prompt the user to select one. When the package ID is input, 
// use the package container to verify the package ID.

SMS_STATUS stat;
// Open a package container.
HANDLE hPackageContainer;
stat = SmsOpenContainer( C_PACKAGE,
                         hConnect,
                         &hPackageContainer);
// Create a package filter.
HANDLE hFilter;
stat = SmsCreateFilter( PACKAGE_FILTER, // Type of filter.
                        hConnect,   // Handle to database
                                    // connection.
                        &hFilter    // Assign handle to new filter
                      );            // to hFilter.

// Add a token to the package filter that
// finds all packages with Workstation properties set.
TOKEN Token;
// Clear the Token structure.
memset( &Token, 0, sizeof (TOKEN) );
// Set the expression token to 
// "PackageType is equal to Workstation".

// Set the attribute name to PackageType.
strcpy( Token.szName, "PackageType");
// Set the operator used to evaluate the expression.
Token.dwOp = QOP_STR_EQ; // Use the equals operator.
// Set the value to evaulate.
strcpy( Token.szValue, "Workstation"); 

// Add the token to the filter.
stat = SmsAddToken( hFilter, // Specifies the handle to filter.
                    OP_AND,  // Use the AND control token to connect
                             // the expression to adjacent expressions.
                    &Token,  // Specifies the structure containing
                             // the expression token.
                    AT_END   // Add the token to the end of 
                             // the filter.
                  );

// Apply the filter to the container.
stat = SmsSetFilter ( hPackageContainer,  // Handle to container.
                      hFilter      // Handle to filter.
                    );

// Populate the container with the folders meeting the criteria set
// by the filter applied to the container. Retrieve folders
// synchronously.
stat = SmsPopulate( hPackageContainer,  // Handle to container.
                    POP_SYNC,    // Retrieve folders in 
                                 // synchronous mode.
                    NULL         // NULL for synchronous.
                  );

// Use SmsGetFolderCount to get number of folders in package container.
DWORD ctFolders;
stat = SmsGetFolderCount( hPackageContainer, // Handle to package container.
                          F_PACKAGE,      // Get count of package folders 
                                      // in package container.
                          &ctFolders  // Assign count to pctFolders.     
                        );

// Loop to retrieve the handles to the
// package folders in the package container using SmsGetNextFolder,
// retrieve the scalar value for the Package ID and Name scalars using
// SmsGetScalarByID, and print the Package ID and Name.
HANDLE hFolder;

SCALAR scalar;
char *pszName;
char szScalarName[SMS_DATA_BUFF_SIZE];
char szScalarValue[SMS_DATA_BUFF_SIZE];
scalar.dwLen = sizeof(szScalarValue)-1;
scalar.pszName = szScalarName;
scalar.pszValue = szScalarValue;
scalar.scType = SCALAR_STRING;

DWORD iLoop;
for (iLoop = 1; iLoop <= ctFolders+1; iLoop++) {
    stat = SmsGetNextFolder( hPackageContainer,
                             F_ANY,
                             &hFolder);
    // if folder was retrieved, display ID and Name.
    if (stat == SMS_OK) {
        //print heading if first time in loop.
        if (iLoop == 1)    {
            printf("%-12s", "Package ID");    
            printf("%-25s\n", "Name");    
        }
        // Get the ID and Name and print them.
        pszName = "Key";
        stat = SmsGetScalarByName(hFolder, pszName, &scalar);
        printf("%-12s", scalar.pszValue);
        scalar.dwLen = SMS_DATA_BUFF_SIZE;
        pszName = "Name";
        stat = SmsGetScalarByName(hFolder, pszName, &scalar);
        printf("%-25s\n", scalar.pszValue);
    }
    // break if end of folder list.
    else if (stat == SMS_NO_MORE_DATA)
        break;
    // break if folder retrieval error.
    else {
        printf("Could not retrieve folder: %d\n", stat);
        break;
    }
}

//Prompt for package ID.
char szPackageID[9];
printf("Enter package ID:");
gets(szPackageID);

//Verify package ID.
int iCompare;
BOOL bPackageExist = FALSE;
//Rewind folders in container to iterate folders again.
stat = SmsRewind(hPackageContainer, RW_FOLDER);
//Loop to search for package with ID match in szPackageID.
iLoop = 1;
while ( iLoop <= ctFolders) {
    stat = SmsGetNextFolder( hPackageContainer,
                             F_ANY,
                             &hFolder);
    // if folder is retrieved, check if szPackageID matches
    // the folder's ID.
    if (stat == SMS_OK) {
        pszName = "Key";
        stat = SmsGetScalarByName(hFolder, pszName, &scalar);
        //compare package ID with ID of folder.
        iCompare = strcmp(szPackageID , scalar.pszValue);
        // if package id matches folder's ID,
        // then set bPackageExist to TRUE and break.
        if (iCompare == 0) {
               bPackageExist = TRUE;
            printf("Package ID verified.\n");
               break;
        }
    }
    // if end of folder list, package ID does not match;
    // therefore, reprompt for ID and check again.
    else if (stat == SMS_NO_MORE_DATA) {
        printf("Package ID specified does not exist.\n");
        // reset folder list to start of list.
        stat = SmsRewind(hPackageContainer, RW_ALL);
        // reset loop.
        iLoop=0;
        // prompt again for ID.
        printf("Enter package ID again:");
        gets(szPackageID);
    }
    // if error retrieving folder, print status code
    // and break.
    else {
        printf("Could not retrieve folder: %d\n", stat);
        break;
    }
    iLoop++; 
}

//***********************************************************
//****** Set the package ID scalar for the job folder.
//***********************************************************
// If the the package ID is valid, use it to set the 
// Package ID scalar for the Run Command On Workstation job.
if (bPackageExist == TRUE) {
    SCALAR sc; // Declare SCALAR struct to hold scalar data.
    char *pszScalarName = "Package ID"; // Name of the scalar to set.
    SCALARTYPE scType = SCALAR_STRING; // Data type of scalar.

    // Assign the scalar data to the sc structure.
    sc.pszName = pszScalarName;
    sc.scType  = scType;
    sc.dwLen = sizeof(szPackageID)-1; // -1 for terminating NULL.
    sc.pszValue = szPackageID;

    // Use SmsSetScalar to use the sc struct to set the 
    // scalar for the folder.
    stat = SmsSetScalar( hJobFolder, // Handle to folder containing 
                                     // the scalar to set.
                         &sc);       // Pointer to SCALAR struct 
                                     // containing value to set.
    if (stat == SMS_OK)
        printf("Package ID %s scalar set successfully.\n", sc.pszValue);
}
return stat;

}