SmsGetScalarByName

The SmsGetScalarByName function retrieves the scalar with the specified scalar name from the specified folder and writes the scalar's information into a SCALAR structure.

SMS_STATUS SmsGetScalarByName(
  HANDLE hFolder,       // Handle to folder.
  const char *pszName,  // Pointer to string containing the name of 
                        // the scalar.
  SCALAR *pScalarStruct // Pointer to SCALAR structure to receive 
                        // scalar data.
);
 

Parameters

hFolder

Specifies the handle to the folder from which you want to retrieve the scalar.

Note that SmsGetScalarByName cannot be used to retrieve scalars from a persistent filter. Scalars for persistent filters can be retrieved in sequence only (by using SmsGetNextScalar).

pszName

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

pScalarStruct

Points to a SCALAR structure that will receive the information for the scalar to be retrieved. Your application is responsible for allocating the memory for this structure.

If the scalar is of type SCALAR_STRING or SCALAR_BINARY, your application must ensure that the buffer for the string or binary is large enough for the value of the scalar. Note that the pszValue member points to a string buffer and the pValue member points to a buffer for a binary.

To get the correct size for the buffers, call the SmsGetScalarByName function with the dwLen member of the pScalarStruct structure set to NULL. SmsGetScalarByName will assign the size of the string or binary value and return a status of SMS_MORE_DATA. After getting the size of the value, create a buffer large enough for the value and assign a pointer to that buffer to the pszValue member for SCALAR_STRING or pValue for SCALAR_BINARY. Then call the SmsGetScalarByName function again using a pScalarStruct structure with the correct size for dwLen and a pointer to a sufficiently sized buffer for the pszValue (SCALAR_STRING) or pValue (SCALAR_BINARY).

Caution Some string scalars may contain embedded control characters. For example, the STRING_1 through STRING_10 attributes for folders with the SMSEvent architecture contain embedded newline and other control characters. Your application is responsible for detecting and handling these control characters.

Return Values

The SmsGetScalarByName 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.

SMS_FOLDER_ALREADY_DELETED

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

SMS_NOT_FOUND

The specified scalar was not contained in the folder.

SMS_MORE_DATA

The dwLen member of the pScalarStruct structure was set to NULL. SmsGetScalarByName sets the dwLen member to the size of a SCALAR_STRING or SCALAR_BINARY scalar.

SMS_NO_MORE_DATA

The specified folder does not contain any scalars.

Remarks

Scalars can be retrieved in sequence or by the scalar name. To retrieve scalars in sequence, use the SmsGetNextScalar function. To retrieve scalars by scalar name, use the SmsGetScalarByName function.

See Also

SmsDescribeFolder, SmsGetNextScalar