LDRdataFindServer RPC Protocol Description

The LDRdataFindServer listens on a Globus GSI protected socket and so requires GSI authentication in order to invoke data finding operations. The server and the standard client LSCdataFind are both written in Python but one can write a client using any language that has GSI binding/libraries. In addtion to Python one can easily find libraries for C, Tcl, and Java.

We present a short tutorial on how to write a C client for LDRdataFindServer. We don't code up a fully functional client and just show how to bootstrap a client that can 'ping' the server.

RPC Coding Conventions

Method names, parameters and results are all encoded as null terminated strings. In the case where a list of results is returned the list is terminated with an empty string (i.e., the last two bytes are nulls, one to terminate the last string in the list, and a second null for the empty string).

Integer and floating point values are encoded as strings using the Python "%" operator, which is essentially equivalent to sprintf(3) in ANSI C.

RPC Method Invocation

All RPC method invocations begin with the method name, a null byte, and the parameters, which are null terminated strings.

All results begin with an integer result code (written as a null terminated string), and if successful (result code = 0) and if the method returns results, then the results follow the result code as null terminated strings.

If an error occurs, the result code will be non-zero, and an error message will follow the result code.

RPC Methods

Note: LFN is 'logical filename', PFN is 'physical filename' (usually a URL), and \0 represents the null byte. Examples are line broken only to make the web pages more readable--the line breaks are not real inside the string.

• PING

  method: PING
  description: ping a LDRdataFind server
  params: none (ignored if present)
  result: hello message (string)
  
  example RPC:     PING\0
  example result:  0\0LDRdataFindServer at dataserver.phys.uwm.edu is alive\0
  
  DISTINCT
  method: DISTINCT
  description: query to find distinct values for a metadata attribute
  params: attribute name
  result: list of distinct values for a metadata attribute
  
  example RPC:     DISTINCT\0frameType\0
  example result:  0\0RDS_R_L1\0RDS_R_L2\0RDS_R_L3\0SFT\0Allegro_L1\0
  
  note: There may be a server set limit to the number of returned entries.
  
  
  LFNPFN
  method: LFNPFN
  description: query to find PFNs associated with a particular LFN
  params: LFN
  result: list of PFNs
  
  example RPC:     LFNPFN\0H-RDS_R_L1-777777777-16.gwf\0
  example result:  0\0gsiftp://dataserver.phys.uwm.edu:15000/data/H-RDS_R_L1-777777777-16.gwf
                      \0file://dataserver.phys.uwm.edu/data/H-RDS_R_L1-777777777-16.gwf\0
  
  
  METALFN
  method: METALFN
  description: query for LFNs using metadata attributes
  params: 
          SQL WHERE-like query string on attributes 
          regular expression filter for LFNs found (NONE for no filtering)
          offset into list to return (0 if want all from begining) 
          number to return (-1 if want entire list)
          attribute to sort on (NONE)
          ascending sort (ASC) or descending sort (DESC) 
  result: list of LFNs
  
  example RPC:     METALFN\0instrument = 'H' AND frameType = 'RDS_R_L1' AND 
                          gpsEnd >= '777777777'\0NONE\00\0-1\0NONE\0ASC\0
  example result:  0\0\H-RDS_R_L1-777777777-16.gwf\0H-RDS_R_L1-777777793-16.gwf\0
  
  note: a second complete set of params if present will also be used and
        the results returned will be the simple UNION of the two sets
        found 
       
  
  
  METAPFN
  method: METAPFN
  description: query for PFNs using metadata attributes
  params: 
          SQL WHERE-like query string on attributes
          regular expression filter for PFNs found (NONE for no filtering)
          offset into list to return (0 if want all from begining) 
          number to return (-1 if want entire list)
          attribute to sort on (NONE)
          ascending sort (ASC) or descending sort (DESC)
  result: list of PFNs
  
  example RPC:     METALFN\0instrument = 'H' AND frameType = 'RDS_R_L1' AND 
                     gpsEnd >= '777777777'\0\NONE\010\02\0gpsStart\0DESC\0
  example result:  0\0gsiftp://dataserver.phys.uwm.edu:15000/data/H-RDS_R_L1-777777777-16.gwf\0
                     file://dataserver.phys.uwm.edu/data/H-RDS_R_L1-777777777-16.gwf\0
  
  note: see note for METALFN regarding second set of params
  
  
  RELFN
  method: RELFN
  description: query for LFNs using regular expression
  params: regular expression query string
          offset into list to return (0 if want all from begining) 
          number to return (-1 if want entire list)
          attribute to sort on (NONE)
          ascending sort (ASC) or descending sort (DESC)
  result: list of LFNs
  
  example RPC:     RELFN\0H-RDS_R_L.-77777....-16\.gwf\00\0-1\0NONE\0DESC\0
  example result:  0\0H-RDS_R_L1-777777777-16.gwf\0H-RDS_R_L1-777777793-16.gwf\0
  
  note: see note for METALFN regarding second set of params
  
  
  REPFN
  method: REPFN
  description: query for PFNs using regular expression
  params: regular expression query string
          offset into list to return (0 if want all from begining) 
          number to return (-1 if want entire list)
          attribute to sort on (NONE)
          ascending sort (ASC) or descending sort (DESC)
          number (optional, but required if offset present)
  result: list of PFNs
  
  example RPC:     REPFN\0file://dataserver\.phys\.uwm\.edu/data/H-RDS_R_L.*gwf\00\0-1\0NONE\0ASC\0
  example result:  0\0file://dataserver.phys.uwm.edu/data/H-RDS_R_L1-777777777-16.gwf\0
                     file://dataserver.phys.uwm.edu/data/H-RDS_R_L2-777777777-16.gwf\0
  
  note: see note for METALFN regarding second set of params