ImportJson

Description

Inserts data from a JSON string into a DataWindow control, DataStore object, or DataWindowChild object according to the index of the JSON item.

The JSON string must be in the format described in the section called “Supported JSON formats” in Application Techniques.

ImportJson function will fail to import data properly, if the DataWindow is in query mode.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, and DataStore object, except for those with the Composite, Crosstab, OLE 2.0, or RichText presentation styles.


Syntax

PowerBuilder

long dwcontrol.ImportJson( string json {, string error} {, DWBuffer dwbuffer {, long startrow {, long endrow {, long startcolumn {, long endcolumn {, long dwstartcolumn } } } } } } )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or DataWindowChild.

json

A string specifying the JSON data. The JSON string must comply with the the section called “Supported JSON formats” in Application Techniques.

error (optional)

A variable into which the returned warning or error message will be placed.

When there are a large amount of error messages, the error information will only display the total number of errors, and the detailed message of the first 10 errors.

The import warning caused by data type mismatch will not affect the return value of ImportJson; although the data of the mismatched columns will not be imported, the rest columns (even only one column) that are matched will be imported successfully; and that row will be regarded as a successful import and counted into the return value.

The import error caused by DW presentation style mismatch, invalid arguments, startrow value greater than the number of rows, etc. will be regarded as a failure, and represented by a negative return value of ImportJson, instead of being placed into this variable. See the Return Value section for more.

Most of the messages placed into this variable are warnings (such as data type mismatch) rather than errors. Developers can adjust the JSON data according to the message or simply ignore the message if the problematic column is not critical and the corresponding DataWindow column can be left blank.

dwbuffer (optional)

A value of the dwBuffer enumerated datatype identifying the DataWindow buffer from which you want to import the data. For a list of valid values, see DWBuffer.

For plain JSON: If not specified, imports the JSON data to the Primary! buffer. If specified, imports the JSON data to the specified buffer.

For DataWindow JSON: If not specified, imports data from all of the buffers from the JSON string to the corresponding buffers and, if any, imports the data for DataWindowChild. If specified, imports data from the specified buffer from the JSON string to the corresponding buffer.

startrow (optional)

The number of the first detail object in the JSON array that you want to import. The default is 1. If it is 0 or negative, 1 is used.

endrow (optional)

The number of the last detail object in the JSON array that you want to import. The default is the rest of the objects. If it is 0 or negative, it indicates the rest of rows.

startcolumn (optional)

The number of the first key value in the JSON object that you want to import. The default is 1. If it is 0 or negative, 1 is used.

endcolumn (optional)

The number of the last key value in the JSON object that you want to import. The default is the rest of the key values. If it is 0 or negative, it indicates the rest of columns.

dwstartcolumn (optional)

The number of the first column in the DataWindow control, DataStore or DataWindowChild that should receive data. The default is 1. If it is 0 or negative, 1 is used.


Return value

Long. Returns the number of rows that were imported if it succeeds and one of the following negative integers if an error occurs. The return value will count the rows imported into the primary, filter, and delete buffers, but not the rows imported into DataWindowChild.

0 -- When all of the data in the JSON string is null or the JSON string only contains data for DataWindowChild.

-1 -- General error.

-2 -- No row is supplied or the startrow value supplied is greater than the number of rows in the JSON data.

-3 -- Invalid argument.

-4 -- Invalid JSON.

-5 -- JSON format error.

-6 -- Unsupported DataWindow presentation style for import.

-7 -- Error resolving DataWindow nesting.

-8 -- Unsupported mapping-method value.

The method returns null if any of the following:

  • any argument's value is null

  • the DataWindow object (dataobject) is invalid

Usage

The ImportJson function imports data according to the index of the JSON item when the data type of the JSON value matches with that of the DataWindow column.

There is no forced conversion between strings and numbers. For example, the number 123 in JSON string will not be imported into the DataWindow column of char(10) type. For such case, a data type mismatch warning will be recorded in the error argument.

A boolean value (true or false) will be converted to 0 or 1 when imported from the JSON string to the DataWindow; however, 0 or 1 will not be converted to a boolean value (true or false) when exported from the DataWindow to the JSON string.

If the string length in JSON is larger than the string length in DataWindow, the string will be truncated when imported into the DataWindow. For example, JSON string [{"name":"TestForTrancate"}] is imported as "Test" when the data type of DataWindow column "name" is char(4).

When the number value is imported from the JSON string to the DataWindow column of number data type (with uncertain precision), the value will have uncertain decimals, for example, 6.78 becomes 6.78000020980835 after imported from the JSON string to the DataWindow.

Examples

This example gets data at plain JSON format from the server and imports into the primary buffer of the DataWindow:

int li_rc
long ll_RowCount
string ls_PlainJson
HttpClient lnv_HttpClient

lnv_HttpClient = create HttpClient

// send request using GET method
li_rc=lnv_HttpClient.SendRequest("GET","http://demo.appeon.com/PB/webapi_client/employee/102")
// obtain the response data
if li_rc = 1 and lnv_HttpClient.GetResponseStatusCode() = 200 then
  lnv_HttpClient.GetResponseBody(ls_PlainJson)
  ll_RowCount = dw_1.ImportJson(ls_PlainJson)
end if

This example imports data (and state) from a DataWindow JSON string into the DataWindowChild and all of the buffers of the DataWindow:

long ll_RowCount
string ls_DWJson, ls_Error

//DataWindow JSON
ls_DWJson = … 
ll_RowCount = dw_1.ImportJson(ls_DWJson, ls_Error)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else

 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

This example imports data (and state) from a DataWindow JSON string into the primary buffer of the DataWindow:

long ll_RowCount
string ls_DWJson

//DataWindow JSON
ls_DWJson = …
ll_RowCount = dw_1.ImportJson(ls_DWJson, Primary!)

This example imports data from a plain JSON string in rows 2 through the end into the primary buffer of the DataWindow:

long ll_RowCount
string ls_PlainJson

//Plain JSON
ls_PlainJson = '[{"department_id":100,"department_name":"Sales"}, &
 {"department_id":200,"department_name":"Finance"},{"department_id":300,"department_name":"Marketing"}]'

ll_RowCount = dw_1.ImportJson(ls_PlainJson, Primary!, 2)

This example imports data from a plain JSON string in rows 1 through 3 into the filter buffer of the DataWindow:

long ll_RowCount
string ls_PlainJson

//Plain JSON
ls_PlainJson = '[{"emp_id":1,"emp_fname":"Fran","emp_lname":"Whitney"}, &
          {"emp_id":2,"emp_fname":"Matthew","emp_lname":"Cobb"}, &
          {"emp_id":3,"emp_fname":"Philip","emp_lname":"Chin"}, &
          {"emp_id":4,"emp_fname":"Julie","emp_lname":"Jordan"}, &
          {"emp_id":5,"emp_fname":"Robert","emp_lname":"Breault"}]'       
ll_RowCount = dw_1.ImportJson(ls_PlainJson, Filter!, 1, 3)

This example imports data from a plain JSON string in rows 1 through 3 and in columns 2 through the end into the primary buffer of the DataWindow:

long ll_RowCount
string ls_PlainJson

//Plain JSON
ls_PlainJson = '[{"emp_id":1,"emp_fname":"Fran","emp_lname":"Whitney"}, &
          {"emp_id":2,"emp_fname":"Matthew","emp_lname":"Cobb"}, &
          {"emp_id":3,"emp_fname":"Philip","emp_lname":"Chin"}, &
          {"emp_id":4,"emp_fname":"Julie","emp_lname":"Jordan"}, &
          {"emp_id":5,"emp_fname":"Robert","emp_lname":"Breault"}]' 
ll_RowCount = dw_1.ImportJson(ls_PlainJson, Primary!, 1, 3, 2)

This example imports data (and state) from a DataWindow JSON string in rows 1 through 10 and in columns 1 through 5 into the primary buffer of the DataWindow:

long ll_RowCount
string ls_DWJson

//DataWindow JSON
ls_DWJson = … 
ll_RowCount = dw_1.ImportJson(ls_DWJson, Primary!, 1, 10, 1, 5)

This example imports data from a plain JSON string in rows 1 through 3 and in columns 2 through 5 into the primary buffer of the DataWindow beginning in column 3:

long ll_RowCount
string ls_PlainJson

//Plain JSON
ls_PlainJson = '[{"emp_id":1,"emp_fname":"Fran","emp_lname":"Whitney", &
       "street":"9 East Washington Street","city":"Cornwall"}, &
     {"emp_id":2,"emp_fname":"Matthew","emp_lname":"Cobb", &
       "street":"7 Pleasant Street","city":"Grimsby"}, &
     {"emp_id":3,"emp_fname":"Philip","emp_lname":"Chin", &
       "street":"539 Pond Street","city":"Oakville"}, &
     {"emp_id":4,"emp_fname":"Julie","emp_lname":"Jordan", &
       "street":"1244 Great Plain Avenue","city":"Woodbridge"}, &
     {"emp_id":5,"emp_fname":"Robert","emp_lname":"Breault", &
       "street":"358 Cherry Street","city":"Milton"}]'
ll_RowCount = dw_1.ImportJson(ls_PlainJson, Primary!, 1, 3, 2, 5, 3)

This example imports data (and state) from a DataWindow JSON string into the primary buffer of the DataWindow:

long ll_RowCount
string ls_DWJson, ls_Error

//DataWindow JSON
ls_DWJson = …
ll_RowCount = dw_1.ImportJson(ls_DWJson, ls_Error, Primary!)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else
 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

This example imports data from a plain JSON string in rows 2 through the end into the delete buffer of the DataWindow:

long ll_RowCount
string ls_PlainJson, ls_Error

//Plain JSON
ls_PlainJson = '[{"emp_id":1,"emp_fname":"Fran","emp_lname":"Whitney"}, &
          {"emp_id":2,"emp_fname":"Matthew","emp_lname":"Cobb"}, &
          {"emp_id":3,"emp_fname":"Philip","emp_lname":"Chin"}, &
          {"emp_id":4,"emp_fname":"Julie","emp_lname":"Jordan"}, &
          {"emp_id":5,"emp_fname":"Robert","emp_lname":"Breault"}]'  
ll_RowCount = dw_1.ImportJson(ls_PlainJson, ls_Error, Delete!, 2)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else
 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

This example imports data (and state) from a DataWindow JSON string in rows 1 through 10 into the primary buffer of the DataWindow:

long ll_RowCount
string ls_DWJson, ls_Error

//DataWindow JSON
ls_DWJson = … 
ll_RowCount = dw_1.ImportJson(ls_DWJson, ls_Error, Primary!, 1, 10)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else
 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

This example imports data (and state) from the DataWindow JSON string in rows 1 through 10 and in columns 2 through the end into the primary buffer of the DataWindow:

long ll_RowCount
string ls_DWJson, ls_Error

//DataWindow JSON
ls_DWJson = …
ll_RowCount = dw_1.ImportJson(ls_DWJson, ls_Error, Primary!, 1, 10, 2)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else
 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

This example imports data (and state) from a DataWindow JSON string in rows 1 through 10 and in columns 2 through 5 into the primary buffer of the DataWindow:

long ll_RowCount
string ls_DWJson, ls_Error

//DataWindow JSON
ls_DWJson = … 
ll_RowCount = dw_1.ImportJson(ls_DWJson, ls_Error, Primary!, 1, 10, 2, 5)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else
 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

This example imports data (and state) from a DataWindow JSON string in rows 1 through 10 and in columns 2 through 5 into the primary buffer of the DataWindow beginning in column 2:

long ll_RowCount
string ls_DWJson, ls_Error

//DataWindow JSON
ls_DWJson = … 
ll_RowCount = dw_1.ImportJson(ls_DWJson, ls_Error, Primary!, 1, 10, 2, 5, 2)

//Checks if any error
IF isnull(ll_RowCount) Then
 Messagebox("Error", "The method returns null")
ElseIf ll_RowCount < 0 Then
 If len(ls_Error) > 0 Then
  Messagebox("Failed","Return Value: " + String(ll_RowCount) &
      + "~r~nWith error information:~r~n" + ls_Error)
 Else
  Messagebox("Failed","Return Value: "+String(ll_RowCount))
 End If
Else
 //Checks if any warning
 If len(ls_Error) > 0 Then
  MessageBox("Warning", "With warning information:~r~n" + ls_Error)
 Else
  MessageBox("Succeed", "Return Value: " + String(ll_RowCount) )
 End If
End If

See also

ImportJsonByKey

ExportJson