TOPIC: NED client user's guide AUTHOR: Xiuqin Wu & NED team TIME: March 16, 1994 NED has been providing services for the Astronomical community for more than three years through our interactive interface. In Response to repeated requests from users for a client/server and manipulative mode access, we are introducing this service for users who prefer to access NED data directly within their code. We are going to provide a NED server, which will be running on a dedicated NED machine, and a client library, which can be used to write client programs to retrieve NED data. We also provide several simple client programs to serve as samples for those who want to write their own client programs. A typical usage of this client/server system would be for the program to establish a connection to the NED server (Section A below), issue a number of search requests (Section B), manipulate the data returned, free up the space when it is not needed (Section C), then disconnect. The memo describes the functions in the client library that client programmer need to call to write a client program. A. connect/disconnect connect to and disconnect from NED server int ned_connect() ned_disconnect() ned_connect() requests and establish a connection from client to server. ned_disconnect() disconnets the client from server. RETURN VALUES: 0: connection is established. -1: connection is not established, check ned_errno for reasons. NE_HOST can't get hostent from the name NE_SERVICE can't get the port number for the service NE_PROTO can't convert tcp to protocol number NE_SOCK can't get a socket allocated NE_CONNECT can't connect to server B. NED search functions: We decide to start by providing a limited subset of the NED functions in the client code. The following five functions provide different ways to retrieve NED data about objects. Upon successful return from the function, basic NED data will be in the data structure described below, and users can navigate through the data structure to get the data they are interested in. B.1) Name resolver: For a given object name, this will return all the other names or Cross Identifications and the corresponding object types attached to the names for the object in the NED database. int ned_name_resolver(char *objname, int *no_names, CrossID **cp) input: objname: object name output: no_names: number of names found cp: point to a pointer of data structure CrossID typedef struct _crossid { char objname[31]; char objtype[7]; } CrossID; RETURN VALUE: 0: the objname has been recognized by the name interpreter, and there is a number (no_names) of cross identifications in NED database for the object the objname refers to, and they are stored in an array of type CrossID pointed to by cp. -1:check ned_errno to determine what happened NE_QUERY: query can't be sent to server NE_NAME: object name can't be recognized by name interpreter EGRET NE_NOSPACE: Can't allocate memory space for data NE_AMBN: input object name is ambiguous, no_names is the number of possible selections supplied by EGRET; they are stored in an array of type CrossID pointed to by cp. NE_NOBJ: the format and nomanclature for the object name provided are recongnized by the NED name interpreter (EGRET), but there is no object in NED database for the given object name The following 4 search functions will return, for the given input, all the objects found; for each object found, there will be a list of cross IDs and other basic data. B.2) Objects search by object name For a given object name, it will return all the objects found in the NED database with matching names. int ned_obj_byname(char *objname, int *obj_no, ObjInfo **op, CrossID **cp) input: objname: object name output: obj_no: number of objects found op: point to pointer of structure ObjInfo cp: point to poniter of structure CrossID B.3) Objects search near object name For a given object name and a search radius, it will return all the objects found in the NED database within the cone centered on the object and defined by the search radius. int ned_obj_nearname(char *objname, double radius, int *obj_no, ObjInfo **op, CrossID **cp) input: objname: object name radius: search radius in arcmin (up to 300 arcmins) output: obj_no: number of objects found op: point to pointer of structure ObjInfo cp: point to poniter of structure CrossID B.4) Objects search near position For a given position(ra-j2000, dec-j2000) and a search radius, it will return all the objects found in the NED database within the cone centered on the position and defined by the radius. int ned_obj_nearposn(double ra, double dec, double radius, int *obj_no, ObjInfo **op) input: ra: Right Ascension in J2000 decimal degree dec: Declination in J2000 decimal degree radius: search radius in arcmin (up to 300 arcmin) output: obj_no: number of objects found op: point to pointer of structure ObjInfo B.5) Objects Search by IAU format For a given IAU-format name, interpretation style and equinox, return the search position, radius and all the objects found in the NED database within the cone centered on the position and defined by the search radius. This function converts the IAU-format name (in accordance with the style) into a search center and radius, then executes a search near position on the result of the conversion. int ned_obj_iau(char *iauformat, char style, char *equinox, char *cra, char *cdec, double *radius, int *obj_no, ObjInfo **op) input: iauformat: IAU format name style: how to interprete the iauformat, 'L' (liberal) or 'S'(strict), case insensitive default: 'S' equinox: "Jnnnn.n" or "Bnnnn.n", case insensitive, nnnn.n is between 1500.0 and 2500.0 default: B1950.0 it is client programer's responsibility to make sure the style and equinox are what you wanted. Otherwise the default will be taken. output: cra: RA in sexigesmal format cdec: DEC in sexigesmal format radius: search radius According to the style, the IAU-format is converted into a position search. obj_no: number of objects found. op: point to pointer of structure ObjInfo. Each of the 4 different object searches will return the information in an array of the data type ObjInfo (defined below). typedef struct _more_data { char data_typec[61]; /* data type code to describe the data */ char data[101]; _more_data *next; } MoreData; typedef struct _obj_info { int no_crossid; /* number of crossids for the object */ CrossID *cp; int no_note; /* number of notes */ int no_photom; /* number of photometric data points */ int no_ref; /* number of references */ double dist; /* distance to the search center */ char objtype[7]; double ra; /* J2000 */ double dec; double unc_maj; double unc_min; double unc_ang; char refcode[20]; MoreData *mdp; } ObjInfo; With the structure MoreData in the definition of ObjInfo, we will have the flexibility of providing new data in the future without changing any code (ideally and hopefully). With any new data we have, all we need to do is to modify the server part to send the new data to the client, and provide users with the data type code and explanation about it. With the "Application protocol between server and client" design (it is described separately), as long as users use the functions we provide to retrieve the data, the new data will be put into the structure MoreData for our client users. Users can modify their client program to make use of the new data, or they can still use the old program with the new server. RETURN VALUE: -1:check ned_errno to determine what happened NE_QUERY: query can't be sent to server NE_NOSPACE: Can't allocate memory space for data NE_NAME: object name can't be recognized by name interpreter EGRET NE_AMBN: input object name is ambiguous, no_names is the number of selections supplied by EGRET, they are stored in an array of type CrossID pointed to by cp. NE_RA: ra has unacceptable value, e.g out of [0, 360] NE_DEC: dec has unacceptable value, e.g out of [-90, 90] NE_RADIUS: radius is out of range, e.g out of [0, 300] NE_JB: Letter other than J or B is in equinox specification NE_EPOCH: Epoch in equinox is out of range, e.g out of [1500, 2500] NE_IAU: iauformat is in wrong format NE_NOBJ: there is no object in the NED database for the given object name 0: There are no_obj found for specified objname(position, iauformat), and they are stored in an array pointed to by op. B.6) Expand the reference code For a given 19-digit reference code, the function returns the detailed information about the it. int ned_ex_refcode(char *refcode, struct reference *full_ref); input: refcode, the NED statndard 19 digit code output: full_ref, the full reference for the refcode. in the structure struct reference{ char refcode[20]; char pub_name[81]; int year; char vol[21]; char page[21]; char title1[81]; char title2[81]; char author1[81]; char author2[81]; }; RETURN: -1: check ned_errno to determine what happened NE_QUERY: query can't be sent to server NE_NOSPACE: Can't allocate memory space for data NE_NOREFC: there is no detailed reference in the NED database for the given refcode. If you get the refcode from NED, please let us know this. NE_EREFC: refcode is not a 19-digit code 0: query is done successfully. B.7) Bibligraphic search for a given object For a given object name, it will return all the references for it in NED database. int ned_ref(char *objname, int begin_year, int end_year, int *no, CrossID **cp, NedRef **refp); input: objname: the name of the object for which you want to get all the references in NED. begin_year, end_year: the beginning and endding year (inclusive) during which the references published ouput: no: number of references returned, cp: point to pointer of struct CrossID, refp: point to pointer of structure reference RETURN: -1: check ned_errno for what happened NE_QUERY: query can't be sent to server NE_NOSPACE: Can't allocate memory space for data NE_NAME: object name can't be recognized by name interpreter EGRET NE_AMBN: input object name is ambiguous, no_names is the number of selections supplied by EGRET, they are stored in an array of type CrossID pointed to by cp. NE_NOBJ: there is no object in the NED database for the given object name NE_NOREF: There is no reference in NED for the given object C. NED free space functions: It is client programer's responsibility to free the space allocated for the results of earlier called search functions. It is a better practice to free the space once you are sure you don't need it any more. We provide two functions to free space. 1) ned_free_objp(ObjInfo *objp, int no_obj) It frees the space for object. Because the size of the space is determined by the number of objects found, the number of objects (no_obj) is needed to free space for those objects. 2) ned_free_cp( CrossID *cp) It frees the space for cross identifications. 3) ned_free_refp(NedRef *refp, int no_ref); It frees the space allocated for the results of reference search for a given object. Because the size of teh space is determined by the number of references found, the number of references (no_ref) is needed. D. data type codes definition The data fields that are available for all objects are placed in the correponding elements in the structure ObjInfo. Other data fields that are not available for all the objects can be found in the chain link of structure MoreData, we give the data type codes and their meanings below. These are the data type codes that are the same for all object types, and may be available for all objects: BH_EXTIN : Burstein Heilius extinction (B mag) Z : redshift of object Z_UNC : uncertainty for redshift Z_REFCODE : 19-degit reference code for redshift HRV : Heliocentric radial velocity in km/s HRV_UNC : uncertainty for Heliocentric radial velocity in km/s HRV_REFCODE : 19-digit code for Heliocentric radial velocity ESSEN_NOTE : essential notes The contents of the ObjInfo structure vary with the type of object under examination, so these contents are different for galaxy clusters and quasers for instance. Here are the data type code lists for differnt object types: 1) Galaxies (G) MORPH 1: Morphology MAG 2: A magnitude in the visible range, on any scale as available DIAM1 3: Major axis diameter in arcmin DIAM2 4: Minor axis diameter in arcmin 2) Small Associations of Galaxies (GPair, GTrpl, GGroup) MORPH 1: Morphology MAG 2: A magnitude in the visible range (of brightest, or of all) SIZE 3: Size in arcmin POP 4: Population count 3) Clusters of Galaxies (GClstr) MORPH 1: Descriptive morphology and [system of classification] MAG 2: A magnitude in the visible range and rank of Nth brightest SIZE 3: Size in arcmin POP 4: Population count or [Richness class] DIST_C 5: distance class (present only when redshift/velocity not available) 4) Quasars (QSO) DESC 1: Description or classification MAG 2: A magnitude in the visible range 5) Absorption Line Systems (AbLS) DESC 1: Description 6) Radio Sources (RadioS) MORPH 1: Morphology LFLUX 2: Log (flux density S in mJy) FREQ 3: Frequency at which S is given SIZE 4: Size indication in arcmin SPEC 5: Spectral index, on the definition S=A*Freq^Index^ 7) Infra-red Sources (IrS) ORIG 1: Origin of source or of data for this source FLUX1 2: Flux density or infrared magnitude WAVE1 3: Wavelength at which COLUMN 2 is given FLUX2 4: Flux density or infrared magnitude WAVE2 5: Wavelength at which COLUMN 4 is given 8) Emission Line Sources (EmLS) MAG 2: A magnitude in the visible range 9) Ultra-violet Excess Sources (UvES) MAG 2: A magnitude in the visible range 11) X-ray Sources (XrayS) 12) Supernovae (SN) SN_TYPE 1: Type and other information MAG 2: Maximum magnitude SYSTEM 3: Photometric system at which COLUMN 2 is given DATE 4: Date of maximum light 13) Gamma-ray Sources (GammaS) 14) Visual Sources(VisS) MAG 2: Magnitude