 | LkStrings |
This topic contains the following sections:
The functions can return the results expressed in 4 different ways.
One of the available output formats is the denominated LkObject. In this format an object of the LkData class is returned. (NOT available in C Library)
The other 3 output formats are (string) type formats. These formats are the MV, XML and JSON formats. To these 3 formats, inside this manual we will name call them LkStrings formats.
LkString: MVTo explain and better understand the information with this structure in this output format, we will use an example: the result of a reading operation. Specifically this is about the two reading records, with codes 2 and 3, from LK.CUSTOMERS record.
In the example that is shown below, line breaks have been added for a better explanation of their structure. Each different section is delimited by the ASCII 28 code. In Linkar TESTER, the 28 ASCII character is replaced by : \u01c to make it more visual. In turn, inside each section, when there is an items list (as is our case, since 2 records have been read), the character ASCII 30 code is used (in Linkar TESTER this is replaced by a \u01e )to separate the items.
THIS_LISTþTOTAL_RECORDSþRECORD_IDþRECORD_ID_DICTSþRECORDþRECORD_DICTSþCALCULATEDþCALCULATED_DICTSþERRORS \u01c 2 \u01c 2\u01e3 \u01c @IDþCODE \u01c CUSTOMER 2þADDRESS 2þ444 - 444 - 002\u01eCUSTOMER 3þADDRESS 3þ444 - 444 - 003 \u01c NAMEþADDRþPHONE \u01c \u01e \u01c \u01c
In the first section a list of labels appears with the character þ (@AM attribute mark). Each label corresponds to each name of the following session. This way, the first section is called THIS_LIST, the second section TOTAL_RECORS, the third RECOR_ID, the fourth RECORD_ID_DICTS etc-
In the first section we find this first section and the rest of sections name.
In the second section (TOTAL_RECORD) we find the 2 value, because a total of 2 records have been read.
In the third section (RECORD_ID_DICTS) we find two dictionaries of Record Id. @ID and CODE.
In the fourth section (RECORD_ID) we find a records ID list. Since it is a list, the 2 and 3 ID´s are separated by the items separator character (\u01e)
In the fifth section (RECORD) we find the whole content of each record read. Since it is also a list, the (\u01e) character is used to separate the content of each record. The record content is shown just like it was in the database, preserving all its original marks: attribute marks (@AM), multivalue (@MV), subvalue (@SM) or Text (@TM).
In the sixth section (RECORD_DICTS) we find the names of the file dictionaries separated by the character þ (@AM attribute mark).
In the seventh section (CALCULATED) we would find the data from the calculated fields in each one of the 2 records read. Since this file has no calculated fields there is nothing to show, just the items separator character \u01e.
In the eighth section (CALCULATED_DICTS) the calculated field names. Since there are none this will be empty.
In the last section (ERRORS), if there were any, the error message would be shown.
More or less sections can appear depending on the operation and options of each operation. The section names always correspond with the same property names from the names of the LkData class properties. When the Read_Text was executed, the result of which we are using in this example, the Calculated option was activated inside its ReadOptions. Due to that, in this example, there are CALCULATED and CALCULATED_DICTS sections, although they are empty
If you wish you can experiment with the Linkar TESTER program, executing Read functions, with different ReadOptions to see the different results. With this program, you can execute all the available clients functions with all their options
The complete list of MV labels is listed below:
THIS_LIST RECORD_ID RECORD_ID_DICTS RECORD RECORD_DICTS CALCULATED CALCULATED_DICTS DICTIONARIES_ID DICTIONARIES ORIGINALRECORD TOTAL_RECORDS ARGUMENTS CAPTURING RETURNING CONVERSION FORMAT ROWHEADERS ERRORS
LkString: XMLWe will use an example to explain this output formats: the result of a reading operation. It is specifically about reading the LK.ORDERS file with ItemID 2.
XML Format
Line breaks have been added for clarity.
<?xml version="1.0" encoding="UTF-8"?> <LINKAR> <TOTAL_RECORDS>1</TOTAL_RECORDS> <RECORDS> <RECORD> <LKITEMID>2</LKITEMID> <CUSTOMER>73</CUSTOMER> <DATE>17566</DATE> <ITEM>101105</ITEM> <QTY>286</QTY> <PRICE>271.18</PRICE> <DELIVERYDATE>17619ü17659</DELIVERYDATE> <QTYPARTIAL>143ü143</QTYPARTIAL> </RECORD> </RECORDS> </LINKAR>
The <LINKAR> node is the root. It only acts as a container of the operation result properties.
XML properties
- TOTAL_RECORDS Property: Number of records. In our example 1, because we have read only one record.
- RECORDS Property: The list with all the records. Each particular record will have the tag RECORD. It will appear as many as RECORD tags as records found.
The second level nodes names always correspond with the properties names of the LkData class. For instance in an EXECUTE operation you will find <CAPTURING> … </CAPTURING> and <RETURNING> … </RETURNING> tags.
All RECORD tags represent a mv record. All of them have an special tag, LKITEMID, that represents the item-id of the record. They can also have another tag, ORIGINAL_RECORD, that has a copy of the record in mv format. You will have this tag if you have activated the option "Original Record" in the read. All other tags represent the record. If the attribute has a dict, the tag will be the DICT. If there are not dicts, Linkar with add the word LKFLD+the attribute number (f.i. LFFLD1 for first attribute).
Both, real attributes and calculated fields, are part of the RECORD tag. You can always know what kind of data are each one using the DICTIONARIES and LKPROPERTIES functions.
XML_DICT Format
This format uses dictionaries data in order to create a more complex structure. It uses the data defined in Assoc or Structure attributtes in the data bases that allows them. If it uses the structure (control-depend) definition like D3 it will name the groups with the <MvGroup> tag
This only has effect inside the <RECORD> tag, so we only show this one.
<RECORD> <LKITEMID>2</LKITEMID> <CUSTOMER>73</CUSTOMER> <DATE>17566</DATE> <LST_LstItems> <LstItems> <ITEM>101105</ITEM> <QTY>286</QTY> <PRICE>271.18</PRICE> <DELIVERYDATE>17619ü17659</DELIVERYDATE> <QTYPARTIAL>143ü143</QTYPARTIAL> </LstItems> </LST_LstItems> </RECORD>
You can see that Linkar has expand the multivalue groups using the dictionary information. Each group has a tag, f.i. <LST_LstItems> and inside the tag another one for each multivalue attribute of the group, <LstItems>.
Linkar uses only dictionary information for this format, so it cannot process subvalues with this output format.
XML_SCH Format
This format uses the Linkar SCHEMAS properties, that allows it to generate even more complex structures using also subvalues.
This only has effect inside the <RECORD> tag, so we only show this one.
<RECORD> <LKITEMID>2</LKITEMID> <CUSTOMER>73</CUSTOMER> <DATE>17566</DATE> <LST_MvItems> <MvItems> <ITEM>101105</ITEM> <QTY>286</QTY> <PRICE>271.18</PRICE> <LST_SvDeliveryDates> <SvDeliveryDates> <DELIVERYDATE>17619</DELIVERYDATE> <QTYPARTIAL>143</QTYPARTIAL> </SvDeliveryDates> <SvDeliveryDates> <DELIVERYDATE>17659</DELIVERYDATE> <QTYPARTIAL>143</QTYPARTIAL> </SvDeliveryDates> </LST_SvDeliveryDates> </MvItems> </LST_MvItems> </RECORD>
As you can see, now the subvalues use the same kind of structure, one tag for a subvalue group, <LST_SvDeliverydates> , and another one for each subvalue in the group, <SvDeliveryDates>.
Linkar can do it using the information defined in Linkar Schemas. You must define SCHEMAS in order to use this tag.
If you wish you can experiment with the Linkar TESTER program, executing Read functions, with different ReadOptions to see the different results. With this program, you can execute all the available clients functions with all their options
LkString: JSONTo explain and better understand this structure with the information in this output formats, we will use an example: the result of a reading operation. It is specifically about the record read, with code 2, from the LK.ORDERS record. In the example that is shown below line breaks have been added for a better explanation of their structure.
JSON Format
This is similar to the database record structure. It will use the dictionary names to create the nodes name and do nothing with the mv and sv marks.
Line breaks have been added for clarity.
{
"TOTAL_RECORDS": "1",
"RECORDS": [{
"LKITEMID": "2",
"CUSTOMER": "73",
"DATE": "17566",
"ITEM": "101105",
"QTY": "286",
"PRICE": "271.18",
"DELIVERYDATE": "17619ü17659",
"QTYPARTIAL": "143ü143"
}
]
}JSON properties
The second level nodes names always correspond with the properties names of the LkData class. For instance in an EXECUTE operation you will find CAPTURING … and RETURNING … properties.
All RECORD tags represent a mv record. All of them have an special property, LKITEMID, that represents the item-id of the record. They can also have another one, ORIGINAL_RECORD, that has a copy of the record in mv format. You will have this property if you have activated the option "Original Record" in the read. All other tags represent the record. If the attribute has a dict, the property will be the DICT. If there are not dicts, Linkar with add the word LKFLD+the attribute number (f.i. LFFLD1 for first attribute).
Both, real attributes and calculated fields, are part of the RECORD properties. You can always know what kind of data are each one using the DICTIONARIES and LKPROPERTIES functions.
JSON_DICT Format
This format uses dictionaries data in order to create a more complex structure. It uses the data defined in Assoc or Structure attributes in the data bases that allows them. If it uses the structure (control-depend) definition like D3 it will name the groups with the MvGroup property.
This only has effect inside the RECORD property, so we only show this one.
{
"LKITEMID": "2",
"CUSTOMER": "73",
"DATE": "17566",
"LstItems": [{
"ITEM": "101105",
"QTY": "286",
"PRICE": "271.18",
"DELIVERYDATE": "17619ü17659",
"QTYPARTIAL": "143ü143"
}
]
}You can see that Linkar has expand the multivalue groups using the dictionary information. Each group has a property, f.i. LST_LstItems and inside it another one for each multivalue attribute of the group, LstItems.
Linkar uses only dictionary information for this format, so it cannot process subvalues with this output format.
JSON_SCH Format
This format uses the Linkar SCHEMAS properties, that allows it to generate even more complex structures using also subvalues.
This only has effect inside the RECORD property, so we only show this one.
{
"LKITEMID": "2",
"CUSTOMER": "73",
"DATE": "17566",
"MvItems": [{
"ITEM": "101105",
"QTY": "286",
"PRICE": "271.18",
"SvDeliveryDates": [{
"DELIVERYDATE": "17619",
"QTYPARTIAL": "143"
}, {
"DELIVERYDATE": "17659",
"QTYPARTIAL": "143"
}
]
}
]
}As you can see, now the subvalues use the same kind of structure, one property for a subvalue group, LST_SvDeliverydates, and another one for each subvalue in the group, SvDeliveryDates.
Linkar can do it using the information defined in Linkar Schemas. You must define SCHEMAS in order to use this property.
If you wish you can experiment with the Linkar TESTER program, executing Read functions, with different ReadOptions to see the different results. With this program, you can execute all the available clients functions with all their options.