--- name: "nws" section: "3" platform: "linux" package: "nws" version: "2.13-6.1" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/nws" --- # nws(3) Howto use the Network Weather Service API. ## NAME nws - Howto use the Network Weather Service API. ## SYNOPSIS nws ## DESCRIPTION This man page briefly explain how to use the Network Weather Service (NWS) API. We will provide few example upon which you can build your own program that interface with NWS. We assume there is already a NWS system in place ([nws\_nameserver(1)](/nws_nameserver/1.md), [nws\_memory(1)](/nws_memory/1.md) and [nws\_sensor(1)](/nws_sensor/1.md)). To be able to access the NWS API you need to include the **nws\_api.h** header file and compile with **-llibnws.a** option to include the library. ## HEADER FILES Currently NWS provides the following header file: **nws\_api.h** this is the main and only header file to access NWS. If before the include statement NWSAPI\_SHORTNAMES is defined, shorted naming of the functions can be used (e.g. NWSAPI\_GetMeasurements can be referenced as GetMeasurements). In the EXAMPLES sections there are few examples on how to use the functions here defined. ## DATA STRUCTURES The NWS API uses few data structures: here there is a list of the most important one; **NWSAPI\_HostSpec** defines a hostname port pair: we expect to have a NWS component listening on hostname:port. **NWSAPI\_SeriesSpec** a description of a NWS experiment series. The series is uniquely identified by a source machine, a destination machine (ignored for single machine resource) and a resource name. **NWSAPI\_Measurement** is a structure containing *timeStamp* and *measurement* (both double). It is a single measurement as returned by an experiment. **NWSAPI\_Forecast** is a structure containing *forecast,* *error,* and *methodUsed* (forecast and error are double). It is a single forecast returned by a forecaster (identified by the index *methodUsed* ) with an estimate of its precision. **NWSAPI\_ForecastCollection** is a structure containing a collection of the best forecastes based on MAE (mean absolute error) and MSE (mean square error). It contains *measurement* (inclued here for convenience) and *forecasts* an array of 2 NWSAPI\_Forecast (first one is MAE forecast and the second is MSE forecast). **NWSAPI\_ForecastState** this is an opaque structure used to keep the state of the forecaster. You shouln't modify it directly nor read it. **NWSAPI\_ObjectSet** it is a typedef to char \*. NWSAPI\_ObjectSet are used when retrieving registration from a nameserver or such: there are specific NWS functions to deal with NWSAPI\_ObjectSet. **NWSAPI\_Object** it is a typedef to char \*. NWSAPI\_Objest contains NwsAttribute and are contained in NWSAPI\_ObjectSet. There are specific NWS functions to deal with NWSAPI\_Object. **NWSAPI\_ObjectSet** it is a typedef to char \*. NWSAPI\_NwsAttribute is a pair of tag:value and are usually contained in NWSAPI\_Object. There are specific NWS functions to deal with NWSAPI\_NwsAttribute. ## API FUNCTIONS Here we list most of the functions defined in the NWS API with a brief explanation on their functionality. See EXAMPLES for examples on how to use them. Here we use the short names (that is without the NWSAPI\_ if we had defined NWSAPI\_SHORTNAMES). const HostSpec \* **MakeHostSpec** (const char \*host, Port machinePort) generate a HostSpec given a machine name and a port. const SeriesSpec \* **MakeSeriesSpec** (const char \*sourceMachine, const char \*destinationMachine, const char \*seriesName); generate a SeriesSpec given a resource name and a source and destination machine. const char \* **SeriesName** (const SeriesSpec \*whichSeries); contructs a series name given a SeriesSpec const char \* **ForecasterMethodName** (unsigned int methodIndex) returnes the name of the forecasting method corresponding to *methodIndex* (as found in a Forecast) ForecatState \* **NewForecastState** (); returns a new forecast state ready to be used by UpdateForecast (for example). void **FreeForecastState** (ForecastState \*\*state); free the memory associated with this forecaster state. void **UpdateForecastState** (ForecastState \*state, const Measurement \*measurements, size\_t howManyMeasurements, ForecastCollection \*forecasts, size\_t howManyForecasts); update the state of forecas given the *howManyMeasurements* ner *measurements.* If *forecasts* is not NULL, *howManyForecasts are returned.* void **UpdateForecast** (ForecastState \*state, const Measurement \*measurements, size\_t howManyMeasurements,); similar to **UpdateForecastState** but doens't return any forecast, just update the forecaster state. int **GetForecasts** (const char \*seriesName, double sinceWhen, ForecastCollection \*whereTo, size\_t atMost, size\_t \*numberReturned); retrieves a time series of forecast collections for measurements of the series named *seriesName* that have been generated since *sinceWhen* and returns them in the *atMost* long array *whereTo* It stores ths count od retrieved collections in *numberedReturned* if it is non-NULL. Return 1 if succesfull, else 0. int **GetForecast** (const char \*seriesName, ForecastCollection \*whereTo); similar to GetForecasts, just return 1 forecastCollection. int **GetMeasurements** (const char \*seriesName, double sinceWhen, Measurement \*whereTo, size\_t atMost, size\_t \*numberReturned); retrieves up to *atMost* measurements for the series named *seriesName* that have been taken since *sinceWhen* (the most recent ones are returned). Returns the measurements in the *atMost* ling array *whereTo* with the newest one in the first element. Stores the count of retrieved measurements in *numberReturned* if non-NULL. Returns 1 on success, 0 else. int **GetMeasurment** (const char \*seriesName, Measurement \*whereTo); similar to **GetMeasurements** but returns only the last measurement. int **UseMemory** (const HostSpec \*whichMemory); use *whichMemory* as NWS memory, that is as the repository for all the measurements. If not set, the interface will attempt to find the best NWS memory available for the required data. Returns 1 if succesfull, else 0. int **UseNameServer** (const HostSpec \*whichNS) add *whichNS* to the NWS nameservers list to use. Needed when looking for registrations and information on the NWS deployment. You need to set at least one NWS nameserver before been able to **GetMeasurements** and **GetForecasts** etc... If *whichNS* is NULL or the empty string, the list is reset. Returns 1 if succesfull, else 0. int **GetNameServer** (const HostSpec \*whoToAsk, HostSpec \*nameServer); contact the NWS host *whoToAsk* and returns the nameserver used by it in *nameserver.* Returns 1 if succesfull, else 0. int **GetMemory** (const HostSpec \*whoToAsk, HostSpec \*memory); contact the NWS host *whoToAsk* and returns the memory used by it in *memory.* Returns 1 if succesfull, else 0. int **GetObjects** (const char \*filter, ObjectSet \*whereTo); contact the nameserver (see **UseNameServer()** ) and retrieves the objects that matches *filter.* Returns the restrieved objects in *whereTo.* After a succesful call, **FreeObjectSet** needs to be called on *whereTo* to free the memory. Returns 1 if succesfull, else 0. void **FreeObjectSet** (ObjectSet \*toBeFreed); free the memory used by *toBeFreed.* Objecct **NextObject** (ObjectSet objects, Object current); returns the next NWS objects contained in *objects* after *current* object or the first object if NULL. Returns NULL if no more objects are presents. NwsAttribute **NextNwsAttribute** (Object object, NwsAttribute current); returns the next NWS attribute contained in *object after* *current* attribute or the first attribute if NULL. Returns NULL if no more attribute are presents. ## EXAMPLES We will assume that a NWS system is already deployed with at least a nameserver (host NS.test.edu in the example), a NWS memory (host MEM.test.edu in the example) and two sensors (hosts ONE.test.edu and TWO.test.edu in the example). In the following examples all error checking is omitted and only the part relevant to NWS have been included to keep the code easy to follow. The following example retrieves a list of hosts registered with the nameserver: ``` #define NWSAPI_SHORTNAMES #include "nws_api.h" HostSpec *NS; char filter[256]; ObjectSet objs; Object current; NwsAttribute attr; char *tmp, *tmp1; /* let's instruct the interface to use the right nameserver */ NS = MakeHostSpec("NS.test.edu", 8090); UseNameServer(&NS); /* create the right filter */ sprintf(filter, "objectclass=nwsHost"); /* query the NS */ GetObjects(filter, &objs) /* now we can browse though the objects*/ for (current = NextObject(objs, NULL); current != NULL; current = NextObject(objs, current)) { /* now we can browse though the attribute*/ for (attr = NextNwsAttribute(current, NULL); attr != NULL; attr = NextNwsAttribute(current, attr)) { /* do some pretty printing */ tmp = NwsAttributeName_r(attr); tmp1 = NwsAttributeValue_r(attr); printf("%s: %s\n", tmp, tmp1); free(tmp); free(tmp1); } } ``` Of course one important feature of NWS is to report measurements and forecasts of specific resources. The following example extracts measurements and generate forecasts for a known nwsSeries (where the series name can be found querying the nws\_nameserver -- see the previous example): ``` #define NWSAPI_SHORTNAMES #include "nws_api.h" char *series; SeriesSpec *spec; int howMany; HostSpec NS; /* how many measurement we retrieve */ #define HOW_MANY 20 Measurement meas[HOW_MANY]; ForecastCollection forecasts[HOW_MANY]; ForecastState *state; /* let's instruct the interface to use the right nameserver */ NS = MakeHostSpec("NS.test.edu", 8090); UseNameServer(&NS); /* get the series name: the right way is to query the nameserver to find * the right name of the series. For simplicity we build one here, * assuming that there is indeed such a series reigsterd with the * nameserver */ spec = MakeSeriesSpec("a.edu", "b.edu", "bandwidthTcp"); series = SeriesName(spec); /* initialize the forecast state */ state = NewForecastState(); /* get the measurements */ if (!GetMeasurements(series, NWSAPI_BEGINNING_OF_TIME, meas, HOW_MANY, &howMany)) { printf("failed to retrieve measurements\n"); exit(0); } /* we have howMany measurements: generate the forecasts now. */ UpdateForecastState(state, meas, howMany, forecasts, howMany); /* ForecastCollection keeps a copy of the measurements handy : let's * print measurments and forecasts */ for (; howMany >= 0; howMany--) { printf("time %.5f measurement %.2f ", forecasts[howMany].measurement.timeStamp, forecasts[howMany].measurement.measurement) /* we use only the MAE forecasts here */ pritnf("forecast %.5f with error %.5f method used %s\n", forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].forecast, forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].error, MethodName(forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].methodUsed); } /* free the memory associated with the forecast state */ FreeForecastState(&state); ``` Starting from version 2.11 of NWS, you can call directly GetForecasts without having the need of a forecaster process running. The previous code can then be written as: ``` #define NWSAPI_SHORTNAMES #include "nws_api.h" char *series; SeriesSpec *spec; int howMany; HostSpec NS; /* how many measurement we retrieve */ #define HOW_MANY 20 ForecastCollection forecasts[HOW_MANY]; /* let's instruct the interface to use the right nameserver */ NS = MakeHostSpec("NS.test.edu", 8090); UseNameServer(&NS); /* get the series name: the right way is to query the nameserver to find * the right name of the series. For simplicity we build one here, * assuming that there is indeed such a series reigsterd with the * nameserver */ spec = MakeSeriesSpec("a.edu", "b.edu", "bandwidthTcp"); series = SeriesName(spec); /* get the forecasts */ if (!GetForecasts(series, NWSAPI_BEGINNING_OF_TIME, forecasts, HOW_MANY, &howMany)) { printf("GetForecasts failed\n"); exit(0); } /* ForecastCollection keeps a copy of the measurements handy : let's * print measurments and forecasts */ for (; howMany >= 0; howMany--) { printf("time %.5f measurement %.2f ", forecasts[howMany].measurement.timeStamp, forecasts[howMany].measurement.measurement) /* we use only the MAE forecasts here */ pritnf("forecast %.5f with error %.5f method used %s\n", forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].forecast, forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].error, MethodName(forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].methodUsed); } ``` ## BUGS Bugs list is at http://nws.cs.ucsb.edu. ⟨http://nws.cs.ucsb.edu⟩ ## AUTHOR NWS is an original idea of Rich Wolski Rich Wolski (rich@cs.ucsb.edu). Neil Spring, Jim Hayes (jhayes@cs.ucsd.edu) and Martin Swany maintained and enhanced it. Graziano Obertelli (graziano@cs.ucsb.edu) currently maintains NWS and wrote this man page. ## SEE ALSO **[nws\_sensor(1)](/nws_sensor/1.md),** **[nws\_search(1)](/nws_search/1.md),** **[nws\_nameserver(1)](/nws_nameserver/1.md),** **[nws\_memory(1)](/nws_memory/1.md),** **[nws\_extract(1)](/nws_extract/1.md)**