It may happen that text variable on iSeries contains control characters. sometimes it is intentionally, sometimes not. These characters can’t be put into JSON string as they are not valid value. The idea is to change them to one of predefined escaped characters, like "\n" or "\t" or "\uXXXX" where XXXX is hexadecimal code of character in unicode. To not force developer to do it aperio gives possibility to automatic conversion special characters into correct JSON value. all procedures which are handle String or UCS2Value… has incorporated automatic conversion of special characters. This conversion can be turned off in any moment. For example:
Let imagine the variable xxText contains special character after coma.
xxText = 'Lorem ipsum dolor sit amet,<CR><LF> consectetur adipiscing elit.';
Then procedure respAddStringField(‘data’: ‘myTextField’: xxText); will automatically convert this text to correct JSON value:
{
"myTextField":"Lorem ipsum dolor sit amet,\n consectetur adipiscing elit."
}
the conversion algorithm converts as follows: This procedure converts JSON value to text. Means converts:
/ --> \/
\ --> \\
" --> \"
0x09 --> \t
0x0B --> \f
0x0C --> \r
0x0D --> \n
0x08 --> \b
0x0A --> \r\n
spec char bellow 0x1F--> \uXXXX where XXXX is hex number
Automatic conversion sometimes is not desired. Let imagine programmer wants to code as \n character inside his program then:
xxText = 'Lorem ipsum dolor sit amet,\n consectetur adipiscing elit.';
will be converted by respAddStringField(‘data’: ‘myTextField’: xxText); to:
{
"myTextField":"Lorem ipsum dolor sit amet,\\n consectetur adipiscing elit."
}
In this case we have two options: a) turn off automatic conversion
xxText = 'Lorem ipsum dolor sit amet,\n consectetur adipiscing elit.';
respAddStringField('data': 'myTextField': xxText: *OFF);
will not convert value at all. So, the result will be:
{
"myTextField":"Lorem ipsum dolor sit amet,\n consectetur adipiscing elit."
}
b) use 0x0D control character in text instead of \n
xxText = 'Lorem ipsum dolor sit amet,<0x0D> consectetur adipiscing elit.';
respAddStringField('data': 'myTextField': xxText);
will convert value 0x0D –> \n in text. The result will be:
{
"myTextField":"Lorem ipsum dolor sit amet,\n consectetur adipiscing elit."
}
The same functionality is introduced to UCS2 procedures, means respAddUCS2Field() and respAddUCS2Value()
What to do with incoming data in request? Here we are facing with situation, that value is already passed using JSON and contains only JSON correct values. There are no any special characters, all of them are “escaped”. Aperio reqGetValue() and reqGetUCS2Value() procedures automatically converts incoming strings to “unescaped” ones. example:
Incoming JSON: ...., "myTextField":"Lorem ipsum dolor sit amet,\n consectetur adipiscing elit.",......
xxText = reqGetValue('params': 'myTextField');
will convert value to:
...'Lorem ipsum dolor sit amet,<0x0D> consectetur adipiscing elit.'...
or
Incoming JSON: ...., "myTextField":"Lorem ipsum dolor sit amet,\\n consectetur adipiscing elit.",......
xxText = reqGetValue('params': 'myTextField');
will convert value to:
...'Lorem ipsum dolor sit amet,\n consectetur adipiscing elit.'...
In case programmer wants to avoid automatic conversion there is extra optional parameter which allows it. NOTE: There are four parameters which should be omitted (value type, exits, value pointer and value length)
Incoming JSON: ...., "myTextField":"Lorem ipsum dolor sit amet,\n consectetur adipiscing elit.",......
xxText = reqGetValue('params': 'myTextField': *omit: *omit: *omit: *omit: *OFF);
…will NOT convert value. So, the result will be:
...'Lorem ipsum dolor sit amet,\n consectetur adipiscing elit.'...