Create a new folder

To create a folder

Use the SmsCreateFolder function to create a new folder. The SmsCreateFolder function can create folders within a container (top-level folders) or a subfolder within a folder.
The SmsCreateFolder function takes four parameters:
- The handle to the parent of the new folder (the parent can be a container or a folder)
- The type of folder to create
- An identifier for the folder
- A pointer to a handle that is assigned the handle to the new folder. You use the handle to manage the new folder.
After a new folder has been created, the folder is empty, that is, it has no scalars set within it. Using the SmsSetScalar function, your application must set the scalars for the new folder. A new folder also does not contain any subfolders. In addition, a new folder created by SmsCreateFolder is not linked to its parent folder (you use the SmsLinkFolder function to link a new folder to its parent). A new folder also is not added to the site database until you use the SmsCommitFolder function to write the folder to the database.
Example:
```
// This example shows how to create a 
// Run Command On Workstation job 
// folder for a job container.

cType = C_JOB; // Set container type to job.
// Open the job container.
stat = SmsOpenContainer( cType,   
                         hConnect,
                         &hContainer);

HANDLE hFolder; // Declare a handle for the new folder.
stat = SmsCreateFolder ( hContainer,
                         F_INSTALLJOB, // Folder type is Run 
                                       // Command On 
                                       // Workstation.
                         NULL,         // SMS system assigns 
                                       // ID. Therefore, this 
                                       // parameter is ignored.
                         &hFolder     // Handle to new folder.
                        );
 
```

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 or ACCESS_CREATE right 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:

The handle to the folder containing the scalar
A pointer to a SCALAR structure that contains the scalar data to be set

Example:

// Set the Package ID scalar for 
// a Run Command On Workstation job.
SCALAR sc;                  // Declare SCALAR struct to hold 
                            // scalar data.
char *szScalarName = "Package ID"; // Name of the scalar to set.
SCALARTYPE scType = SCALAR_STRING; // Data type of scalar.
char *pszScalarValue = "TIM00001"; // Value to set.
// Assign the scalar data to the sc structure.
sc.pszName = szScalarName;
sc.scType  = scType;
sc.dwLen = sizeof(pszScalarValue)-1;
sc.pszValue = pszScalarValue;

// Use SmsSetScalar to use the sc struct to set 
// the scalar for the folder.
stat = SmsSetScalar( hFolder, // Handle to folder containing 
                              // the scalar to set.
                     &sc      // Pointer to SCALAR struct 
                              // containing value to set.
                   );

After setting the scalars, use the SmsLinkFolder function to link the folder to its parent (the parent is the container or folder within which the new folder was created). Note that linking a folder only associates the folder to its parent within the application's memory—the folder is not written to the site database.
Example:
```
// Link the new folder to its parent.
stat = SmsLinkFolder( hFolder );
```
Use the SmsCommitFolder function to write the new folder to the site database.
Some folders require their direct parent folders to be committed in order to be written to the site database. If a folder requires its parent to be committed, the SmsCommitFolder function will return a status of SMS_PARENT_NEEDS_COMMIT.
Example:
```
// Write the new folder to the site database.
stat = SmsCommitFolder( hFolder );
```
Note that the new folder is not written to the site database until the application calls the SmsCommitFolder function for that folder. If you do not want to write the new folder into the database, you can use the SmsCloseFolder function to deallocate the memory used by the new folder.