ijmitch / cicscors Goto Github PK

Looking at a trace, we can see:

00062 SO    WB 0432 WBRQ  *EXC* OPTIONS NOT OPTIONS *                       RET-ABCCB19C 18:30:02.7982353618 00.0000073339 =000328=
00062 QR    WB 0501 WBSR  EXIT  RECEIVE/EXCEPTION REASON(OPTIONS_NOT_ALLOWED) ATTACH_TRANSID() FAILING_PROGRAM() CONNECTION_PERSIST
                                (YES) TOKEN(2AFA6030)                       RET-ABCCB19C 18:30:02.7982397753 00.0000044135 =000329=
00062 QR    AP 4522 WBXN  *EXC* RECEIVE_ERROR                               RET-A9D583CE 18:30:02.7982404086 00.0000006333 =000330=

and then CICS links to the Web Error Program.

PG 0A01 PGLU  ENTRY - FUNCTION(LINK_URM) PROGRAM_NAME(DFHWBEP) COMMAREA(2AF9D4D0 , 000000D0) SYSTEM_AUTOINSTALL(NO)
 
              TASK-00062 KE_NUM-004D TCB-C/QR   /009B3E88 RET-ABCCDA56 TIME-18:30:02.7988260195 INTERVAL-00.0000008598      =000368=
                1-0000  00400000 0000009D 00000000 00000000  BD100000 00000000 01000100 C4C6C8E6  *. ..........................DFHW*
                  0020  C2C5D740 2AF9D4D0 000000D0 29A18D00  02000000 00000000 00000000 00000000  *BEP .9M}...}....................*
                2-0000  00D06EA6 82859783 81400002 00420000  C1E6C2C1 000002FA 2AF9B878 000000E7  *.}>wbepca ......AWBA.....9.....X*
                  0020  2AFA7008 00000120 0CF94BF1 F4F54BF1  F7F84BF5 F2404040 08F94BF2 F04BF54B  *.........9.145.178.52   .9.20.5.*
                  0040  F0404040 40404040 E3C8D9C5 C1C4C1C3  00000000 00000000 00000000 00000000  *0       THREADAC................*
                  0060  00000000 00000000 00000195 00000000  00000000 00000000 00000000 D5000000  *...........n................N...*
                  0080  0CF94BF1 F4F54BF1 F7F84BF5 F2404040  40404040 40404040 40404040 40404040  *.9.145.178.52                   *
                  00A0  40404040 40404040 08F94BF2 F04BF54B  F0404040 40404040 40404040 40404040  *        .9.20.5.0               *
                  00C0  40404040 40404040 40404040 40404040

Unfortunately, this program is not provided with much HTTP request information, but we can see that the field wbep_message_number (offset x'14' in the commarea) is x'2FA' = 762. DFHWB0762 is unique to the detection of an OPTIONS request that CICS doesn't know how to handle.

The description of the wbep_response_ptr field says...

On input, pointer points to a block of storage containing the default HTTP response for this error. CICS provides only a default response for HTTP requests. The default response is a complete HTTP response, including a status line, HTTP headers and message body. On output, this pointer either points to the same block of storage, containing the original or a modified version of the default response, or a pointer to a new block of storage containing a replacement response. If DFHWBEP successfully uses the EXEC CICS WEB SEND command to create a new response and sends it to the web client, CICS ignores and discards the HTTP response in the block of storage. Otherwise, the response in the block of storage is sent to the web client.

It sounds from that as if it might be possible to code some handling of OPTIONS into DFHWBEP. For example, if DFHWBEP could use the EXEC CICS WEB EXTRACT PATH command to discover the resource specified in the HTTP request, and then EXEC CICS WEB SEND a suitable, good reply to the request, then we might need to enhancement to CICS!

Actually, we might ignore the message number in the commarea and use EXEC CICS WEB EXTRACT HTTPMETHOD to know we're trying to handle an OPTIONS request.

A mechanism along the lines of the Web Error Program might be the most appropriate - in the same way that Liberty asks for the CORS information to be part of the server configuration, this program would be a way to select the information to be returned as a response to OPTIONS.

Define a new URM, say DFHWBOPT, which has the responsibility to respond to the OPTIONS request. CICS could make EXEC CICS WEB EXTRACT commands work in this URM so that it would be possible to find out the resource being queried (there would be no need to query for the HTTP verb since CICS would only drive DFHWBOPT for an OPTIONS request).

Your DFHWBOPT program then just has to construct the reply... something that DFHWBEP is already tasked with. You would be free to derive that anyway you like:

• code it in the program,
• look it up in a file or database,
• use the DOCUMENT API,
• ...

Should CICS demand a DFHWBOPT program? If it does, everyone needs to have one. The alternative would be to default back to the existing behaviour if there's no DFHWBOPT program definition installed.

One alternative I don't think is appropriate would be to make some use of the URIMAP - CICS could perform the normal matching on a URIMAP and then have some URI-specific behaviour. But what would this be?

The data to be returned wouldn't really fit into a Resource Definition attribute. Perhaps we could make the attribute a DOCTEMPLATE name... but how would we substitute any symbols in that template? Or a zFS file? Path and name or just name and we assume a path?

Basic principles

Deciding what to return in response to an OPTIONS request is not really a job for an application to handle.

I've refactored the options into separate issues for discussion:

• New URM - issue #4
• Content from zFS file inferred from URIMap name - issue #6
• Content from zFS file defined via new URIMap attribute - issue #5

All options would suppress the DFHWB0762 message.

Just for completeness, I'll describe another option...

What if we decided that handling an OPTIONS request was just another obligation for the app? It would have to be opted into via a URIMAP option (handleoptions?), but once opted into then the app could do EXEC CICS WEB EXTRACT HTTPMETHOD in order to distinguish OPTIONS from GET, POST etc.

This idea is to match the resource against the URIMap and then look for a zFS file in a given directory with the same name as the URIMap.

For example, if you have URIMaps called payroll and HRApps, then the CORS content to be returned would be put in individual files with those names in a directory called "ussconfig/web/optionsresponses".

ie. "ussconfig/web/optionsresponses/payroll" and "ussconfig/web/optionsresponses/HRApps".

If there was no file with the same name as the URIMap, then the existing hardcoded 'not allowed' response would be returned.

Comment here with reasons that CORS would be important for CICS to support.