Sun Java System Portal Server 7.1 Developer's Guide

Multi-valued Attribute Routines

A Search attribute can have multiple values. Search supports the convention of using -NNN to indicate a multivalued attribute. For example, Title-1, Title-2, Title-3, and so on. The -NNN do not need to be sequential positive integers.

The Search Engine supports searching on multi-valued attributes such as the classification attribute. In Search representation, it is represented using classification-1, classification-2, and so on. For example:

classification-1{5}: robot
classification-2{5}: siroe
classification-3{10}: web crawler

Search_AttributeCompareMV

NSAPI_PUBLIC int Search_AttributeCompareMV
(const char *a1, const char *a2);

Compares two attribute names. Returns 0 (zero) if they are equal, or non-zero if they are different. If neither of the attributes is multi-valued then use above routine Search_AttributeCompare(). If one or both of the attributes are multi-value, use the base name of the multi-valued attribute for comparison. The base name of a multi-valued attribute is the name portion before “-”. For example, the base name of classification-3 is classification.

Search_MVAttributeParse

NSAPI_PUBLIC int Search_MVAttributeParse(char *a)

Returns the multi-valued number of the given attribute, and strips the attribute string of its -NNN indicator; otherwise, returns zero in the case of a normal attribute name. For example, classification-3 returns the number 3.

Search_IsMVAttribute

NSAPI_PUBLIC char *Search_IsMVAttribute(const char *a);

Returns NULL if the given attribute is not a multi-valued attribute; otherwise returns a pointer to where the multi-valued number occurs in the attribute string. For example, for the multi-valued attribute classification-3, it will return the pointer to 3.

Search_InsertMV

NSAPI_PUBLIC int Search_InsertMV(Search *s, 
char *a, int slot, char *v, int vsz, int useval)

Inserts a new value v at index slot for the given attribute a (in non-multivalue form). If set, the useval flag tells the function to use the given value buffer rather than creating its own copy.

For example:

Search_InsertMV(s, "classification", 3, 
"web crawler", strlen("web crawler");

Inserts

classification-3{10}: web crawler

Search_ReplaceMV

NSAPI_PUBLIC int Search_ReplaceMV(Search *s, 
char *a, int slot, char *v, int vsz, int useval);

Search_DeleteMV

NSAPI_PUBLIC int Search_DeleteMV
(Search *s, char *a, int slot)

Deletes the value at the index slot in the attribute a. For example:

Search_DeleteMV(s, "classification", 3)

Deletes classification-3.

Search_FindvalMV

NSAPI_PUBLIC const char *Search_FindvalMV
(Search *s, const char *a, int slot)

Finds the value at the index slot in the attribute a. For example:

Search_FindvalMV(s, "classification", 3)

Returns web crawler (using the previous example).

Search_SqueezeMV

NSAPI_PUBLIC void Search_SqueezeMV(Search *s)

Forces a renumbering to ensure that the multi-value indexes are sequentially increasing (for example, 1, 2, 3,...). This function can be used to fill in any holes that might have occurred during Search_InsertMV() invocations. For example, to insert values explicitly for the multivalue attribute author-*:

Search_InsertMV(s, "author", 1, "John", 4, 0);
Search_InsertMV(s, "author", 2, "Kevin", 5, 0);
Search_InsertMV(s, "author", 6, "Darren", 6, 0);
Search_InsertMV(s, "author", 9, "Tommy", 5, 0);
Search_FindvalMV(s, "author", 9); /* == "Tommy" */
Search_SqueezeMV(s);
Search_FindvalMV(s, "author", 9); /* == NULL */
Search_FindvalMV(s, "author", 4); /* == "Tommy" */

SearchAVPair_IsMV

#define SearchAVPair_IsMV(avp)

Use this to determine if the AVPair has multiple values or not.

SearchAVPair_NthValid

#define SearchAVPair_NthValid(avp,n)

Use this to determine if the Nth value is valid or not.

SearchAVPair_NthValue

#define SearchAVPair_NthValue(avp,n)   ((avp)->values[n])

Use this to access the Nth value. For example:

for (i = 0; i <= avp->last_slot; i++)
  if (SearchAVPair_NthValid(avp, i))
    printf("%s = %s\\n", avp->attribute,
      SearchAVPair_NthValue(avp, i));

SearchAVPair_NthVsize

#define SearchAVPair_NthVsize(avp,n)   ((avp)->vsizes[n])

Use this to get the size of the Nth value.

Search_Contains

NSAPI_PUBLIC boolean_t Search_Contains
(Search *s, char *a, char *v, int vsz);

Indicates if the given attribute contains the given value. It returns B_TRUE if the value matches one or more of the values of the attribute a in the given Searches.