SmsSetScalar

The SmsSetScalar function sets the value of a scalar within a new folder created by SmsCreateFolder. Or SmsSetScalar can be used to set a scalar within a persistent filter created by SmsCreateFilter.

SMS_STATUS SmsSetScalar(
  HANDLE hFolder,        // Handle to folder or filter in which to 
                         // set the scalar.
  SCALAR *pScalarStruct  // Pointer to SCALAR structure containing 
                         // the scalar value to set.
);
 

Parameters

hFolder

Specifies the handle to the folder or filter containing the scalar to set.

pScalarStruct

Points to a SCALAR structure that contains the scalar data to be set.

Return Values

The SmsSetScalar function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns one of the following manifest constants:

SMS_INVALID_HANDLE

The specified parent handle is not a valid folder handle or filter handle.

SMS_FOLDER_ALREADY_DELETED

An action was attempted on a folder or persistent filter that has already been deleted.

SMS_FOLDER_NO_UPDATE

The folder is of a type that has read-only access.

SMS_SCALAR_NO_UPDATE

The scalar is of a type that has read-only access.

SMS_NOT_FOUND

The specified folder does not contain the specified scalar.

SMS_PARAMETER_ERROR

A scalar of type SCALAR_TIME has an invalid time value specified.

SMS_SCALAR_WRONG_TYPE

The scType member specified in the SCALAR structure does not match the actual type of the specified scalar.

Remarks

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 to the scalar, SmsSetScalar returns an SMS_SCALAR_NO_UPDATE value. If you do not have access to the folder, SmsSetScalar returns an SMS_FOLDER_NO_UPDATE value.

In addition, the SmsSetScalar function compares the data being set by the pScalarStruct structure with the actual data type for the scalar. If your application attempts to set an integer value for a scalar with a string data type, the SmsSetScalar function does not set the scalar value and returns SMS_SCALAR_WRONG_TYPE.

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

Note For workstation command line folders (F_WCL), the Name scalar is also used as the identifier for the folder. When creating a new F_WCL folder, your application should ensure that this scalar is not set to a string that is already being used by another workstation command line folder within the same package folder. If the Name scalar for the folder is the same as the Name scalar for another F_WCL folder in the same package, your application will not be able to commit the new F_WCL folder.

See Also

SmsCreateFolder, SmsDescribeFolder, SmsLinkFolder, SmsCreateFilter, SmsCommitFilter