The SCALAR structure contains information about a specific scalar within a folder.
typedef struct _SCALAR {
SCALARTYPE scType;
char *pszName;
char *pszValue;
DWORD dwValue;
time_t tValue;
void *pValue;
DWORD dwLen;
BOOL bStringEquivalence;
DWORD fAccess;
} SCALAR;
The SCALAR structure is used by the scalar functions to read or set scalars within folders (SmsSetScalar, SmsGetNextScalar, and SmsGetScalarByName).
Your application must ensure that a buffer for the string is large enough for the name of the scalar. Your application can use the SMS_DATA_BUFF_SIZE value, which is the maximum allowable length for a string stored in a site database.
If the scalar's type is SCALAR_STRING, this member points to a string buffer to contain the string value.
If the bStringEquivalence member is set to TRUE and the scalar's type is SCALAR_INT or SCALAR_TIME, this member is the string equivalent for the value of the scalar.
Your application must ensure that a buffer for the string is large enough for the value of the scalar. To get the size of the value, call SmsGetNextScalar or SmsGetScalarByName with pszValue and dwLen set to zero. These functions will return a status of SMS_MORE_DATA and will set the dwLen member to the size of the value. Your application can also use the SMS_DATA_BUFF_SIZE value, which is the maximum allowable length for a string stored in a site database.
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.
When the SmsGetNextScalar or SmsGetScalarByName functions are called, this member specifies the size of the buffer receiving the scalar value.
If the SmsGetNextScalar or SmsGetScalarByName functions are called with this member set to zero, the length of the scalar value is returned in this member and the function returns a status of SMS_MORE_DATA.
Note that the access right of each scalar is set by the SMS API engine—your application can read the access right of a scalar but it cannot set the access right.
To set the value of a scalar, the scalar must have access rights of ACCESS_CREATE or ACCESS_MODIFY and its folder must have access rights of ACCESS_CREATE or ACCESS_MODIFY. If the folder and scalar do not have these rights, 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.
All scalars have a type, a name, a value, and an access mode.
The SCALAR structure contains separate members for the value for each scalar type. If the scalar's type is SCALAR_STRING or SCALAR_BINARY, the dwLen member specifies the size of the scalar value. For example, if your application retrieves a scalar of type SCALAR_STRING by using the SmsGetNextScalar function, the function sets the following members in the SCALAR structure that receives the scalar: scType to SCALAR_STRING, pszName to the name of the scalar, pszValue to the value of the scalar, dwLen to the length of the scalar value, and fAccess to the access mode for the scalar.
SmsSetScalar, SmsGetNextScalar, SmsGetScalarByName, SmsDescribeFolder