Writing your own Simple Object Access Protocol (SOAP) message header handler may be necessary in some instances. In this tutorial, I use a security header block to give a high-level view of the necessary changes when writing a SOAP message handler.
Getting into the pipeline
First you must modify the pipeline's eXtensible Markup Language (XML) configuration file for CICS to invoke the message handler. Listed below is CICS' sample Web service provider pipeline with a couple of highlighted alterations.
[IMAGE]
Click to enlarge.
The tag signals the beginning of the header processor definition, which is followed by the program name. Following the name space definition is the tag, in green, that tells CICS the type of header block the handler processes. This will make more sense later when we see an example of the input message.
The tag controls when CICS calls t...
To continue reading for free, register below or login
To read more you must become a member of SearchDataCenter.com
he handler. A value of "false" or "0" tells CICS to call the handler if the incoming message contains a "Security" header block. CICS will call the message hander for every incoming request if the tag is set to "True" or "1."
The tag terminates the definition for header program SECHEADR. Other processors may follow up until the tag.
Example SOAP request header block
The message handler has a couple of options for accessing the inbound message. Container DFHRESPONSE holds the entire message. DFHHEADER contains the header block pertinent to header processor CICS called.
Below is a sample header block for Security. I elided the name space URL's to save room.
[IMAGE]
Click to enlarge.
This is where we get to the hard part. As you can tell from the above example, XML in general and SOAP in particular are very verbose. Text-based messages containing self-defining fields are fine for passing information between disparate platforms. However, they play into one of the mainframe's weaknesses, string processing. Handling long messages in Assembler is relatively fast and cheap, but difficult. Other languages, such as PL/1, can parse text deftly, but with the performance penalty inherent in all higher level languages. The good news is that IBM may introduce an XML specialty engine -- although we'll just have to wait for CICS to support it.
As you've probably noticed, each SOAP tag begins with a less than sign ("<"), followed by a label. Following them are attributes consisting of name-value pairs that mean something to the process parsing the message. The tag ends with a greater than sign (">"). Following the starting tag is the content the tag describes. The end of the content is marked by a lesser than sign followed by a slash ("
SOAP is hierarchical, as tags are nested inside of each other. In fact, some tags are only valid nested in other tags or invalid if they appear in the wrong part of a message.
The catch to processing any header is not to be too specific or too vague. Looking for too specific of a string or, worse, assuming a given value, will always be at a certain offset and will likely break the header processing program any time the environment changes. On the other hand, too vague of a search may miss or misinterpret part of the message. This type of processing runs the risk of producing errors that are hard to debug.
I've highlighted a couple of strings in the above example. The first highlight shows the beginning of the header block CICS fished out of the message into container DFHHEADER. Note that the string "Security" matches the localname attribute in the pipeline configuration file.
Way down deep into the header I highlighted the user ID and password. Don't be fooled by the short tag attributes. I substituted three periods for some very long URLs that describe how to handle the credentials. The long attributes would be funny if it weren't someone's job to wade through the message to find the needed information.
Processing the header block for user credentials
This brings us to my ignorant-of-details, crossed-fingers, hack-at-it-until-it-works algorithm.
- Look for "" because attributes may be present.
- Scan for "" to find the beginning of the user ID element. In this case I include the greater than sign at the end of the tag, because without it the scan might stop at the "
- Look for "
" to find the end of the user ID element. With the beginning and ending of the content I can calculate the length of the user ID and copy it into working storage.
- Next, look for "" because of the attributes included in the tag.
- Skip all the attributes and look for the ">" at the end of the leading tag to end up at the beginning of the password.
- From the end of the leading tag I would look for "
This just goes to show what happens when you turn a systems programmer loose on something like SOAP. I made a lot of assumptions and did a less than vigorous parsing of a complicated message. But it works. For now.
ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
What did you think of this feature? Write to SearchDataCenter.com's Matt Stansberry about your data center concerns at mstansberry@techtarget.com.
