README.TXT

SMS API Example: object enumeration. (enumobj.exe) 
    ================================================== 
 
This sample illustrates the use of the SMS object enumeration APIs. 
The objects involved here are currently Architectures and Platforms, 
and their descendent objects. 
 
The API draws a distinction between 'first-class' and 'secondary objects. 
A 'first-class' object is one that can be described by SMS without any 
prior knowledge. The first-class objects that are known to the system 
is returned by calling SmsEnumObjectTypes. Calling this will currently 
result in two object-types being returned: Architectures and Platforms. 
In order to determine what Architectures exist the user then calls 
SmsEnumObjects, passing "Architectures" as the types of object that we 
are interested in. What is returned from this call depends on the 
individual database. The set of architectures will certainly include: 
        Personal Computer 
        SMSEvents 
        SNMP Traps      (SMS 1.2 and above) 
        PackageLocation 
        UserGroups 
        etc. 
These are all secondary objects whose type is "Architecture". 
 
It is now possible to determine what objects each of these contain. 
For instance, every object of type 'Architecture' will contain one or 
more object of type 'Group', such as "MICROSOFT|IDENTIFICATION|1.0". 
Note that it is impossible to determine what groups exist without first 
knowing what architecture the user is interested in. Similarly, while a 
Group object contains Attribute objects, it is impossible to know what 
Attributes exist without knowing what group we are talking about. 
This is why the SmsEnumObjects API has the notion of a predecessor list. 
 
The data type used by the API to describe an object that it returns 
is known as OBJDESCRIPTOR. Looking at the definition for this data type 
(see smsapi.h) we see that there are the following fields: 
         
    DWORD objType                Type of this object. 
 
    SMSBUFF szName               Object name (eg 'Personal Computer') 
 
    SMSBUFF szFriendlyName       Friendly name. Only used in groups 
                                 where szName would be, eg, 
                                 'MICROSOFT|IDENTIFICATION|1.0', the 
                                 friendly name would be 'Identification'. 
 
    BOOL bGotFriendlyName        TRUE if we have a friendly name. 
 
    DWORD dwRelopMin             For attributes, indicates range of 
    DWORD dwRelopMax             relational operators that can be used 
                                 for this attribute. 
 
    BOOL bGotRelops              TRUE if we have the relops fields set. 
 
 
The 'objType' parameter is one of the set of OT_ defines (also in smsapi.h). 
This tells the user what type of object is described by this OBJDESCRIPTOR. 
 
'szName' provides the name for this object (eg 'Personal Computer', 'SMSID'). 
 
'szFriendlyName' if this is not null then it gives a user-friendly name for 
the object (see above). This is only used in the case of Group objects, but 
the 'bGotFriendlyName' datum will indicate whether this field is present 
or not. 
 
'dwRelopMin' and 'dwRelopMax' are used by attributes. They inform the caller 
what the range of operators are for the attribute in question. 'bGotRelops' 
is TRUE if these fields are present. 
The values of these relational operators is from the file qrycodes.h. 
 
 
Note that this example operates in a recursive manner in order to enumerate 
all objects that are known to the API set. 
A different use would of the APIs would be something like: given a specific 
architecture and a specific group, what attributes exist. Code for this would 
be something like: 
        (where Architecture is Personal Computer, and Group is MICROSOFT| 
         VIDEO|1.0) 
 
 
    SMSBUFF aPreds[10]; 
    strcpy( aPreds[0], "Architectures" ); 
    strcpy( aPreds[1], "MICROSOFT|VIDEO|1.0 ); 
    strcpy( aPreds[2], "MICROSOFT|VIDEO|1.0 ); 
 
    SmsEnumObjects( hConnect,   // Handle to datasource connection. 
                    pszObj,     // Attribute. 
                    pPreds,     // see above. 
                    ctPreds,    // 3: Architectures, PC, MS|VIDEO|1.0 
                    Objects,    // filled in by API. 
                    &ctObjs );  // filled in by API. 
 
This would return, in 'Objects', all attributes for the video group.