RetrieveOne

Description

Retrieves one data row to the DataWindow, DataWindowChild, or DataStore from the RESTFul Web service.

If the data received from the RESTful web service is compressed as gzip, it will be automatically decompressed. Only gzip compression format is supported at this moment. The developer can use the SetRequestHeader function to set the Accept-Encoding header to allow only the gzip compression format.

It is not recommended to use this method to process large data (20 MB or 100,000 data rows can be considered as large data based on our tests).

Applies to

RestClient object

Syntax

objectname.RetrieveOne (DWControl dwObject, string urlName {,string data})

Argument

Description

objectname

A reference to the RestClient object.

dwObject

The name of the DataWindow control, DataStore, or child DataWindow.

urlName

A string whose value is the URL.

data (optional)

A string specifying the data to send to the server. If this argument is not specified, the RetrieveOne function sends the request to the server with "GET" method, otherwise with "POST".


Usage

For the RetrieveOne function, the JSON string returned from the RESTFul Web service APIs can be an array in the two-level plain JSON format (see Plain JSON: two-level structure in Application Techniques for details) or a JSON object; for the Retrieve function, the JSON string returned from the RESTFul Web service APIs must be an array in the two-level plain JSON format (see Plain JSON: two-level structure in Application Techniques for details).

If the retrieved data is a JSON object that contains one single row, the JSON object will be imported to DataWindow as one row; if the retrieved data is a JSON array that contains multiple rows, only the first element of the JSON array will be imported to DataWindow.

The RetrieveOne function is not supported in DataWindow/DataWindowChild/DataStore with the following presentation styles: Composite, Crosstab, OLE 2.0, and RichText.

Although the RetrieveOne function is not supported in the Composite DataWindow, you can call GetChild function to get the child DataWindow from the Composite DataWindow, and then call the RetrieveOne function to retrieve the data into the child DataWindow.

Return value

Long.

Returns values as follows. If any argument's value is null, the method returns null.

>=0 -- Returns the number of rows if it succeeds

-1 -- General error

-2 -- Invalid URL

-3 -- Cannot connect to the Internet

-4 -- Timed out

-7 -- Failed to decompress data

-10 -- The token is invalid or has expired

-15 -- Unsupported character sets

Example 1

The following code example shows the usage of RetrieveOne without the data argument.

RestClient lrc_P024
Long ll_P024_DepartmentID
Integer li_p024_RetrieveOneReturn

lrc_P024 = Create RestClient
lrc_P024.SetRequestHeaders( "Content-Type:application/json;charset=UTF-8~r~nAccept-Encoding:gzip" )

ll_P024_DepartmentID = 100

li_p024_RetrieveOneReturn=lrc_P024.RetrieveOne(dw_Data,"https://demo.appeon.com/PB/webapi_client/api/department/retrieveone/"+String(ll_P024_DepartmentID))
If li_p024_RetrieveOneReturn <> 1 Then 
//Checks if any error information
Else
 If lrc_P024.GetResponseStatusCode() <> 200 Then
  //Processes according to the exception information
 End If
End If

Example 2

The following code example shows the usage of RetrieveOne with the data argument.

RestClient lrc_P024
Integer li_p024_RetrieveOneReturn

lrc_P024 = Create RestClient
lrc_P024.SetRequestHeaders( "Content-Type:application/json;charset=UTF-8~r~nAccept-Encoding:gzip" )
 
li_p024_RetrieveOneReturn=lrc_P024.RetrieveOne(dw_Data, "https://demo.appeon.com/PB/webapi_client/department/retrievebyid", "500")
If li_p024_RetrieveOneReturn <> 1 Then 
//Checks if any error information
Else
 If lrc_P024.GetResponseStatusCode() <> 200 Then
  //Processes according to the exception information
 End If
End If

See also

Retrieve