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 supported 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
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.
The RetrieveOne function is not supported for Report controls, TableBlob controls, OLE Database Blob controls, and InkPicture controls in DataWindow objects.
The RetrieveOne function is not supported for dynamically created or modified DataWindows.
AutoRetrieve for DropDownDataWindow is unsupported.
The RetrieveOne function will not pass the retrieval arguments used in computed fields and DataWindow expressions.
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.
-18 -- Certification revocation checking has been enabled, but the revocation check failed to verify whether a certificate has been revoked. The server used to check for revocation might be unreachable.
-19 -- SSL certificate is invalid.
-20 -- SSL certificate was revoked.
-21 -- The function is unfamiliar with the Certificate Authority that generated the server's certificate.
-22 -- SSL certificate common name (host name field) is incorrect, for example, if you entered www.appeon.com and the common name on the certificate says www.devmagic.com.
-23 -- SSL certificate date that was received from the server is bad. The certificate has expired.
-24 -- The certificate was not issued for the server authentication purpose.
-25 -- The application experienced an internal error loading the SSL libraries.
-26 -- More than one type of errors when validating the server certificate.
-27 -- The server requires the client to provide a certificate.
-28 -- The client certificate has not been assigned with a private key.
-29 -- The client certificate has no accessible private key.
-30 -- Cannot find the specified certificate.
-31 -- Failed to read the certificate.
-32 -- The certificate password is wrong.
-33 -- TLS 1.3 error. The client does not support TLS 1.3.
-34 -- Response is unrecognizable. Normally this is because the HTTP version does not match with the version required by the server.
-35 -- TLS 1.3 error. The server does not support TLS 1.3.
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
