SCALAR

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).

Members

scType

Specifies a SCALARTYPE enumerated type that indicates the type of the scalar. The members used in the SCALAR structure are determined by the scalar type.

pszName

Points to a string buffer that specifies the name of the scalar. To get the list of all scalars within a folder (and the general properties of those scalars such as name, type, and access mode), use the SmsDescribeFolder function.

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.

pszValue

Points to a string buffer containing the value of the scalar.

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.

dwValue

Specifies the value of the scalar if the scalar's type is SCALAR_INT.

tValue

Specifies the value of the scalar if the scalar's type is SCALAR_TIME.

pValue

Points to a buffer that contains the binary value. Your application must ensure that the buffer for the binary is large enough for the value of the scalar. To get the size of the value, call SmsGetNextScalar or SmsGetScalarByName with dwLen set to NULL. These functions will return a status of SMS_MORE_DATA and will set the dwLen member to the size of the value.

dwLen

Specifies the size of the scalar value if the scalar type is SCALAR_STRING or SCALAR_BINARY.

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.

bStringEquivalence

Specifies whether a string equivalent is available for a scalar with scalar type SCALAR_INT or SCALAR_TIME. TRUE specifies that a string exists. The string value is placed in the pszValue member. The bStringEquivalence member applies only to scalars with scalar type SCALAR_INT or SCALAR_TIME.

fAccess

Specifies the access right of the scalar. See Access Rights.

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.

Remarks

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.

See Also

SmsSetScalar, SmsGetNextScalar, SmsGetScalarByName, SmsDescribeFolder