NEED DOCUMENTATION CONTRIBUTIONS
If you would like to contribute documentation to this page in ANY way shape or form, please contact me (firstname.lastname@example.org) and I will get you authority. It could be a big contribution or a small contribution. It could be detailing out something you learned or describing an approach to use an OpenRPGUI API. Please help carry the project.
RPGUI (short for RPG User Interface) is a framework for RPG developers on the IBM i to use for building modernizing looking applications. The purpose of this document is to brainstorm the various aspects of the RPGUI framework.
The RPGUI framework is in it's infancy. We have big plans for it but it WILL NOT reach it's full potential unless others get involved and donate their time and resources. Below is a list of things we are actively in need of to further the RPGUI framework.
- "Stateful Job" capabilities. This relates to the graphic below where there is a main CGI Router job that receives in all requests and routes them to the appropriate job via data queue.
- Reorganize the installation so users don't need to manually upload IFS files. There is a way to store IFS files in a *SAVF file and it would be good to simplify the install by including those in the main *SAVF object.
- Research which code documentation tool should be used. Right now I would lean towards ILEDocs (https://sourceforge.net/projects/iledocs/)
- Put together DB2 tables that will be used to store the configuration of a screen.
This section will define terms used throughout this document that may not be readily apparent without formal definition.
- CGI Router - This program will process all HTTP inbound requests and send the associated response back to the requester. It will recognize what type of request was sent (i.e. JSON) and appropriately "parse" it into the intermediary holding place.
- Screen - A "screen" is a collection of UI components displayed to the user. This could be a data grid, a modal dialog, a fully form, a "processing request" pop-up, etc - essentially it is anything that takes control over the currently displayed components to the user.
- User Job - A user job is nearly exactly similar to what we know today as an interactive job.
High Level Requirements
This section will detail high level requirements of RPGUI.
Utilize Existing OS400 Infrastructure
There are MANY aspects of OS400 that are very robust and reliable. These aspects will purposely be focused on as "must haves" so we don't require "re-inventing the wheel". These aspects/features would include things like job-per-user, library lists, call stacks, open data paths, etc.
In short, RPGUI needs to provide significant time savings over traditional CGI for the RPG developer. To meet this need there will mechanisms put into place that purposely hide complexities of the many technologies involved to keep the programmer productive. For example, the RPG programmer shouldn't have to manually enter ExtJS code into a text editor because that would be highly error prone and subject to complex syntax errors. Instead they should be able to configure screens and UI components by "documenting" them in a DB2 table - similar to how a display file record is documented - location of fields, their data types, actions to take when keys are pressed, etc.
- Will utilize existing OS400 security through the use of OS400 user profiles.
- Utilize Apache's and DCM's SSL capabilities to digitally sign and encrypt traffic.
- Address "Remoting Hi-jacking".
Logging and Debugging
For a framework to be successful it must be easy to locate issues.
- Have a central DB2 table where "events" and/or logs can be placed, where each row contains a code, severity, program that created the entry, text description
- Have a browser based application that can be used to easily query the aforementioned central DB2 events/log table.
Much will be gained by utilizing existing OS400 infrastructure, so there will be some performance we get for "free". <TODO add more>
Flow Of Processing
This image is used to depict the flow of a request from the browser to the server and how the server processes it before a response is sent back.
- 1 - JSON request comes in from browser and is received by CGI Router.
- 2 - JSON request is parsed and placed into Request Data resource (*USRSPC). If there isn't a session Id present then a job will be submitted to listen on the keyed data queue.
- 3 - CGI Router writes an entry to keyed data queue, specifying the session Id as the key and immediately does a read on the same data queue to wait for the Business Logic Program to respond.
- 4 - Business Logic Program receives entry from data queue, causing it to resume processing.
- 5 - Business Logic Program retrieves necessary information from Request Data (i.e. what button was pressed) and based on that acts on the other data accordingly.
- 6 - After doing necessary business logic, Business Logic Program will send "compose" response and send it to Response Data. Composing the response will consist of either updating the existing form or sending a new form down to the UI device.
- 7 - Write an entry to the keyed data queue to signal that the processing of the request is done and immediately do a read of the same data queue to go back into a wait state.
- 8 - CGI Router reads the data queue entry.
- 9 - Obtain data from Response Data.
- 10 - Send serialized response back down to the requester.
- Utilize the program call stack for navigation. This feature is specific to traditional 5250 applications where you can have PGM1 call PGM2 without PGM2 needing to know what screen it is returning control to. This lessens the need for duplicate programming of the same screen
- Each User Job will have it's own library list in traditional 5250 session fashion.
- Each User Job will have their corresponding job log which can be viewed via normal mechanisms (i.e. WRKACTJOB opt 5 opt 10)
Detailed in here will be the specific UI components needing to be implemented. They will be prioritized into groups of "fundemental" and "nice to have". Eventually it would be good to support all of the ExtJS UI components, but for the sake of quick ROI we will choose a select few. Obviously we should generically support and name the various UI components, but being ExtJS is the primary implementation objective we will reference ExtJS UI compoenents for describing what we would like to implement.
- Standard form with submit capabilities - http://www.extjs.com/deploy/dev/examples/form/dynamic.html
- Display only Grid - http://www.extjs.com/deploy/dev/examples/grid/array-grid.html
- Editable Grid - http://www.extjs.com/deploy/dev/examples/grid/edit-grid.html
- Is there an issue with each user having their own job? What are the limitations if any?
- Ability to "peek" at data queue entries (http://i5toolkit.sourceforge.net/q/page_dspqmsg.html)
- Need the ability for the browser to reliably talk to a job sitting on the other side of a data queue.
- Time outs. There will be two primary areas where time-outs can and need to occur. The user job listening for interactions from the browser and also when the CGI Router program is waiting for a data queue response from the user program.
- Where to store intermediary data? Data received in from the browser will need to be stored someplace temporarily by the CGI Router so after the user job receives a data queue entry it can be readily accessed. Similarly there will need to be a place for the response to be place so the CGI Router can send it back to the requester.