catalog_query.h File Reference

Query the global catalog server for server descriptions. More...

`#include <time.h>`
`#include "jx.h"`

Go to the source code of this file.

## Enumerations

enum | catalog_update_flags_t { CATALOG_UPDATE_BACKGROUND =1 , CATALOG_UPDATE_CONDITIONAL =2 }
| Catalog update control flags. More...

## Functions

struct catalog_query * | catalog_query_create (const char *hosts, struct jx *filter_expr, time_t stoptime)
| Create a catalog query.
struct jx * | catalog_query_read (struct catalog_query *q, time_t stoptime)
| Read the next object from a query.
void | catalog_query_delete (struct catalog_query *q)
| Delete a completed query object.
int | catalog_query_send_update (const char *hosts, const char *text, catalog_update_flags_t flags)
| Send update text to the given hosts hosts is a comma delimited list of hosts, each of which can be host or host:port.

## Detailed Description

Query the global catalog server for server descriptions.

## Enumeration Type Documentation

## catalog_update_flags_t

enum catalog_update_flags_t

Catalog update control flags.

These control the behavior of catalog_query_send_update

Enumerator
CATALOG_UPDATE_BACKGROUND | Send update via a background process if TCP is selected.
CATALOG_UPDATE_CONDITIONAL | Fail if UDP is selected and update is too large to send.

## Function Documentation

## catalog_query_create()

struct catalog_query * catalog_query_create | ( | const char * | hosts,
|  | struct jx * | filter_expr,
|  | time_t | stoptime )

Create a catalog query.

Connects to a catalog server, issues a query, and waits for the results. The caller may specify a specific catalog host and port. If none is given, then the environment variables CATALOG_HOST and CATALOG_PORT will be consulted. If neither is set, the system will contact chirp.cse.nd.edu on port 9097.

Parameters

  hosts | A comma delimited list of catalog servers to query, or null for the default server.
  filter_expr | An optional expression to filter the results in JX syntax. A null pointer indicates no filter.
  stoptime | The absolute time at which to abort.

Returns
  A catalog query object on success, or null on failure.

## catalog_query_read()

struct jx * catalog_query_read | ( | struct catalog_query * | q,
|  | time_t | stoptime )

Read the next object from a query.

Returns the next jx expressions from the issued query. The caller may use jx_lookup_string, jx_lookup_integer and related functions to manipulate the object, and then must call jx_delete when done.

Parameters

  q | A query created by catalog_query_create.
  stoptime | The absolute time at which to abort.

Returns
  A jx expression representing the next result, or null if the end of stream has been reached.

## catalog_query_delete()

void catalog_query_delete | ( | struct catalog_query * | q | ) |

Delete a completed query object.

Parameters

  q | The query to delete.

## catalog_query_send_update()

int catalog_query_send_update | ( | const char * | hosts,
|  | const char * | text,
|  | catalog_update_flags_t | flags )

Send update text to the given hosts hosts is a comma delimited list of hosts, each of which can be host or host:port.

Parameters

  hosts | A list of hosts to which to send updates
  text | String to send
  flags | Any combination of CATALOG_UPDATE

Returns
  The number of updates successfully sent,