0001 TPIMPORT(3)
0002 ===========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpimport - Import.a JSON formatted text buffer to UBF|VIEW|STRING|CARRAY|JSON type buffer
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpimport(char \*'istr', long 'ilen', char **'obuf', long *'olen', long 'flags');
0016
0017 For XATMI client link with '-latmiclt -latmi -lview -lnstd -lpthread -lrt -lm'
0018
0019 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lview -lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 Function converts JSON formatted text buffer into typed message buffer.
0024
0025 'istr' is JSON formatted buffer to import. If 'ilen' is 0, 'istr' is assumed
0026 to point to a null-terminated string. 'obuf' is output buffer should be allocated
0027 with *tpalloc()* call. If the allocated buffer size is shorter then received one,
0028 then Enduro/X will automatically realloc
0029 the buffer to new size. If 'olen' not NULL there will be stored imported buffer length.
0030
0031 tpimport support embedded UBF sub-buffers: *sub-UBF*, *sub-VIEW*, *sub-PTR*. The
0032 *VIEW* and *UBF* data is imported within the master *UBF* buffer. However *PTR*
0033 json fields will initiated allocation of new XATMI buffer, and pointer to XATMI
0034 buffer will be installed in master UBF. As UBF may have null occurrences, the
0035 same applies to VIEWS. The empty view name indicates that this is NULL view
0036 and will generate NULL/empty occurrence in UBF. See samples bellow.
0037
0038 *Valid flags*
0039
0040 If *TPEX_STRING* flag is set then input JSON formatted buffer is in base64.
0041
0042 If *TPEX_NOCHANGE* then do not allow to change the reply buffer type. If flag
0043 is set and different buffer type is received than original,
0044 then error *TPEINVAL* is returned.
0045
0046 *JSON tags in import file:*
0047
0048 - *buftype* - determine which type of buffer will be imported (STRING, UBF, VIEW, CARRAY, JSON)
0049
0050 - *version* - version of JSON text buffer to import
0051
0052 - *subtype* - contains name of VIEW buffer, used only to import VIEW buffer
0053
0054 - *data* - contains JSON formatted data
0055
0056
0057 EXAMPLES
0058 --------
0059
0060 Imported JSON as:
0061
0062 --------------------------------------------------------------------------------
0063 {
0064 "buftype":"UBF",
0065 "version":1,
0066 "data":
0067 {
0068 "T_SHORT_FLD":1765,
0069 "T_LONG_FLD":[3333111,2],
0070 "T_CHAR_FLD":"A",
0071 "T_FLOAT_FLD":1,
0072 "T_DOUBLE_FLD":[1111.220000,333,444],
0073 "T_STRING_FLD":"HELLO WORLD",
0074 "T_CARRAY_FLD":"AAECA0hFTExPIEJJTkFSWQQFAA=="
0075 }
0076 }
0077 --------------------------------------------------------------------------------
0078
0079 Will be imported to following UBF buffer:
0080
0081 --------------------------------------------------------------------------------
0082 T_SHORT_FLD 1765
0083 T_LONG_FLD 3333111
0084 T_LONG_FLD 2
0085 T_CHAR_FLD A
0086 T_FLOAT_FLD 1.00000
0087 T_DOUBLE_FLD 1111.220000
0088 T_DOUBLE_FLD 333.000000
0089 T_DOUBLE_FLD 444.000000
0090 T_STRING_FLD HELLO WORLD
0091 T_CARRAY_FLD \00\01\02\03HELLO BINARY\04\05\00
0092 --------------------------------------------------------------------------------
0093
0094 For example following JSON formatted text
0095
0096 --------------------------------------------------------------------------------
0097 {
0098 "buftype":"VIEW",
0099 "version":1,
0100 "subtype":"MYVIEW56",
0101 "data":
0102 {
0103 "MYVIEW56":
0104 {
0105 "tshort1":1,
0106 "tlong1":2,
0107 "tchar1":"A",
0108 "tfloat1":1,
0109 "tdouble1":21,
0110 "tstring1":"ABC",
0111 "tcarray1":"SEVMTE8AAAAAAA=="
0112 }
0113 }
0114 }
0115 --------------------------------------------------------------------------------
0116
0117 Will be imported into following VIEW:
0118
0119 --------------------------------------------------------------------------------
0120 VIEW MYVIEW56
0121 #type cname fbname count flag size null
0122 short tshort1 - 1 - - -
0123 long tlong1 - 1 - - -
0124 char tchar1 - 1 - - -
0125 float tfloat1 - 1 - - -
0126 double tdouble1 - 1 - - -
0127 string tstring1 - 1 - 15 -
0128 carray tcarray1 - 1 - 10 -
0129 END
0130 --------------------------------------------------------------------------------
0131
0132
0133 For example following JSON formatted text
0134
0135 --------------------------------------------------------------------------------
0136 {
0137 "buftype":"STRING",
0138 "version":1,
0139 "data":"HELLO WORLD"
0140 }
0141 --------------------------------------------------------------------------------
0142
0143 Will be imported into following STRING buffer
0144
0145 --------------------------------------------------------------------------------
0146 HELLO WORLD
0147 --------------------------------------------------------------------------------
0148
0149 For example following JSON formatted text
0150
0151 --------------------------------------------------------------------------------
0152 {
0153 "buftype":"CARRAY",
0154 "version":1,
0155 "data":"SEVMTE8gV09STEQgQ0FSUkFZ"
0156 }
0157 --------------------------------------------------------------------------------
0158
0159 Will be imported into following CARRAY buffer
0160
0161 --------------------------------------------------------------------------------
0162 0000 48 45 4c 4c 4f 20 57 4f 52 4c 44 20 43 41 52 52 HELLO WORLD CARR
0163 0010 41 59 AY
0164 --------------------------------------------------------------------------------
0165
0166 For example following JSON formatted text
0167
0168 --------------------------------------------------------------------------------
0169 {
0170 "buftype":"JSON",
0171 "version":1,
0172 "data":
0173 {"T_SHORT_FLD":1765,
0174 "T_LONG_FLD":[3333111,2],
0175 "T_CHAR_FLD":"A",
0176 "T_FLOAT_FLD":1,
0177 "T_DOUBLE_FLD":[1111.220000,333,444],
0178 "T_STRING_FLD":"HELLO WORLD",
0179 "T_CARRAY_FLD":"AAECA0hFTExPIEJJTkFSWQQFAA=="}
0180 }
0181 --------------------------------------------------------------------------------
0182
0183 Will be imported into following JSON buffer
0184
0185 --------------------------------------------------------------------------------
0186 {
0187 "T_SHORT_FLD":1765,
0188 "T_LONG_FLD":[3333111,2],
0189 "T_CHAR_FLD":"A",
0190 "T_FLOAT_FLD":1,
0191 "T_DOUBLE_FLD":[1111.220000,333,444],
0192 "T_STRING_FLD":"HELLO WORLD",
0193 "T_CARRAY_FLD":"AAECA0hFTExPIEJJTkFSWQQFAA=="
0194 }
0195 --------------------------------------------------------------------------------
0196
0197 Importing data with sub-buffers this example contains:
0198
0199 - sub-ubf single occurrence (T_UBF_FLD)
0200
0201 - two occurrence UBF buffers (T_UBF_2_FLD)
0202
0203 - single occurrence VIEW buffers (T_VIEW_FLD)
0204
0205 - three occurrence VIEW buffers (T_VIEW_2_FLD) with empty view in the 1 occ
0206
0207 - single occurrence PTR (T_PTR_FLD) - this pointers to another UBF data buffer
0208
0209 - two occurrence PTR (T_PTR_2_FLD) - this pointers to other UBF data buffers
0210
0211 --------------------------------------------------------------------------------
0212 {
0213 "buftype":"UBF",
0214 "version":1,
0215 "data":{
0216 "T_SHORT_FLD":55,
0217 "T_UBF_FLD":{
0218 "T_STRING_FLD":"HELLO WORLD INNER"
0219 },
0220 "T_UBF_2_FLD":[
0221 {
0222 "T_STRING_FLD":"HELLO WORLD INNER 1"
0223 },
0224 {
0225 "T_STRING_FLD":"HELLO WORLD INNER 2"
0226 },
0227 {
0228
0229 }
0230 ],
0231 "T_VIEW_FLD":{
0232 "MYVIEW56":{
0233 "tshort1":1,
0234 "tlong1":2,
0235 "tchar1":"A",
0236 "tfloat1":1,
0237 "tdouble1":21,
0238 "tstring1":"ABC",
0239 "tcarray1":"SEVMTE8AAAAAAA=="
0240 }
0241 },
0242 "T_VIEW_2_FLD":[
0243 {
0244 "MYVIEW56":{
0245 "tshort1":1,
0246 "tlong1":2,
0247 "tchar1":"A",
0248 "tfloat1":1,
0249 "tdouble1":21,
0250 "tstring1":"ABC_2",
0251 "tcarray1":"SEVMTE8AAAAAAA=="
0252 }
0253 },
0254 {
0255 "":{
0256
0257 }
0258 },
0259 {
0260 "MYVIEW56":{
0261 "tshort1":1,
0262 "tlong1":2,
0263 "tchar1":"A",
0264 "tfloat1":1,
0265 "tdouble1":21,
0266 "tstring1":"ABC_3",
0267 "tcarray1":"SEVMTE8AAAAAAA=="
0268 }
0269 }
0270 ],
0271 "T_PTR_FLD":{
0272 "buftype":"UBF",
0273 "version":1,
0274 "data":{
0275 "T_SHORT_FLD":1765,
0276 "T_LONG_FLD":[
0277 115,
0278 2
0279 ],
0280 "T_CHAR_FLD":"A",
0281 "T_FLOAT_FLD":1,
0282 "T_DOUBLE_FLD":[
0283 1111.220000,
0284 333,
0285 444
0286 ],
0287 "T_STRING_FLD":"HELLO WORLD",
0288 "T_CARRAY_FLD":"AAECA0hFTExPIEJJTkFSWQQFAA=="
0289 }
0290 },
0291 "T_PTR_2_FLD":[
0292 {
0293 "buftype":"UBF",
0294 "version":1,
0295 "data":{
0296 "T_SHORT_FLD":1765,
0297 "T_LONG_FLD":[
0298 1111,
0299 2
0300 ],
0301 "T_CHAR_FLD":"A",
0302 "T_FLOAT_FLD":1,
0303 "T_DOUBLE_FLD":[
0304 1111.220000,
0305 333,
0306 444
0307 ],
0308 "T_STRING_FLD":"HELLO WORLD 22",
0309 "T_CARRAY_FLD":"AAECA0hFTExPIEJJTkFSWQQFAA=="
0310 }
0311 },
0312 {
0313 "buftype":"UBF",
0314 "version":1,
0315 "data":{
0316 "T_SHORT_FLD":1765,
0317 "T_LONG_FLD":[
0318 4444,
0319 2
0320 ],
0321 "T_CHAR_FLD":"A",
0322 "T_FLOAT_FLD":1,
0323 "T_DOUBLE_FLD":[
0324 1111.220000,
0325 333,
0326 444
0327 ],
0328 "T_STRING_FLD":"HELLO WORLD 44",
0329 "T_CARRAY_FLD":"AAECA0hFTExPIEJJTkFSWQQFAA=="
0330 }
0331 }
0332 ]
0333 }
0334 }
0335 --------------------------------------------------------------------------------
0336
0337 The imported UBF would render as:
0338
0339 --------------------------------------------------------------------------------
0340 T_SHORT_FLD 55
0341 T_PTR_FLD 0x619000003280
0342 T_PTR_2_FLD 0x61900000be80
0343 T_PTR_2_FLD 0x619000002d80
0344 T_UBF_FLD
0345 T_STRING_FLD HELLO WORLD INNER
0346 T_UBF_2_FLD
0347 T_STRING_FLD HELLO WORLD INNER 1
0348 T_UBF_2_FLD
0349 T_STRING_FLD HELLO WORLD INNER 2
0350 T_UBF_2_FLD
0351 T_VIEW_FLD MYVIEW56
0352 tshort1 1
0353 tlong1 2
0354 tchar1 A
0355 tfloat1 1.00000
0356 tdouble1 21.000000
0357 tstring1 ABC
0358 tcarray1 HELLO\00\00\00\00\00
0359 T_VIEW_2_FLD MYVIEW56
0360 tshort1 1
0361 tlong1 2
0362 tchar1 A
0363 tfloat1 1.00000
0364 tdouble1 21.000000
0365 tstring1 ABC_2
0366 tcarray1 HELLO\00\00\00\00\00
0367 T_VIEW_2_FLD
0368 T_VIEW_2_FLD MYVIEW56
0369 tshort1 1
0370 tlong1 2
0371 tchar1 A
0372 tfloat1 1.00000
0373 tdouble1 21.000000
0374 tstring1 ABC_3
0375 --------------------------------------------------------------------------------
0376
0377
0378 RETURN VALUE
0379 ------------
0380 On success, *tpacall()* return call descriptor (>0); on error, -1 is returned,
0381 with *tperrno* set to indicate the error.
0382
0383 ERRORS
0384 ------
0385 Note that *tpstrerror()* returns generic error message plus custom message with
0386 debug info from last function call.
0387
0388 *TPEINVAL* Invalid parameter is given to function. Either 'istr' is NULL
0389 or flags does not allow to change the value.
0390
0391 *TPEINVAL* Invalid JSON or invalid base64 encoding, 'istr' is NULL or 'obuf' is NULL.
0392
0393 *TPEOTYPE* Invalid type specified to function. VIEW sub-type not found or
0394 environment is not configured.
0395
0396 *TPESYSTEM* System failure occurred during serving. See logs i.e.
0397 user log, or debugs for more info.
0398
0399 *TPEOS* System failure occurred during serving. See logs i.e.
0400 user log, or debugs for more info. In case of insufficient memory
0401 this error will be generated too.
0402
0403
0404
0405 EXAMPLE
0406 -------
0407
0408 Sample code see under:
0409
0410 - *atmitest/test056_tpimpexp/atmiclt56_ubf.c* - import UBF buffer
0411
0412 - *atmitest/test056_tpimpexp/atmiclt56_view.c* - import VIEW buffer
0413
0414 - *atmitest/test056_tpimpexp/atmiclt56_carray.c* - import CARRAY buffer
0415
0416 - *atmitest/test056_tpimpexp/atmiclt56_json.c* - import JSON buffer
0417
0418 - *atmitest/test056_tpimpexp/atmiclt56_string.c* - import STRING buffer
0419
0420
0421 BUGS
0422 ----
0423 Report bugs to support@mavimax.com
0424
0425 SEE ALSO
0426 --------
0427 *tpexport(3)*
0428
0429 COPYING
0430 -------
0431 (C) Mavimax, Ltd
