Chapter 23 About the RDM API

This chapter

• Introduction to the RDM API

• rdm.h File

• API Reference

Introduction to the RDM API

This chapter describes the use of the search engine Resource Description Manager (RDM) API to access the search engine and its database. The RDM API provides routines to parse, modify, and create resource description messages (RDMs) using C.

The robot generates RDs and saves them to the search engine database. You can retrieve the RDs in SOIF format, use the RDM API to modify them, and then have the search engine import them back.

The RDM API is defined in the rdm.h file in the following directory in your search engine installation directory:

PortalServer-base/sdk/rdm/include

This chapter is restricted to discussing the use of C functions that come with the search engine RDM API. Therefore, it is strongly recommended that you have a basic understanding of the C programming language.

rdm.h File

The file rdm.h defines structures and functions for creating RDMs. The intent of these functions is to construct queries and instructions that can be output as RDM and sent via the sendrdm program to a search engine for processing. These queries and instructions are created in the C programming language.

The basic structures are:

• RDMHeader

• RDMQuery

To support each of these main structures, there are additional structures like RDMViewAttributes, RDMViewOrder, and RDMViewHit which are used to represent attributes in an RDMQuery.

The RDM API defined in rdm.h file provides functions for creating and modifying these structures. For example, the following statement:

RDMQuery *myquery = RDMQuery_Create("varrius");

creates an RDMQuery that corresponds to the following SOIF:

@RDMQUERY { -
    scope{7}:varrius
}

The following statement:

RDMQuery_SetViewAttr(myquery, "URL,Title");

modifies the RDMQuery so that it corresponds to the following SOIF:

@RDMQUERY { -
    scope{7}:varrius
    view-attributes{30}: URL,Title,Author,Last-Modified
}

Both the RDMHeader and RDMQuery structures have soif fields, which contain the SOIF data for the header or the query. To extract SOIF data from RDMHeader or RDMQuery, you can access the soif field. Thus, you can also use the RDM SOIF API to create and modify RDMHeader and RDMQuery objects.

API Reference

This section describes the RDM API, located in directory PortalServer-base/sdk/rdm/include/rdm.h.

Finding the RDM Version

RDM_Version

NSAPI_PUBLIC const char *RDM_Version(void);

Returns the version of the RDM library.

Creating and Freeing RDM Structures

For most RDMX structures, such as RDMRequest, RDMQuery, and so on, there are two or more creation functions. There is usually an RDMX_Parse() function, which takes SOIF arguments, and an RDMX_Create() function, which takes non-SOIF arguments.

There is also an RDMX_Free() function, which releases the object.

Several RDM structures also have an RDMX_merge() function, which merges data from a SOIF object into an existing RDMX structure.

An RDMHeader

An RDMHeader represents the header of an RDM. An RDMHeader structure has one public field, soif, which is a SOIF containing a collection of attribute-value pairs. The allowable attribute names of the attribute-value pairs in the SOIF are:

• rdm-version (required) - This is set automatically if you use RDMHeader_CreateRequest() or RDMHeader_CreateResponse() to create the RDMHeader.

• rdm-type (required).

• catalog-service-id (recommended) - This indicates which search engine instance to send the RDM request to).

• rdm-query-language (required for a request) - For communicating with the search engine, you can specify search.

Response RDMs also have several attributes, and you can find them in rdm.h.

The following statements create an RDMHeader whose RDMType is RDM_RD_REQ, and whose query language is search. This RDM will be sent to the search engine instance search1 of the search engine at http://budgie.siroe.com:6714.

CSID *csid = CSID_Parse("x-catalog://budgie.siroe.com:6714/search1");
RDMHeader *myheader = RDMHeader_CreateRequest(RDM_RD_REQ, "search", csid);

The following is a description of the allowable values for RDM-Type:

RDM_MSGTYPE_UNKNOWN

Undefined or unknown message type

RDM_RD_UPD_REQ

Requesting an RD update

RDM_RD_REQ

Requesting an RD update (same as RDM_RD_UPD_REQ)

RDM_RD_DEL_REQ

Requesting an RD delete

RDM_RD_UPD_RES

Responding to an RD update request

RDM_RD_RES

Responding to an RD update request (same as RDM_RD_UPD_RES)

RDM_RD_DEL_RES

Responding to an RD delete request

RDM_SD_REQ

Requesting a server description

RDM_SD_RES

Responding to a server description request

RDM_SCH_REQ

Requesting a schema description

RDM_SCH_RES

Responding to a schema description request

RDM_TAX_REQ

Requesting a taxonomy description

RDM_TAX_RES

Responding to a taxonomy description request

RDM_STAT_REQ

Requesting a status

RDM_STAT_RES

Responding to a status description request

You can use the following macros to get and set the string values of the attributes:

RDMHeader_GetType(RDMHeader) /* returns RDMType */
RDMHeader_GetVersion(RDMHeader)
RDMHeader_GetQueryLanguage(RDMHeader)
RDMHeader_GetCSID(RDMHeader)
RDMHeader_GetResponseInterpret(RDMHeader)
RDMHeader_GetErrorMessage(RDMHeader)
RDMHeader_GetErrorNumber(RDMHeader)

RDMHeader_SetType(RDMHeader,RDMType)
RDMHeader_SetVersion(RDMHeader,stringvalue)
RDMHeader_SetQueryLanguage(RDMHeader,stringvalue)
RDMHeader_SetCSID(RDMHeader,stringvalue)
RDMHeader_SetResponseInterpret(RDMHeader,stringvalue)
RDMHeader_SetErrorMessage(RDMHeader,stringvalue)
RDMHeader_SetErrorNumber(RDMHeader,stringvalue)

RDMHeader_Parse

NSAPI_PUBLIC RDMHeader *RDMHeader_Parse(SOIFStream *ss);

RDMHeader_Create

NSAPI_PUBLIC RDMHeader *RDMHeader_Create(RDMType t);

RDMHeader_CreateRequest

NSAPI_PUBLIC RDMHeader *RDMHeader_CreateRequest(RDMType, char *ql, CSID *)

RDMHeader_CreateResponse

NSAPI_PUBLIC RDMHeader *RDMHeader_CreateResponse(RDMType, char *ri, CSID *);

RDMHeader_Free

NSAPI_PUBLIC int RDMHeader_Free(RDMHeader *r);

RDMHeader_Merge

NSAPI_PUBLIC int RDMHeader_Merge(RDMHeader *, SOIF *)

Merges data from a SOIF object into the RDMHeader object.

An RDMQuery

An RDMQuery represents the body of an RDM. An RDMQuery structure has one public field, soif, which is a SOIF containing a collection of attribute-value pairs. The allowable attribute names of the attribute-value pairs in the SOIF are:

• scope (required)

• view-attributes (optional)

• view-hit (optional)

• view-order (optional)

• view-template (optional)

You can use the following macros to get and set the string values of these attributes:

RDMQuery_GetScope(query)
RDMQuery_GetViewAttr(query)
RDMQuery_GetViewHits(query)
RDMQuery_GetViewOrder(query)
RDMQuery_GetViewTemplate(query)

RDMQuery_SetScope(query, value)
RDMQuery_SetViewAttr(query,value-list)
RDMQuery_SetViewHits(query,value)
RDMQuery_SetViewOrder(query,value-list)
RDMQuery_SetViewTemplate(query,value)

RDMQuery_Parse

NSAPI_PUBLIC RDMQuery *RDMQuery_Parse(SOIFStream *ss);

RDMQuery_Create

NSAPI_PUBLIC RDMQuery *RDMQuery_Create(const char *scope);

RDMQuery_Free

NSAPI_PUBLIC int RDMQuery_Free(RDMQuery *);

RDMQuery_Merge

NSAPI_PUBLIC int RDMQuery_Merge(RDMQuery *, SOIF *);

Other RDM Structures

In addition to RDMHeader and RDMQuery, the file rdm.h provides definitions and functions for the following auxiliary objects. See the file rdm.h in PortalServer-base/sdk/rdm/include directory for details.

• RDMRequest

• RDMResponse

• RDMServer

• RDMView

• RDMViewHits

• RDMViewOrder

• RDMTaxonomy

• RDMClassification

• RDMSchema