New or enhanced PowerBuilder objects

Enhanced RESTClient object

The following functions are added to the RESTClient object:

  • Submit can not only send data from the application client to the RESTful web service but also get the response body from the RESTful web service.

    The data to be submitted may be from either a DataWindow, DataStore, DataWindowChild, or JSONPackage. You can specify one or multiple DataWindow buffers, and also the range in the DataWindow, from which to submit the data. The request supports OAuth 2.0 authorization.

    objectname.Submit(string urlName, ref string response, DWControl dwObject{, boolean format})
    
    objectname.Submit(string urlName, ref string response, DWControl dwObject {,DWBuffer dwbuffer}, boolean changedonly, boolean format)
    objectname.Submit(string urlName, ref string response, DWControl dwObject, boolean primarydata, boolean filterdata, boolean deletedata, boolean dwcdata {, boolean format})
    objectname.Submit(string urlName, ref string response, DWControl dwObject, DWBuffer dwbuffer{,long startrow{, long endrow{, long startcol{, long endcol}}}} {, boolean format})
    objectname.Submit(string urlName, ref string response, ref JsonPackage package)
  • SendDeleteRequest: Sends the HTTP DELETE request to the server and then gets the content of the server response.

    Previously only the HTTPClient object supports sending a request to the RESTful web service. Now you can directly send a request from the RESTClient object, and the request supports OAuth 2.0 authorization.

    SendDeleteRequest(string urlName{, string data }, ref string response)
  • SendGetRequest: Sends the HTTP GET request to the server and then gets the content of the server response.

    SendGetRequest(string urlName, ref string response)
  • SendPatchRequest: Sends the HTTP PATCH request to the server and then gets the content of the server response.

    SendPatchRequest(string urlName, string data, ref string response)
  • SendPostRequest: Sends the HTTP POST request to the server and then gets the content of the server response.

    SendPostRequest(string urlName, string data, ref string response)
  • SendPutRequest: Sends the HTTP PUT request to the server and then gets the content of the server response.

    SendPutRequest(string urlName, string data, ref string response)
  • GetJWTToken: Gets the JWT token using the POST method.

    GetJWTToken (string urlName, string data, ref string token)
  • SetJWTToken: Sets the JWT token string to the HTTP request header which will be sent to the server.

    SetJWTToken(string jwtToken)
  • GetOAuthToken: Gets the OAuth 2.0 access token.

    GetOAuthToken (TokenRequest tokenRequest, ref string token)
  • SetOAuthToken: Sets the OAuth 2.0 token string to the HTTP request header which will be sent to the server.

    SetOAuthToken(string token)
  • RetrieveOne: Retrieves one data row to the DataWindow, DataWindowChild, or DataStore from the RESTFul Web service.

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

The following functions for the RESTClient object are modified:

  • Retrieve - Retrieves data 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. You can use the SetRequestHeader function to set the Accept-Encoding header to allow only the gzip compression format.

  • SetRequestHeader - Supports to add a request header or add/replace the value in the existing request header if the header already exists.

    SetRequestHeader ( string headerName, string headerValue{, Boolean replace } )

For more details about these functions, refer to the section called “RESTClient object” in Objects and Controls.

Enhanced HTTPClient object

The following functions for the HTTPClient object are enhanced:

  • SetRequestHeader: supports to add a request header or add/replace the value in the existing request header if the header already exists.

    SetRequestHeader ( string headerName, string headerValue{, Boolean replace } )
  • SendRequest: supports to encode the data with the charset which is specified by the user in the Content-Type request header, if charset is not specified, this function will encode the data in UTF-8 by default.

  • GetResponseBody: supports to encode the data with the charset which is specified by the user in the Content-Type request header; if charset is not specified, this function determines the encoding type based on the BOM header, and then converts the data into UNICODE.

For more details about these functions, refer to the section called “HTTPClient object” in Objects and Controls.

Enhanced JSONPackage object

The GetValue function of the JSONPackage object always returns the result in string, and the SetValue function only sets string-type values. Now there are more functions in the JSONPackage object for getting or setting values of various types.

  • GetValueBlob -- Gets the blob value of the key.

  • GetValueBoolean -- Gets the boolean value of the key.

  • GetValueDate -- Gets the date value of the key.

  • GetValueDateTime -- Gets the datetime value of the key.

  • GetValueNumber -- Gets the number value of the key.

  • GetValueString -- Gets the string value of the key.

  • GetValueTime -- Gets the time value of the key.

  • SetValueBlob -- Sets the blob value for a key.

  • SetValueBoolean -- Sets the boolean value for a key.

  • SetValueDate -- Sets the date value for a key.

  • SetValueDateTime -- Sets the datetime value for a key.

  • SetValueNumber -- Sets the number value for a key.

  • SetValueString -- Sets the string value for a key.

  • SetValueTime -- Sets the time value for a key.

You can now directly get values from the JSONPackage object into DataWindows, or set the key values in the JSONPackage object from DataWindows.

  • GetValueToDataWindow -- Gets the value of the key and inserts it into a DataWindow control, DataStore object, or DataWindowChild object.

  • SetValueByDataWindow -- Sets the value of the key using the data from a DataWindow control, DataStore object, or DataWindowChild object.

The JSONPackage object also provides the GetItemType function which works the same as the GetItemType function in the JSONParser object.

  • GetItemType -- Gets the type of item.

The SaveToFile and GetJsonBlob functions for JSONPackage (and JSONGenerator) are enhanced to specify the character encoding of the resulting blob.

  • SaveToFile

    SaveToFile ( FileName {, Encoding e} )
  • GetJsonBlob

    GetJsonBlob ( {Encoding e} )

For the newly-added or enhanced functions, see the section called “JSONPackage object” in Objects and Controls for more details.

The following new property is added to the JSONPackage object (also added to JSONParser):

  • ReturnsNullWhenError -- Specifies whether the getting value function returns a null value when error occurs.

    You can use this property to avoid throwing an exception in cases when a getting item function returns null.

    See the section called “ReturnsNullWhenError” in Objects and Controls for more details.

Enhanced JSONGenerator

The SaveToFile and GetJsonBlob functions for JSONGenerator (and JSONPackage) are enhanced to specify the character encoding of the resulting blob.

  • SaveToFile

    SaveToFile ( FileName {, Encoding e} )
  • GetJsonBlob

    GetJsonBlob ( {Encoding e} )

For more information, see the section called “SaveToFile” in PowerScript Reference and the section called “GetJsonBlob” in PowerScript Reference.

Enhanced JSONParser object

The following new function is added to the JSONParser object:

  • ContainsKey -- Checks if the key name exists.

    You can use this function to check whether certain key exists in a JSONParser object before executing other functions, such as GetItem.

    See the section called “ContainsKey” in PowerScript Reference for more details.

The following function is enhanced:

  • GetItemType -- Gets the type of item.

    It is now possible to specify the key of a child item, and directly get the type of the child item.

    See the section called “GetItemType” in PowerScript Reference for more details.

The following new property is added to the JSONParser object (also added to JSONPackage):

  • ReturnsNullWhenError -- Specifies whether the getting item function returns a null value when error occurs.

    You can use this property to avoid throwing an exception in cases when a getting item function returns null.

    See the section called “ReturnsNullWhenError” in Objects and Controls for more details.

New CompressorObject and ExtractorObject objects

Two new objects called CompressorObject and ExtractorObject are added to compress and decompress the folder or file(s), or the byte data stream. The supported compression formats include ZIP, 7ZIP, GZIP and TAR, and the ZIP and 7ZIP formats support AEM-256 encryption for password; the supported extraction formats include ZIP, 7ZIP, RAR, GZIP, TAR, LZMA, and LZMA86.

For more information about these objects, refer to the section called “CompressorObject object” in Objects and Controls and the section called “ExtractorObject object” in Objects and Controls.

For syntax of compressing files or data stream, refer to the section called “Compress” in PowerScript Reference; for syntax of extracting a compressed archive or data stream, refer to the section called “Extract” in PowerScript Reference; for code examples on compressing and extracting files with the HTTPClient object, the RESTClient object, or the OAuthClient object, refer to the section called “Compressing and extracting data” in Application Techniques.

New Import & Export JSON functions

The following functions are added to import/export a single data row between a JSON string and a DataWindow control, DataStore object, or DataWindowChild object:

  • ImportRowFromJson: Inserts a data row from a JSON string into a DataWindow control, DataStore object, or DataWindowChild object.

    ImportRowFromJson( string json, long row {, ref string error} {, DWBuffer dwbuffer})
  • ExportRowAsJson: Exports a data row from a DataWindow control, DataStore object, or DataWindowChild object to the JSON string.

    ExportRowAsJson (long row {, DWBuffer dwbuffer})

For more information, see the section called “ImportRowFromJson” in DataWindow Reference and the section called “ExportRowAsJson” in DataWindow Reference.

New JSON format

The SnapObjects ModelStore can exchange data with PowerBuilder DataWindow in JSON strings, so now the following JSON formats are supported:

  • Plain JSON (formerly called simple JSON)

  • DataWindow JSON (formerly called standard JSON)

  • ModelStore JSON (added in version 2019) Note: removed in version 2019 R2

For more about these formats, refer to the section called “Supported JSON formats” in Application Techniques.