Getting Started

1. Prepare the Smeup Service template

This section shows the prototype template of a Smeup service: this service is in RPGLE code in fixed format, and it's composed of:

versioning notes in the format dd/mm/yy nn.mm i xx description_text (comment)
notes describing the service activities (comment)
section for the F and D specifications
initials /COPY
MAIN block
/COPY £INIZI
subroutine £INIZI
subroutine IMP0
subroutine FIN0
subroutine £JAX_LOG
finals /COPY

X1_X11_03.rpgle
     V* ============================================================================================
     V* CHANGES   Ril.  T Au Description
     V* dd/mm/yy  nn.mm i xx description_text
     V* ============================================================================================
     V* 
     V* ============================================================================================
      * Simple example of RPGLE service that will allow users to record their activities,
      * which will be represented by the Activity model.
      *--------------------------------------------------------------------------------------------*
      * Here you put variables definitions (F and D specifications)
      *--------------------------------------------------------------------------------------------* 
      /COPY QILEGEN,£JAX_D
      /COPY QILEGEN,£PDS
      *--------------------------------------------------------------------------------------------* 
      * MAIN
      *--------------------------------------------------------------------------------------------*
     C                   EXSR      IMP0
      *
      * 1. Logic of the "method-function" sifter
      *
     C                   EXSR      FIN0
      *
     C                   SETON                                        LR 
      /COPY QILEGEN,£INZSR
      *--------------------------------------------------------------------------------------------* 
      *--------------------------------------------------------------------------------------------*         
      * £INIZI
      *--------------------------------------------------------------------------------------------*
     C     £INIZI        BEGSR
     C                   ENDSR 
      *--------------------------------------------------------------------------------------------*
      * IMP0
      *--------------------------------------------------------------------------------------------*
     C     IMP0          BEGSR
     C                   ENDSR
      *--------------------------------------------------------------------------------------------* 
      * FIN0
      *--------------------------------------------------------------------------------------------*
     C     FIN0          BEGSR
     C                   ENDSR
      *--------------------------------------------------------------------------------------------*
      * Specific application log                                     
      *--------------------------------------------------------------------------------------------* 
     C     £JAX_LOG      BEGSR                                         
     C                   ENDSR
      *--------------------------------------------------------------------------------------------*
      /COPY QILEGEN,£JAX_C

Create the service file in the directory /kokos-dsl/JASRC and call it X1_X01_03.rpgle, and copy the template code into the file: this will be your template and you will be modify by adding section with a step-by-step procedure.

2. Initializing the data source

The service we need to implement has the task of reading from a database of entities representing activities and returning them in the form of a Smeup Data Table. To continue, we must therefore know how the data to be retrieved from the database is structured. For this tutorial we will use a preconfigured database in docker mongodb called SMEUP_TUTORIAL and the collection X1_X010F that contain the data.

2.1 Definition of the model

Activity: represent the activity that a user can track. Each activity includes the following attributes:

Field	Description field	Smeup Data Format	Length field
Date	The date when the activity takes place	D8*YYMD	8
Description	A brief description of the activity		50
Start at	The time the activity begins	I12	6
End at	The time the activity ends	I12	6
Style category	The style associated with the category		5
Category	The type or classification of the activity (e.g., work, sport)		20
Hours	Hours of activity	NR	4;2

The model is saved in a MongoDB database (docker container in Data) with this information:

database: SMEUP_TUTORIAL
collection X1_X010F
fields structure:

Field	Smeup Data Format	Code field MongoDB	Type field MongoDB	Length field
Date	D8*YYMD	X1DATE	String	8
Description		X1DESC	String	50
Start at	I12	X1STIM	String	6
End at	I12	X1ETIM	String	6
Style category		X1CTGR	String	5
Category		X1STCT	String	20
Hour	NR	X1HOUR	Number	4;2

From this information we can begin to build metadata and connect kokos to the collection in the database.

2.2 Populate mongodb

You need to add this model into the mongodb container using the following steps.

Find id of the mongodb container

docker ps --filter "name=mongodb"

Run the MongoDB shell from the container itself using:

docker exec -it  [container_id] mongosh --username [username] --password [password] --authenticationDatabase admin

replace: [container_id] with the actual id value for the container; [username] and [password] with your actual username and password. The default values are respectively mongodb, root and smeup

Create the database SMEUP_TUTORIAL

use SMEUP_TUTORIAL

Create the collection X1_X010F within the database

db.createCollection("X1_X010F")

Insert multiple documents in the collection

db.X1_X010F.insertMany( [{X1DATE: '20501205', X1DESC: 'DOCTOR - MONTHLY CHECK                            ',X1STIM: '100000  ',X1ETIM: '110000  ', X1STCT: '00E20',X1CTGR: 'Health              ',X1HOUR: 1.5},{X1DATE: '20501205', X1DESC: 'GYM - YOGA LESSON                                 ',X1STIM: '113000  ', X1ETIM: '124500  ', X1STCT: '00D01', X1CTGR: 'Sport               ',X1HOUR: 1.25},{X1DATE: '20501206', X1DESC: 'CINEMA WITH LARA                                  ', X1STIM: '140000  ', X1ETIM: '160000  ',X1STCT: '53400', X1CTGR: 'Free Time           ',X1HOUR: Double(3)}]);

You can that the data has been successfully added into the db using

db.X1_X010F.find().pretty()

2.3 Creation JSON metadata file

From the previous data structure we need to define the metadata reload file, that is a JSON file with the following structure:

{
  "name": "",                 //name of the logical/physical file,
  "tableName": "",            //name of the physical ref. file,
  "recordFormat": "",         //name record format,
  "fields":[
    {  // String field
      "fieldName": "",        //name of the field,
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType/",
        "length": 0,          //length of string field
      }
    }, { // Numeric field
      "fieldName": "",        //name of the field,
      "type":{
          "type":"com.smeup.rpgparser.interpreter.NumberType",
          "entireDigits": 0,  //total number of digit,
          "decimalDigits": 0, //digits of decimal part = entireDigits - digits of integer part,
          "rpgType": ""       //"P"|"S"
        }
    }],
  "accessFields":[]           // Access Fields for logical file, empty for physical
}

For our tutorial you need to create two metadata files in the /kokos-dsl/RELOAD_METADATA folder called X1_X010F and X1_X010L, which will be the physical and logical file respectively. In X1_X010F copy the following code block:

X1_X010F.json
{
  "name":"X1_X010F",
  "tableName":"X1_X010F",
  "recordFormat":"X1_X01R",
  "fields":[
    {
      "fieldName":"X1DATE",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType",
        "length":8
      }
    },
    {
      "fieldName":"X1DESC",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType",
        "length":50
      }
    },
    {
      "fieldName":"X1STIM",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType",
        "length":6
      }
    },
    {
      "fieldName":"X1ETIM",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType",
        "length":6
      }
    },
    {
      "fieldName":"X1STCT",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType",
        "length":5
      }
    },
    {
      "fieldName":"X1CTGR",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.StringType",
        "length":20
      }
    },
    {
      "fieldName": "X1HOUR",
      "type":{
        "type":"com.smeup.rpgparser.interpreter.NumberType",
        "entireDigits": 4,
        "decimalDigits": 2,
        "rpgType": "P"
      }
    }
  ],
  "accessFields":[]
}

Do the same for X1_X010L, but adjust the name field with the new file name, and change the accessFields to the following:

{
  "name":"X1_X010L",
   [...]
  "accessFields":["X1DATE"]
}

2.4 Connection database to environment

To connect MongoDB collections to Kokos, you need to edit the configuration yaml files:

define the connection with MongoDB in the data_source_definition.yaml file:

data_structure_definition.yaml
tutorial_db_mongodb:
  type: DOCUMENT_DATABASE
  description: "MongoDB Database for Tutorial RPGLE Smeup Service"
  uri: "mongodb://[user]:[password]@[name_docker_mongo]:[port]/SMEUP_TUTORIAL?authSource=admin"
  database: SMEUP_TUTORIAL

associate physical and logical collections/files in table_definition.yaml file:

table_definition.yaml
tables:
  # MongoDB Database for tutorial RPGLE
  - names:
    - X1_X010F
    - X1_X010L
    dataSourceId: tutorial_db_mongodb