/faq/index.htmlChapter 9 FAQ This chapter contains various articles which describes how to solve different aperio or API problems. the articles are based on true questions from users. Most of solutions described in these articles are also done as example programs delivered together with aerio backend. The sample programs are shiped in QSAMPLES source file.Hugoen-usTue, 04 Oct 2022 17:13:07 +0200/faq/crud_dc1apiexample/index.htmlTue, 04 Oct 2022 17:13:07 +0200/faq/crud_dc1apiexample/index.htmlThe example programs can be found in the QSAMPLES source file and they are delivered together with Aperio. CRUD operations are performed over file FILE01. DSRE01 - black box program for validation incoming data and maintaining the file. EXAMPLE025 getting a list of records EXAMPLE026 getting one record EXAMPLE027 adding new record EXAMPLE028 record update EXAMPLE029 record deletion Message handling is performed according to : How to handle messages in Aperio (Standard DC1 method )/faq/crudnondc1apiexample/index.htmlTue, 04 Oct 2022 17:13:07 +0200/faq/crudnondc1apiexample/index.htmlThe example programs can be found in the QSAMPLES source file and they are delivered together with Aperio. CRUD operations are performed over file FILE01. DSRE02 - black box program for validation incoming data and maintaining the file. EXAMPLE030 getting a list of records EXAMPLE031 getting one record EXAMPLE032 adding new record EXAMPLE033 record update EXAMPLE034 record deletion Black box program Data structure for the parameter list for DSRE02 is based on file DSLE02. Database fields in DSLE02 (ones that correspond to fields from FILE01) should be defined with ALWNULL keyword, so the program can check if the value is passed (null indicator off)./faq/salesdi/index.htmlTue, 10 Nov 2020 09:10:10 +0200/faq/salesdi/index.htmlThere are 2 sets of methods that can be used to create sales order in DC1: Methods which use DI (witout prevalidation) Methods to dirrect create sales orders. Create sales orders inside DI files These are set of API’s which create sales order inside DI files. You don’t have validation of data you put inside files. You can use these API’s to register an order with any type, because these orders will be managed by standard DI interface. (You can e.g. use a sales order type with ‘invoicing only flag’)/faq/messagehandling/index.htmlTue, 04 Aug 2020 11:34:13 +0200/faq/messagehandling/index.htmlGeneral overwiew. Generally in API comunication the the service program sends response data only. After the request with incoming parameters are received, server calculates answer and put it into the response. In case there is no corresponding records or update process fails etc.. the apropriate HTTP code is returned back. But what in case the server wants to send message to the client? The Message can be packed to hardcoded field in response data. Or send in HTTP headers etc.. How to transfer variable message text from RPG program to the client. If there is only one RPG program in call chain then seems to be not an issue to receive mesages sent by it then put all of them into response… But in case there are several programs in call chain, all of them should have possibility to send their messages independly then gather all of them in the response. How to do it? There is no general answer. There are couple of ways. In this article we describe three of them which we currently use in our solutions./faq/installationprocess/index.htmlTue, 28 Jul 2020 10:53:41 +0200/faq/installationprocess/index.htmlPrerequisite check Make sure that all RPG method sources are available. Current version of metadata retrieves information directly from the source on the fly. If the RPG source members for methods are not available or stored in library which is not on library list, then this process will fail. Make sure that all sources contain necessary @APIDOC_ tags which describes Your methods. If the RPG programs source location is specific in Your environment, make sure to write exit program which will be able to localize source file based on RPG program location. The example of exit programs are located in QSAMPLES source file delivered together with Aperio./faq/upgradeprocess/index.htmlMon, 27 Jul 2020 08:59:13 +0200/faq/upgradeprocess/index.htmlUPGAPI command There is UPGAPI dedicated API command to upgrade Aperio framework. The upgrade process covers the following steps: checking authority to use crucial commands to make the upgrade (e.g. SAVLIB and RSTLIB) making backup of API framework library exporting all data in Metadata, Control, Configuration and Notification libraries restoring all objects from save file containing entire Aperio framework saved into framework library changing owner of all objects in framework library (by default to the owner already set for Framework library) initializing API Framework updating data in Metadata, Control, Configuration and Notification libraries by making an import from already exported data To not loose information during upgrade process? There is the mechanism to restore Aperio elements (Framework library + libraries containing Metadata, Control, Config and Notification related data) under UPGAPI command in case of failure during the upgrade process, but still it’s possible to make a backup copy of Framework library (e.g. by using SAVLIB) and/or export all API data via EXPAPIDTA command./faq/sorting/index.htmlFri, 24 Jul 2020 09:08:26 +0200/faq/sorting/index.htmlSorting feature is an option in methods which return array as response and are SQLRPGLE program with embedded SQL. It gives the possibility of arranging items in a sequence ordered by some criterion. The sorting in Aperio is based on orderBy control parameter where the passed value can be as follows 'parameter1 [ASC | DESC], parameter2 [ASC | DESC], ...' In this syntax: parameter1, parameter2, etc., that can be names of method parameters by which you want to sort the result set ASC to sort the result set in ascending order (from low to high) and DESC to sort the result set in descending order (from high to low). The ASC or DESC is optional. If you skip it, ASC is used by default. In order to implement the sorting in RPG program:/faq/externalapi/index.htmlThu, 23 Jul 2020 09:10:10 +0200/faq/externalapi/index.htmlApproaches in integration with external APIs: Directly to external API The following RPG procedures can be used to handle external API call: extApi() extApiGet() extApiPost() extApiPut() extApiDelete() You can use extApi() where the first mandatory parameter is API method name to complete the request or one of its equivalents (extApiGet(), extApiPost(), extApiPut() or extApiDelete()) for given HTTP method./faq/dataexpiration/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/dataexpiration/index.htmlThe data expiration control is one of the main problem with stateless and multi access applications. The web service should check if data on the back end was changed meanwhile. How to do it? There are many ways to check if data was changed. The most trivial one seems to be lock record while reading. Then unlock if update operation is performed. But this is against stateless rule. You never know if the update operation will come and will be operated by the same job. It may happen that update operation will never be sent from client. What to do then with locked records? In aperio we introduced mchanism which helps You to calculate record state hash code. Based on entire record from database you can calculate hash code. There is possbilitity to send to the client hash code of record together with data while reading. Then the update procedure must send saved hash code back to the manager program. Manager program once again calculates current hash code of record and compare it to this one which was received from client. If there are no changes then update is allowed. If hash codes are different then error message is send back to the client./faq/environmentinit/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/environmentinit/index.htmlThe skeleton program was prepared for this purpose. In the QSAMPLES source file devlivered together with aperio You can find SKELETON06 source which is ready to fill. You can copy it and adjust or change if needed. The skeleton of environment.init method was build based on DC1 initialization program and requires three parameters: environmentBaseLibrary <– This is library where the main information is stored for environment environmentId <– The ID of environment which can be used by program to find what to do (how to build environment) comanyCode <– This parametr indicates which company will be used to initialize environment. The environment.init method should return (it is not manadatory but reccomendation):/faq/complexresponse/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/complexresponse/index.htmlIt is possible to create any complex response using aperïo, but there are couple of limitations: The response is prepared in job memory which is limited to 16MB per job. These 16 MB are total available memory limited by IBM in single cheap storage model. This is more than enough if someone wants to create web services in micro service style. Iptor approach is performance and micro services structure of API. That is why we stick to straight requests/responses. Every time when RPG program is created the programmer must to take it into consideration, that job memory is limited. The other factor is reasonable response time. It may happen that creating verry complex and big response takes long time./faq/complexrequest/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/complexrequest/index.htmlConsuming complex requests are possible in aperïo. There are some limitations which comes from performance assumptions. Total memory per job is 16MB. As Iptor is focused on performance of aperïo the JSON parser is created as “direct indexing parser”, not DOM parser. DOM parser was much more slower in usage by RPG programs. NOTE: In the road map is to prepare full DOM JSON parser and possibility for programer to decide which one is used in aperïo. Currently the number of incoming parameters are limited to 1024./faq/rest/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/rest/index.htmlWhenever someone creates API RPG program, he is faced with problem how to correctly build response. In this article I will try to give some tips how to do it. First of all, the main tip is to split problem into small problems. Each project (task) can be divided to very small atomic API-s. Developer should avoid to create very complex responses. The simple programs (microservices) will be easier to maintain and will contain less bugs. The best idea is to not mix types of response in one program. For example itemPrices.get method should return array of prices. Or itemBatch.get should return simple object which will contain only one batch for given item. But what should return salesOrder.get program? Should it return only header information? Or should it return header information together with lines? Should we add also order header texts to the returned information? The answer is….. it depends. The best idea is to split this problem into several API-s. Each responsible for one particular object:/faq/menumethod/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/menumethod/index.htmlThe sample program was prepared for this purpose. In the QSAMPLES source file devlivered together with aperio You can find all sources ready to use as dynamic menu structure. The programs and files are ready to compile. You can copy it and adjust or change if needed. Following sources contain necessary elements to build dynamic menu structure: MENU_ATTR PF Menu items attributes MENU_AUTH PF Menu items authority MENU_GET SQLRPGLE applicationMenu.get MENU_STR PF Menu structure The menu structure is stored in MENU_STR. This file contains 3 columns:/faq/controlcharacters/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/controlcharacters/index.htmlIt 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:/faq/paging/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/paging/index.htmlPaging is required in methods which returns array as response. In case there is a lot of data in file which needs to be transferred the paging limit tada transfer. Especially if You build user interface (mobile application) based on aperio paging is verry useful. Not all records are loaded to to screen but limited number of records. The paging in aperio is based on two control parameters: limit <– says how many of records you want to receive back in one go offset <– says from which index to start read data There is also information which should be returned back by method. This will give client possibility to calculate total number of pages:/faq/security/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/security/index.htmlThere are couple of methods to secure API methods in IBMi. In this article I will focus on four of them. It means IBMi way, DC1 secur way, Aperio way and security exit program. IBMi way First of all the API methods are ordinary programs or rather objects in IBMi operating system. It means the easiest way to secure them is to define authority to objects. This is pure administration work. System administrator can grant authority only for certain users and programs. The MGRRxxxx programs (managers or wrappers) are used only by aperio. They are not called from other places of DC1 system. If user has no access to specific MGRRxxxx program, it will not harm anything in DC1 flow. Just use WRKOBJ command in IBMi operation system and edit authority for MGRRxxxx object./faq/blob/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/blob/index.htmlTo operate on CLOB values aperio has some procedres: reqGetBlobValue() respAddBlobField() respAddBlobValue() As the CLOB value length is not known when You write program these three procedures use pair of parameters to handle long data: Pointer to data Length of data in bytes To add long data into response use respAddBlobField() or respAddBlobValue() and provide pointer to data and length in bytes Example: D lText S 1600A /FREE lText = 'Sample long text bla bla bla bla'; respAddBlobField('data':'text':%ADDR(lText):%LEN(%TRMR(lText))); To get CLOB value from request use procedure reqGetBlobValue(). This procedure returns pair of values, pointer to data and length of data./faq/graphicalsignature/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/graphicalsignature/index.htmlThere is component “graphical-signature” available in JForms. { "text": "Signature", "params": ["documentId"], "elements": [ { "text": "Sign the following document", "type": "h4"}, { "id": "signature", "type": "graphical-signature", "onOK": { "method": "signatureMethod.add", "params": { "signature": "signature", "documentId": "documentId" }, "onOK": "*back" } } ], "actions": [ "*back" ] } Example of graphical signature panel To include graphical signature component just add element into JForm with type “graphical-signature”. This component returns encrypted signature which is built based on the graphical representation of signature on the screen./faq/exitpoint/index.htmlMon, 13 Jul 2020 17:13:07 +0200/faq/exitpoint/index.htmlThe exit point program it is special program which is run in certain moment of aperio process. Program can calculate something in middle of aperio process then return results back to process. By this it is possible to influence to the aperio job. All exit programs has the same entry parameters: Parameter Type Description len 10U0 Mandatory This parameter is used to pass length of incoming data data varying length data structure which contains entry parameters Mandatory This parameter can be freally defined by programer. The type and length of this parameter is not important. As the parameters between programs are passed by reference, the pointer when data entry parameter starts is the starting point of data structure. Exit points are called from following points of process in aperio: