Create the client module

Create a client app that interacts with the Genero Web service through calls to functions in the stub file.

It is assumed you have generated the stub file.

Create the client app that accesses the Genero BDL web service created in Create a web service module.

In this task you create a module that will call functions the previously generated stub file.

In this task you also create the client form used to interact with the service.

Steps

  1. Create your client app module. For example, create a file named mywsclient.4gl
  2. Import the clientstub module:
    IMPORT FGL clientstub
  3. Add the MAIN block.
    In the MAIN / END MAIN block:
    • We define five modular variables; the first two of these are based on record types in the client stub.
      • A variable based on the customer record type (custinfoType) we use to display the record.
      • A variable for customer keys based on the array type (getCustomerRecordKeysResponseBodyType) we use for the navigation of customer records.
      • A variable (idx) we use to index the customer key array.
      • A variable (WStatus) we use to return the execution status from calls to the Web service.
      • A variable (rets) we use to handle messages returned in the update and delete function calls to the Web service.
    • Open the custform form file with OPEN FORM / DISPLAY FORM.
    • We call the getCustomerRecordKeys() function to fill an array with customer ids from the Web service.
    • We call the getCustomerById function to get the first customer and display some fields.
    • We create a MENU dialog with buttons that activate calls to create, read, update, and delete customers. We handle the activation of the navigation buttons (First, Previous, etc.) in the call to in the setupDialog() function in the BEFORE MENU block and in each action block.
    DEFINE wsstatus, rets STRING
    DEFINE p_cust_keys clientstub.getCustomerRecordKeysResponseBodyType
    DEFINE p_cust clientstub.custinfoType
    
    DEFINE idx INT
    
    MAIN
        OPTIONS INPUT WRAP, FIELD ORDER FORM
        OPEN FORM f FROM "custform"
        DISPLAY FORM f
        CALL clientstub.getCustomerRecordKeys() RETURNING wsstatus, p_cust_keys
        IF p_cust_keys.getLength() > 0 THEN
            LET idx = 1
            CALL clientstub.getCustomerById(p_cust_keys[idx])
                RETURNING wsstatus, p_cust
            DISPLAY BY NAME p_cust.cust_num,
                p_cust.cust_fname,
                p_cust.cust_lname,
                p_cust.cust_email
        ELSE
            LET idx = 0
        END IF
        MENU "MENU"
            BEFORE MENU
                CALL setupDialog(DIALOG)
            ON ACTION first
                IF p_cust_keys.getLength() > 0 THEN
                    LET idx = 1
                    CALL getCustomer(p_cust_keys[idx])
                    CALL setupDialog(DIALOG)
                END IF
            ON ACTION previous
                IF idx > 1 THEN
                    LET idx = idx - 1
                    CALL getCustomer(p_cust_keys[idx])
                    CALL setupDialog(DIALOG)
                END IF
            ON ACTION next
                IF idx < p_cust_keys.getLength() THEN
                    LET idx = idx + 1
                    CALL getCustomer(p_cust_keys[idx])
                    CALL setupDialog(DIALOG)
                END IF
            ON ACTION last
                IF p_cust_keys.getLength() > 0 THEN
                    LET idx = p_cust_keys.getLength()
                    CALL getCustomer(p_cust_keys[idx])
                    CALL setupDialog(DIALOG)
                END IF
            ON ACTION update ATTRIBUTES(TEXT = "Update customer")
                IF p_cust.cust_num > 0 THEN
                    DISPLAY "Updating customer ..." TO info
                    CALL updateCustomer(p_cust.cust_num)
                    CALL setupDialog(DIALOG)
                END IF
            ON ACTION delete ATTRIBUTES(TEXT = "Delete customer")
                IF p_cust.cust_num > 0 THEN
                    DISPLAY "Deleting customer ..." TO info
                    CALL deleteCustomer(p_cust.cust_num)
                    CALL setupDialog(DIALOG)
                END IF
            ON ACTION create ATTRIBUTES(TEXT = "Create customer")
                DISPLAY "Creating customer ..." TO info
                CALL createCustomer()
                CALL setupDialog(DIALOG)
            COMMAND KEY(INTERRUPT) "Exit"
                EXIT MENU
        END MENU
    END MAIN
  4. Add a function to handle the navigation in the Menu dialog
    This function is called by the dialog control blocks to enable/disable the actions depending on the context:
    FUNCTION setupDialog(d ui.Dialog)
        DEFINE row_count INTEGER
        LET row_count = p_cust_keys.getLength()
        CALL d.setActionActive("first", row_count > 0 AND idx > 1)
        CALL d.setActionActive("previous", row_count > 0 AND idx > 1)
        CALL d.setActionActive("next", row_count > 0 AND idx < row_count)
        CALL d.setActionActive("last", row_count > 0 AND idx < row_count)
        CALL d.setActionActive("update", row_count > 0)
        CALL d.setActionActive("delete", row_count > 0)
    END FUNCTION
  5. Add a function to create a customer (copy and paste the code below)
    In this function:
    • We define two variables:
      • A variable based on the customer record type (custinfoType) defined in the client stub
      • A variable to return the customer id (p_key) created by the Web service database.
    • We create an INPUT BY NAME dialog to handle the user interaction.
    • We call the createCustomer function defined in the client stub.
    • We check the wsstatus variable returned after the execution of the call in the CASE / END CASE block.
      • If wsstatus indicates success (C_SUCCESS),
        • We append the key (p_key) returned to the keys array and adjust the index (idx) to the length of the array.
        • We call the getCustomer function using the customer id (p_key) to display the customer record in the form.
      • If wsstatus indicates an error, we handle these possible causes:
        • A user level error (C_USERERROR): we reference the variable (userError) defined in the client stub to display details in the form.
        • A server error: we reference the variable (wsError) defined in the client stub to display details in the form.
    FUNCTION createCustomer()
        DEFINE p_cust_create clientstub.custinfoType
        DEFINE p_key INTEGER
        INITIALIZE p_cust TO NULL
        CLEAR FORM
        LET int_flag = FALSE
        INPUT BY NAME p_cust.cust_fname, p_cust.cust_lname, p_cust.cust_email
            ATTRIBUTES(UNBUFFERED)
            AFTER INPUT
                IF int_flag THEN
                    EXIT INPUT
                END IF
                LET p_cust_create.cust_fname = p_cust.cust_fname
                LET p_cust_create.cust_lname = p_cust.cust_lname
                LET p_cust_create.cust_addr = p_cust.cust_addr
                LET p_cust_create.cust_email = p_cust.cust_email
                LET p_cust_create.cust_yts = NULL -- Done in server code
                CALL clientstub.createCustomer(p_cust_create)
                    RETURNING wsstatus, p_key
                CASE wsstatus
                    WHEN clientstub.C_SUCCESS
                        DISPLAY SFMT("Created customer %1 primary key: [%2]",
                                p_cust.cust_lname, p_key)
                            TO info
                        CALL p_cust_keys.appendElement()
                        LET idx = p_cust_keys.getLength()
                        LET p_cust_keys[idx] = p_key
                        CALL getCustomer(p_key)
                    WHEN clientstub.C_USERERROR
                        DISPLAY SFMT("Bad request (user error):  %1  [%2]",
                                wsstatus, clientstub.userError.message)
                            TO info
                        CONTINUE INPUT
                    OTHERWISE
                        DISPLAY SFMT(" Internal error: %1, [%2]",
                                wsstatus, clientstub.wsError.description)
                            TO info
                END CASE
        END INPUT
    END FUNCTION
  6. Add a function to get a customer's details (copy and paste the code below)
    In this function:
    • We call the getCustomerById function (defined in the client stub to return the details for the customer id specified in the parameter.
    • We check the wsstatus variable after the execution of the call in the CASE / END CASE block.
      • If wsstatus indicates success (C_SUCCESS), we display the customer record returned in p_cust in the form.
      • If wsstatus indicates an error, we handle these possible causes:
        • A user level error (C_USERERROR): we reference the variable (userError) defined in the client stub to display details in the form.
        • A server error: we reference the variable (wsError) defined in the client stub to display details in the form.
    FUNCTION getCustomer(customer_id INTEGER)
        CALL clientstub.getCustomerById(customer_id) RETURNING wsstatus, p_cust
        CASE wsstatus
            WHEN clientstub.C_SUCCESS
                DISPLAY BY NAME p_cust.cust_num,
                    p_cust.cust_fname,
                    p_cust.cust_lname,
                    p_cust.cust_email
            WHEN clientstub.C_USERERROR
                DISPLAY SFMT(" Bad request (user error):  %1 [%2]",
                        wsstatus, clientstub.userError.message)
                    TO info
            OTHERWISE
                DISPLAY SFMT(" Internal error: %1 [%2]",
                        wsstatus, clientstub.wsError.description)
                    TO info
        END CASE
    END FUNCTION
  7. Add a function to update a customer's details (copy and paste the code below)
    In this function:
    • We define a variable (p_cust_backup) based on the customer record type (custinfoType) defined in the client stub
    • We make a copy (in p_cust_backup) of the current customer record in case the user cancels or the update fails.
    • We create an INPUT BY NAME dialog to handle the user interaction.
    • We call the updateCustomer function defined in the client stub.
    • We check the wsstatus variable after the execution of the call in the CASE / END CASE block.
      • If wsstatus indicates success (C_SUCCESS), we display information in the form.
      • If wsstatus indicates an error, we handle these possible causes:
        • A user level error (C_USERERROR): we reference the variable (userError) defined in the client stub to display details in the form.
        • A server error: we reference the variable (wsError) defined in the client stub to display details in the form.
    FUNCTION updateCustomer(customer_id INTEGER)
        DEFINE p_cust_backup, p_cust_update clientstub.custinfoType
        LET p_cust_backup = p_cust
        LET int_flag = FALSE
        INPUT BY NAME p_cust.cust_fname, p_cust.cust_lname, p_cust.cust_email
            ATTRIBUTES(UNBUFFERED, WITHOUT DEFAULTS)
            AFTER INPUT
                IF int_flag THEN
                    EXIT INPUT
                END IF
                # Note : id cannot be modified
                LET p_cust_update.cust_num = customer_id
                LET p_cust_update.cust_fname = p_cust.cust_fname
                LET p_cust_update.cust_lname = p_cust.cust_lname
                LET p_cust_update.cust_addr = p_cust.cust_addr
                LET p_cust_update.cust_email = p_cust.cust_email
                LET p_cust_update.cust_yts = NULL -- Done by server code
                CALL clientstub.updateCustomer(customer_id, p_cust_update)
                    RETURNING wsstatus, rets
                CASE wsstatus
                    WHEN clientstub.C_SUCCESS
                        DISPLAY SFMT("Updated customer %1 ", rets) TO info
                    WHEN clientstub.C_USERERROR
                        DISPLAY SFMT("Bad request (user error):  %1 [%2]",
                                wsstatus, clientstub.userError.message)
                            TO info
                        CONTINUE INPUT
                    OTHERWISE
                        DISPLAY SFMT(" Internal error: %1 [%2]",
                                wsstatus, clientstub.wsError.description)
                            TO info
                END CASE
        END INPUT
    END FUNCTION
  8. Add a function to delete a customer (copy and paste the code below)
    In this function:
    • We call the deleteCustomer function to delete the customer currently displayed.
    • We check the wsstatus variable after the execution of the call in the CASE / END CASE block.
      • If wsstatus indicates success (C_SUCCESS), we display information in the form's info field.
        • We delete the customer key from the keys array (p_body_keys) and subtract one from the index (idx), and make sure the index matches the remaining number of array elements and clear fields if there are no more rows.
      • If wsstatus indicates an error, we handle these possible causes:
        • A user level error (C_USERERROR): we reference the variable (userError) defined in the client stub to display details in the form.
        • A server error: we reference the variable (wsError) defined in the client stub to display details in the form.
    FUNCTION deleteCustomer(customer_id STRING)
        CALL clientstub.deleteCustomer(customer_id) RETURNING wsstatus, rets
        CASE wsstatus
            WHEN clientstub.C_SUCCESS
                DISPLAY SFMT("Deleted customer %1 ", rets) TO info
                CALL p_cust_keys.deleteElement(idx)
                LET idx = idx - 1
                IF idx == 0 THEN
                    LET idx = p_cust_keys.getLength()
                END IF
                IF idx > 0 THEN
                    CALL getCustomer(p_cust_keys[idx])
                ELSE
                    INITIALIZE p_cust.* TO NULL
                    CLEAR FORM
                END IF
            WHEN clientstub.C_USERERROR
                DISPLAY SFMT("Bad request (user error):  %1 [%2]",
                        wsstatus, clientstub.userError.message)
                    TO info
            OTHERWISE
                DISPLAY SFMT(" Internal error:  %1 [%2]",
                        wsstatus, clientstub.wsError.description)
                    TO info
        END CASE
    END FUNCTION
  9. Create your client form. For example, create a file named custform.per (copy and paste the code below):
    LAYOUT (TEXT="RESTful Client")
    GRID
    {
     Id:         [f1           ]
     First name: [f2                      ]
     Last name:  [f3                      ]
     EMail:      [f4                                          ]
    <G Navigation                                             >
     [b1           :b2           :b3           :b4           ]
    <                                                         >
    <G Info                                                   >
    [info                                                     ]
    [                                                         ]
    [                                                         ]
    [                                                         ]
    [                                                         ]
    [                                                         ]
    [                                                         ]
    [                                                         ]
    <                                                         >
    }
    END
    END
    
    ATTRIBUTES
    EDIT f1 = formonly.cust_num, NOENTRY, COLOR=RED;
    EDIT f2 = formonly.cust_fname;
    EDIT f3 = formonly.cust_lname;
    EDIT f4 = formonly.cust_email;
    BUTTON b1: first;
    BUTTON b2: previous;
    BUTTON b3: next;
    BUTTON b4: last;
    TEXTEDIT info=formonly.info;
    END