Examples

creating arrays

The following code show the ab-initio creation of a nested array with objects and a member inside an array. The JSON representation after each step is written after the Igor Pro function or operation.

JSONXOP_New
Variable jsonID = V_Value
JSONXOP_AddTree/T=(JSON_ARRAY) jsonID, "/array"

{
  "array": []
}

JSONXOP_AddValue/OBJ=2 jsonID, "/array"

{
  "array": [
    {},
    {}
  ]
}

JSONXOP_AddValue/V=0 jsonID, "/array/0/name"

{
  "array": [
    {
      "name": 0
    },
    {}
  ]
}

JSONXOP_AddValue/O/N jsonID, "/array/0"

{
  "array": [
    null,
    {}
  ]
}

JSONXOP_Remove jsonID, "/array/0"

{
  "array": [
    {}
  ]
}

RFC6901 example

Completeness of the API is demonstrated with the following JSON object that is created from scratch in Igor Pro.

target JSON representation

{
  "Image": {
    "Width": 800,
    "Height": 600,
    "Title": "View from 15th Floor",
    "Thumbnail": {
      "Url": "http://www.example.com/image/481989943",
      "Height": 125,
      "Width": 100
    },
    "Animated": false,
    "IDs": [
      116,
      943,
      234,
      38793
    ]
  }
}

Igor Pro code to produce the specified target.

Variable jsonID
JSONXOP_New
jsonID = V_Value
JSONXOP_AddTree/T=(JSON_OBJECT) jsonID, "Image"
JSONXOP_AddValue/I=800 jsonID, "/Image/Width"
JSONXOP_AddValue/I=600 jsonID, "/Image/Height"
JSONXOP_AddValue/T="View from 15th Floor" jsonID, "/Image/Title"
JSONXOP_AddTree/T=(JSON_OBJECT) jsonID, "/Image/Thumbnail"
JSONXOP_AddValue/T="http://www.example.com/image/481989943" jsonID, "/Image/Thumbnail/Url"
JSONXOP_AddValue/I=125 jsonID, "/Image/Thumbnail/Height"
JSONXOP_AddValue/I=100 jsonID, "/Image/Thumbnail/Width"
JSONXOP_AddValue/B=0 jsonID, "/Image/Thumbnail/Animated"
Make/U/I/N=4/FREE array = {116, 943, 234, 38793}
JSONXOP_AddValue/WAVE=array jsonID, "/Image/IDs"
JSONXOP_Release jsonID

Andor Camera Suite

The following example shows how to load custom dll functions in Igor Pro. The example sets Parameters in an Andor Camera using the Solis SDK dll. For more information on FCALL_CallFunction please contact support@byte-physics.de.

Usage in the Call Arbitrary Function XOP

#pragma TextEncoding="UTF-8"
#pragma rtGlobals=3 // Use modern global access method and strict wave access.

StrConstant AndorPackagePath = "root:Packages:Andor"
StrConstant LibAndorPath     = "C:Program Files:Andor SOLIS:Drivers"
StrConstant LibAndor         = "atmcd64d"

Constant GENERIC_ERROR      = 1
Constant ERROR_EXTRACTJSON  = 2
Constant ERROR_CALLFUNCTION = 3

// wrapper for
// unsigned int WINAPI SetExposureTime(float time)
//
// @see GetAcquisitionTimings
//
// @return errorCode
//         DRV_SUCCESS         Exposure time accepted.
//         DRV_NOT_INITIALIZED System not initialized.
//         DRV_ACQUIRING       Acquisition in progress.
//         DRV_P1INVALID       Exposure Time invalid
Function SetExposureTime(variable exposure)

	string ParameterIn, ParameterOut = ""
	variable errorCode, jsonID

	JSONXOP_New
	jsonID = V_Value
	JSONXOP_AddValue/I=1 jsonID, "/version"
	JSONXOP_AddTree/T=(JSON_ARRAY) jsonID, "/Parameter"
	JSONXOP_AddValue/OBJ=1 jsonID, "/Parameter"
	JSONXOP_AddValue/V=(exposure) jsonID, "/Parameter/0/value"
	JSONXOP_AddValue/T="FLOAT" jsonID, "/Parameter/0/type"
	JSONXOP_AddTree/T=(JSON_OBJECT) jsonID, "/result"
	JSONXOP_AddValue/T="UINT32" jsonID, "/result/type"
	JSONXOP_Dump jsonID
	ParameterIn = S_Value
	JSONXOP_Release jsonID

	errorCode = CallFunctionAndor("SetExposureTime", ParameterIn, ParameterOut)
	return errorCode
End

// wrapper for
// unsigned int WINAPI GetAcquiredData(at_32* arr, unsigned long size)
//
// @see GetAcquiredData16
// @see GetAcquiredFloatData
//
// @return errorCode
//         DRV_SUCCESS         Data copied.
//         DRV_NOT_INITIALIZED System not initialized.
//         DRV_ACQUIRING       Acquisition in progress.
//         DRV_ERROR_ACK       Unable to communicate with card.
//         DRV_P1INVALID       Invalid pointer (i.e. NULL).
//         DRV_P2INVALID       Array size is incorrect.
//         DRV_NO_NEW_DATA     No acquisition has taken place
Function GetAcquiredData(WAVE wv)

	variable errorCode, jsonID
	string ParameterIn
	string ParameterOut = ""

	if(WaveType(wv, 2) != 1 || WaveType(wv, 1) != 1)
		return GENERIC_ERROR
	endif

	JSONXOP_New
	jsonID = V_Value
	JSONXOP_AddValue/I=1 jsonID, "/version"
	JSONXOP_AddTree/T=(JSON_ARRAY) jsonID, "/Parameter"
	JSONXOP_AddValue/OBJ=2 jsonID, "/Parameter"
	JSONXOP_AddValue/T=(GetWavesDataFolder(wv, 2)) jsonID, "/Parameter/0/value"
	JSONXOP_AddValue/T="WAVEREF" jsonID, "/Parameter/0/type"
	JSONXOP_AddValue/I=(numpnts(wv)) jsonID, "/Parameter/1/value"
	JSONXOP_AddValue/T="INT32" jsonID, "/Parameter/1/type"
	JSONXOP_AddTree/T=(JSON_OBJECT) jsonID, "/result"
	JSONXOP_AddValue/T="UINT32" jsonID, "/result/type"
	JSONXOP_Dump jsonID
	ParameterIn = S_Value
	JSONXOP_Release jsonID

	errorCode = CallFunctionAndor("GetAcquiredData", ParameterIn, ParameterOut)
	return errorCode
End

// Handle ErrorCode from json output of CallFunction
// with Andor specific extraction of UINT32 result output errorCode.
//
// @param json JSON formatted string: @p ParameterOut from @ref CallFunction
//
// @ingroup errorHandling
//
// @return errorCode
Function ExtractErrorCode(string jsonStr)

	variable errorCodeCallFunction, errorCodeAndor
	variable jsonID

	JSONXOP_Parse jsonStr
	jsonID = V_Value
	JSONXOP_GetValue/V/Z=1 jsonID, "/errorCode/value"
	errorCodeCallFunction = !V_Flag ? V_Value : ERROR_EXTRACTJSON
	JSONXOP_GetValue/V/Z=1 jsonID, "/result/value"
	errorCodeAndor = !V_Flag ? V_Value : ERROR_EXTRACTJSON
	JSONXOP_Release jsonID

	if(errorCodeCallFunction)
		return errorCodeCallFunction
	endif
	return errorCodeAndor
End

// Andor-Camera specific wrapper to CallFunction
//
// @ingroup FCALL
//
// @param[in]  FuncName     Name of the C Function in the dll
// @param[in]  ParameterIn  json formatted input string for @c FCALL_CallFunction
// @param[out] ParameterOut json formatted output string from @c FCALL_CallFunction
//
// @see CallFunction
//
// @return errorCode
static Function CallFunctionAndor(string FuncName, string ParameterIn, string &ParameterOut)

	variable errorCode

	DFREF  dfr       = $AndorPackagePath
	SVAR/Z LibHandle = dfr:$LibAndor
	errorCode = CallFunction(LibHandle, FuncName, ParameterIn, ParameterOut)

	return errorCode
End

// wrapper for @c FCALL_CallFunction with ANDOR specific call to @ref ExtractErrorCode
//
// @ingroup FCALL
//
// @param[in]  LibHandle   location of open library from @c FCALL_LoadLibrary
// @param[in]  FuncName    Function from dll to call
// @param[in]  ParameterIn json encoded string for input to function
// @param[out] ParameterOut json encoded output from function
//
// @returns errorCode as definded in constants
static Function CallFunction(string LibHandle, string FuncName, string ParameterIn, string &ParameterOut)

	variable errorCode    = GENERIC_ERROR
	string   errorMessage = ""

	DFREF dfr = $AndorPackagePath

	ParameterOut = ""
	FCALL_CallFunction/Z LibHandle, FuncName, ParameterIn, ParameterOut
	if(!V_flag)
		errorCode = ExtractErrorCode(ParameterOut)
	else
		errorCode = ERROR_CALLFUNCTION
	endif

	return errorCode
End