Conversational Web Services

We’ve all used conversational web sites: the results of our response to the first request are remembered, and influence the next.  For example,

1.    We log on to our on-line banking/we see a list of our accounts

2.    We select one of these accounts/we see a list of the most recent transactions

3.    We select a transaction/we see its details

And so on.  Such a sequence is called a “Conversation”. 

On the server (the bank’s site) our first transaction activated a web service that validated our logon credentials, and sent us a list of our accounts.  We responded by selecting an account: the 2nd transaction returns a list of the most recent transactions.  A request/response is self-contained: everything that the request needs to know must be part of the input message.  We certainly don’t have to repeat our logon, or say “Step 2”.  So how did the 2nd transaction know who we are, and where we are in the conversation?    The answer: the first response included some information that, like SAVESUM/CHECKSUM above, we never see but will be returned in Response #1 and is sent back unchanged in Request #2. 

We can create conversational web services by using ViewState when we create the web service.  “ViewState” is a record type for information that is used in this way.

  

When the message for program JSPG2V is generated, it will include COPY Vstate; because we gave this name in the Viewstate textbox: -

*# Last Updated by JAZZUSR at 8/03/2025 2:35:59 PM

*# You may edit this definition: right-click the 'WEBSERVICE' keyword of the PROGRAM statement.

COPY EMPLOYEE;

COPY Vstate;

…

Vstate is a working storage record with type VIEWSTATE, and may contain whatever data we want

*# Last Updated by JAZZUSR at 21/12/2024 12:20:56 PM

DEFINE VState VIEWSTATE DATA(

    VSName CHAR(8) VALUE 'VState',

    VCField CHAR(6) VALUE '  ',

    VSEND CHAR(2) VALUE 'XX');

DEFINE VState-Lth DATA(

    L1 INTEGER VALUE 16,

    L2 INTEGER VALUE 24);

We wrote the first definition in this copy book.   The system automatically created the 2nd, VState-Lth, containing fields L1 and L2.

A VIEWSTATE definition can only be used in a JSON Web Service.   The data that it contains will be encrypted and sent to the client in the output message.  It will be returned unchanged with the response, where it will be decrypted into record VState.  All this is handled automatically by the Client Interface: VState is kept private within the interface and not communicated to the external client.

COPY JZVSTAT;

COPY TYPES;

DEFINE MyJSv-JSPG2V SYSTEM DATA([Not in COBOL

    INPUT VARCHAR(7) VALUE 'IJSPG2V',

    OUTPUT VARCHAR(7) VALUE 'OJSPG2V',

    MType CHAR(4) VALUE 'JSON',

    Template CHAR(8) VALUE '@JSF1Upd',

    URL VARCHAR(42) VALUE 'http://localhost:9003/cics/services/JSPG2V');

DEFINE IJSPG2V SERVICE INPUT DATA(

    JZ-VIEWSTATE CHAR(24),

    Function CHAR(1) CAPS CODES(E:Enquiry,U:Update,A:Add,D:Delete)  VALUE Enquiry,

    JZ-EMPLOYEE-Skip SMALLINT VALUE 0 RANGE(0:999),

    JZ-EMPLOYEE GROUP,

        EMPNO CHAR(6) ASSIGN EMPLOYEE.EMPNO,

        FIRSTNME CHAR(12) ASSIGN EMPLOYEE.FIRSTNME,

        MIDINIT CHAR(1) ASSIGN EMPLOYEE.MIDINIT,

        LASTNAME CHAR(15) ASSIGN EMPLOYEE.LASTNAME,

        WORKDEPT CHAR(3) ASSIGN EMPLOYEE.WORKDEPT,

        PHONENO CHAR(4) ASSIGN EMPLOYEE.PHONENO,

        HIREDATE CHAR(9) ASSIGN EMPLOYEE.HIREDATE,

        JOB CHAR(8) ASSIGN EMPLOYEE.JOB,

        EDLEVEL CHAR(7) ASSIGN EMPLOYEE.EDLEVEL,

        SEX CHAR(1) ASSIGN EMPLOYEE.SEX,

        BIRTHDATE CHAR(9) ASSIGN EMPLOYEE.BIRTHDATE,

        SALARY CHAR(15) ASSIGN EMPLOYEE.SALARY,

        BONUS CHAR(15) ASSIGN EMPLOYEE.BONUS,

        COMM CHAR(15) ASSIGN EMPLOYEE.COMM,

        CURRENCY CHAR(3) ASSIGN EMPLOYEE.CURRENCY,

        DEPTMGR CHAR(5) ASSIGN EMPLOYEE.DEPTMGR,

        STARTTIME CHAR(12) ASSIGN EMPLOYEE.STARTTIME,

        Checksum CHAR(40),

        END GROUP);

DEFINE OJSPG2V SERVICE OUTPUT DATA(

    JZ-VIEWSTATE CHAR(24),

    Error VARCHAR(80),

    JZ-EMPLOYEE-ReadTo SMALLINT VALUE 0,

    JZ-EMPLOYEE-NbrReturned SMALLINT VALUE 0,

    JZ-EMPLOYEE-BrowseCount SMALLINT VALUE 0,

    JZ-EMPLOYEE (6) GROUP,

        JZ-EMPLOYEE-ReturnCode LIKE Types.ReturnCode,

        EMPNO LIKE EMPLOYEE.EMPNO ASSIGN EMPLOYEE.EMPNO,

        FIRSTNME LIKE EMPLOYEE.FIRSTNME ASSIGN EMPLOYEE.FIRSTNME,

        MIDINIT LIKE EMPLOYEE.MIDINIT ASSIGN EMPLOYEE.MIDINIT,

        LASTNAME LIKE EMPLOYEE.LASTNAME ASSIGN EMPLOYEE.LASTNAME,

        WORKDEPT LIKE EMPLOYEE.WORKDEPT ASSIGN EMPLOYEE.WORKDEPT,

        PHONENO LIKE EMPLOYEE.PHONENO ASSIGN EMPLOYEE.PHONENO,

        HIREDATE LIKE EMPLOYEE.HIREDATE ASSIGN EMPLOYEE.HIREDATE,

        JOB LIKE EMPLOYEE.JOB ASSIGN EMPLOYEE.JOB,

        EDLEVEL LIKE EMPLOYEE.EDLEVEL ASSIGN EMPLOYEE.EDLEVEL,

        SEX LIKE EMPLOYEE.SEX ASSIGN EMPLOYEE.SEX,

        BIRTHDATE LIKE EMPLOYEE.BIRTHDATE ASSIGN EMPLOYEE.BIRTHDATE,

        SALARY LIKE EMPLOYEE.SALARY ASSIGN EMPLOYEE.SALARY,

        BONUS LIKE EMPLOYEE.BONUS ASSIGN EMPLOYEE.BONUS,

        COMM LIKE EMPLOYEE.COMM ASSIGN EMPLOYEE.COMM,

        CURRENCY LIKE EMPLOYEE.CURRENCY ASSIGN EMPLOYEE.CURRENCY,

        DEPTMGR LIKE EMPLOYEE.DEPTMGR ASSIGN EMPLOYEE.DEPTMGR,

        STARTTIME LIKE EMPLOYEE.STARTTIME ASSIGN EMPLOYEE.STARTTIME,

        Checksum CHAR(40),

        DEPTNAME LIKE DEPARTMENT.DEPTNAME ASSIGN DEPARTMENT.DEPTNAME FKEY EMPLOYEE.WORKDEPT,

        END GROUP);