Breakdown of the CICS application IBM-CICS

This section describes the details of the Change of Address application.

1. Overview of the approach to CICS application development

The CICS application was initially developed as a CICS/BMS menu driven system. This enabled our developers, who were new to CICS Web services, to develop and test a traditional application while they learned the new WD/z tooling. By using careful application structuring, we kept the business logic well separated from the BMS presentation logic. This is the key to easy transition to a CICS Web service using the CICS Web Services Assistant.

“Modern Web services development tools” we employed the newly released WebSphere Application Developer for Systems z V7 to create and edit the BMS maps. This facility is a great benefit to the traditional BMS developer as it provides true drag and drop BMS map creation. BMS maps are edited directly out of mainframe PDS(E) libraries. Likewise, JCL editing and job-submission is friendly and efficient. The default LPEX editor provides more of a Windows Notepad-like editor. We say default here because there is a significant number of editor styles available. If desired, an ISPF- like editor is available under Window → Preferences: LPEX. The editors also provide colored parsing and syntax error notifications as you type.

LPEX Editor choices

LPEX Editor choices

Job output is readily available under the JES key of the Remote Systems pane:

Accessing Job output

Accessing Job output

WD/z also contains a 3270 emulator, allowing full window-based testing of applications as they develop.

A 3270 screen in WD/z

A 3270 screen in WD/z

What this means is that the CICS developer is freed from the need to continually switch between 3270 mainframe sessions and WD/z in the edit-compile-test sequence.

During development, as simple functions completed testing as a BMS application, we created the WSDL & WSBind using the DFHLS2WS utility. We carried out simple testing of these generated Web services initially using the Web Services Explorer feature that is part of the underlying RAD software.

The data layer is typically insulated from the business layer by a standard interface such as SQL. This is good practice for many reasons including the following:

  • Applications can have a multitude of presentation interfaces. Perhaps a Web interface as well as a 3270 interface.
  • Organizations tend to have graphic designers produce presentation interfaces, particularly for Web applications. This staff should not have to worry about business or data logic.
  • Independence of presentation implementation from business or data implementation. Indeed, they might be on different platforms.
  • Components can be upgraded independently.
  • The usual non-functional reasons such as reliability, scalability, security, robustness, recoverability.

Keeping these three layers separate is easy when developing from the ground up. Keeping all data in a database system, then ensuring separation of the BMS calls from the business logic is then fairly straightforward.

Importantly, the interface to the business logic is then a mapped data structure of input and output parameters. For smaller structures (< 32Kb), we use CICS COMMAREAS to contain this structure. But the facility is present in CICS to handle larger structures using containers and channels. Given the simplicity of our application, we mostly use COMMAREAS.

2. Overview of the application

Application design of CICSWSAP

Application design of CICSWSAP

3. Database schema

The following tables are defined on our DB2 for z/OS system:

Database relationships

Database relationships

4. Application schema

This section explains the application schema.

Programs

Programs have the following name structure:

ITSOxxnn

Where: xx indicates the function, for example CA is Corporate Acknowledgements and nn is a two-digit number of the program.

Typically nn=01 is the initial program that displays the first BMS menu of the function. nn=02 retrieves the BMS map and sets up the COMMAREA to call the business function and then displays the results. nn=03, 04 ... are the business layer programs of this particular function.

Transactions

Transactions are identified as follows: ITnn

where nn=00, 01 ...

The only transaction worthy of individual mention is IT00 - the main menu transaction

Map sets/maps

Map sets are identified as follows: ITSOMSn

where n=0, 1 ...

WMQ queues

WMQ queues are prefixed with CICSWSAP. The main publication queue is called CICSWSAP.PUBLICATION.QUEUE, from which the pub/sub function distributes messages to subscriber queues. These are typically prefixed CICSWSAP.ADDRESS.CHANGE.

5. Application functions

Following are the major business functions of our application. There are some other minor functions and test harnesses included in the source.

Get HashDescription

Return a hash key calculated from the full address supplied in the input parameters. This key should be unique for the given parameters.

Availability

Publicly available as a Web service call.

Logic

Calculate hash value from string AddressLine1 + AddressLine2 + Suburb + State+ Postcode.

Algorithm is known as djb2. Quick, efficient with a good spread of results.

Input parameters

Address input parameters must be in the standard format provided by the StandardAddress function.

Table: GetHash (ITSOGH03) input parameters

Table: GetHash (ITSOGH03) input parametersTable: GetHash (ITSOGH03) input parameters

Output parameters

Table: GetHash (ITSOGH03) Output Parameters

GetHash (ITSOGH03) Output Parameters

Return codes

RC=0 mean OK.

Only returns RC=0. Might fail if input parms are in read-protected storage.

Corporate client registration

Description

Register a corporate client. Note, this does not register a pub/sub subscription, although such functionality could easily be built into this program.

Availability

Internal only.

Input parameters

Table: CorpClient (ITSOCC03) input parameters

Table: CorpClient (ITSOCC03) input parameters

Output parameters

Table CorpClient (ITSOCC03) output parameters

Table CorpClient (ITSOCC03) output parametersTable CorpClient (ITSOCC03) output parameters

Return codes

RC=0 means OK. CorpClient Added.
RC=1 means SQL INSERT to CORPCLIENTS table failed. See Reason.
RC=2 means SQL SELECT to obtain CorpClient ID failed. See Reason.

Logic

  • Check input parameter
  • INSERT new client into CORPCLIENTS table
  • If INSERT failed
  • Set RC=1, Reason=SQLCODE, SQLSTATE
  • Return
  • SELECT row just entered to get generated CorpClient ID
  • If SELECT failed
  • Set RC=2, Reason=SQLCODE, SQLSTATE
  • Return
  • Set RC=0, CorpClientId, Reason
  • Return

Add address

Description

Add an address to DB2 Address table or return an error code. This function is called internally by Add/Update Address only, but it is a significant function factored out of the Add/Update Address. For this reason, this program is called ITSOUA03, not ITSOAA03.

Availability

Internal only.

Input parameters

Table: AddAddress (ITSOUA03) input parameters

AddAddress (ITSOUA03) input parametersAddAddress (ITSOUA03) input parameters

Output parameters

Table : AddAddress (ITSOUA03) output parameters

AddAddress (ITSOUA03) output parameters

Return Codes
RC=0 mean OK
RC=1 means Address Already exists
RC=2 means SQL Failure

Logic>

  • Check input parameters
  • Call GetHash to get HashCode for address
  • INSERT address into ADDRESS table
  • If INSERT failed
  • If SQLCode indicates address already exists
  1. Set RC=1, Reason=Address Already Exists
  2. Set AddressHash
  3. Return
  • Otherwise there was an SQL Error
  1. Set RC=2, Reason=SQLCODE, SQLSTATE
  2. Set AddressHash=0
  3. Return
  • INSERT was OK:
  1. Set RC=0
  2. Set AddressHash
  3. Return

Add/update address
Description
Add or update the address of a relocatee in the local DB2 Names and Address tables. Post notification to broker of update.

Availability
Internal only.

Input parameters

Table: Add/update address (ITSOUA04) input parameters

Add/update address (ITSOUA04) input parameters

Output Parameters

Table :Add/update address (ITSOUA04) Output Parameters

Add/update address (ITSOUA04) Output Parameters

Return Codes

RC=0 means OK
RC=1 means Insert Name Failed - SQL error
RC=2 means Name already exists when trying to do an Add
RC=3 means Current and new address are the same
RC=4 means call to AddAddress Failed
RC=5 means Supplied AddressHash didn't match existing address for name
RC=6 means Cannot update non-existent name entry
RC=7 means Notification to broker failed (MQ error)

Logic

  • Attempt to retrieve NAMES table entry for the person named
  • If there was a SQL error, other than no NAMES entry
  • Set RC=2 Reason=SQLCODE SQLSTATE
  • Return
  • If there was no NAMES entry
  • Call AddAddress to add the address
  • If call failed (“Address already exists” is not a failure)
  1. Set RC=4, Reason=AddAddress reason
  2. return
  • Insert new entry into NAMES table with AddressHash just returned
  • If INSERT failed
  1. Set RC=1, Reason= SQLCODE SQLSTATE
  2. Perform rollback
  3. Return
  • SELECT the row just added to retrieve the NAMEREF generated
  • If SELECT failed
  1. Set NameRef = -1
  2. Continue on. Not a big problem.
  • MQPUT AddressHash on to publication queue
  1. If MQPUT failed

Set RC=7, Reason= MQRC
Perform rollback
Return

  • NAMES entry already exists
  • Call AddAddress to add the address
  • If call failed (“Address already exists” is not a failure)
  1. Set RC=4, Reason=AddAddress reason
  2. return
  • Update NAMES db entry using new address & hashcode
  • If UPDATE failed
    1. Set RC=1, Reason= SQLCODE SQLSTATE
    2. Perform rollback
    3. Return
    • MQPUT old AddressHash on to publication queue
    • If MQPUT failed
  • Set RC=7, Reason= MQRC
    Perform rollback
    Return

  • Set RC=1, Reason=OK, AddressHash & NameRef

Standard address

Description

Format addresses in a standard way. This allows different organizations to compare addresses in standard fashion. There are whole application suites in existence to perform these sorts of functions. This is not critical to our test application but it would be in a real situation. There might even be public Web services in existence that already do this.

Availability

Publicly available as a Web service call.

Input parameters

Table: StandardAddress (ITSOSA03) input parameters

StandardAddress (ITSOSA03) input parameters

Output parameters

Table: StandardName (ITSOSN03) output parameters

StandardName (ITSOSN03) output parameters

Return Codes

RC=0 means OK
RC=1 means Not OK

Logic

  • Check input parameters
  • Format Name

Standard address

Description

Format addresses in a standard way. This allows different organizations to compare addresses in standard fashion. There are whole application suites in existence to perform these sorts of functions. This is not critical to our test application but it would be in a real situation. There might even be public Web services in existence that already do this.

Availability

Publicly available as a Web service call.

Input parameters

Table: StandardAddress (ITSOSA03) input parameters

StandardAddress (ITSOSA03) input parameters

Output parameters

Table: StandardAddress (ITSOSA03) output parameters

StandardAddress (ITSOSA03) output parameters

Return Codes

RC=0 means OK
RC=1 means Not OK

Logic

  • Check input parameters
  • Format name

List corporate acknowledgements

Description

Return a list of the corporate clients that were sent the new address of the relocatee. This does not mean they actually changed this in their own databases, but they should have.

Availability

Restricted availability. Should be available to relocatee perhaps by a secured Web page.

Input parameters

Table: CorpAcknowledgements (ITSOCA03) input parameters

CorpAcknowledgements (ITSOCA03) input parameters

Output Parameters

Table: CorpAcknowledgements (ITSOCA03)output parameters

CorpAcknowledgements (ITSOCA03)output parameters

Return Codes

RC=0 means OK
RC=1 means Bad input parameter
RC=2 means SQL Error

Logic

  • Validate input parms
  • If parms invalid
  • Return RC=1 Reason="Bad Paramater: " + parm in error
  • Query Audit table for all the corp-clients who were told of new address
  • If query failed
  • Return RC=2 Reason="Query Failed: " + SQL Reason
  • Otherwise
  • Return RC=0 Reason="OK" with results


Face Book Twitter Google Plus Instagram Youtube Linkedin Myspace Pinterest Soundcloud Wikipedia

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-CICS Topics