IBM Z and LinuxONE IBM Z

Expand all | Collapse all

Support for Path Parameters in URIMAP Path Attribute

  • 1.  Support for Path Parameters in URIMAP Path Attribute

    Posted Fri September 17, 2021 10:21 AM

    We are encountering an issue in our CICS Environment (v5.4) with APIs running against our Liberty Server in CICS.

    Specifically we are defining a URIMAP as an application entry point where the URIMAP resource is defined with USAGE(JVMSERVER) using Liberty.

    We are using Path Parameters in the URI to pass an identifier into the API call:

    DEFINE URIMAP(SU622WS1) GROUP(WSGRESP)

           DESCRIPTION(WSG Endpoint)

           USAGE(JVMSERVER) SCHEME(HTTP) HOST(*)

           PATH(/customer/{id})

           TRANSACTION(22SU)

    As the characters { and } are not supported in the Path attribute, we are using hexadecimal escape sequences as per the CICS documentation

    https://www.ibm.com/docs/en/cics-ts/5.4?topic=resources-urimap-attributes

    The PATH attribute is specified in mixed case, and the case is preserved in the URIMAP definition. The PATH attribute must contain only the characters that are allowed in URIs. Specifically, the characters < > # % " { } | \ ^ [ ] ` and embedded blanks must be excluded (except that % is allowed when it introduces a valid hexadecimal escape sequence; that is, when it is followed by two valid hexadecimal digits in uppercase or lowercase). The tilde character ~ cannot be specified in CICS and must be replaced by the corresponding hexadecimal escape sequence (%7E). CICS validates the use of characters at define time.


    This results in the following URIMAP definition:

    DEFINE URIMAP(SU622WS1) GROUP(WSGRESP)
           DESCRIPTION(WSG Endpoint)
           USAGE(JVMSERVER) SCHEME(HTTP) HOST(*)
           PATH(/customer/%7Bid%7D)
           TRANSACTION(22SU)

     

    Based on the CICS documentation, this should be supported.  However at run time the process invoked by the API call runs under the default Liberty transaction CJSA indicating that it was unable to match to the URIMAP defined above.

    This does work using the wildcard character * in the PATH attribute:

    DEFINE URIMAP(SU622WS1) GROUP(WSGRESP)

           DESCRIPTION(WSG Endpoint)

           USAGE(JVMSERVER) SCHEME(HTTP) HOST(*)

           PATH(/customer/*)

           TRANSACTION(22SU) 

    At runtime the API executes under Transaction 22SU.

    URIMAPs are limited to a single wildcard entry, and it must be the end of the path. This means URIs such as /customer/{id}/orders/{oid} cannot be represented as /customer/*/orders/* in the URIMAP, but only /customer/*

    The downstream effect is that in circumstances where multiple path parameters exist, only a top level single match can occur. So if a custom transaction code is required, then /customer/{id}/orders/{oid} must run under the same transaction code as /customer/{id}.  This is not a desirable outcome.


    Liberty happily supports the brace syntax for path parameters, but CICS does not in the URIMAP definition, despite compliance with the hexadecimal escape sequence.

    Looking to understand if this is a bug in CICS or a design feature? Has anyone else successfully used Path Parameters in the URIMAP Path Attribute? 



    ------------------------------
    Ryan Johnson
    ------------------------------


  • 2.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted Mon September 20, 2021 10:37 AM
    I have two thoughts.

    First,  it's likely that your choice of %7B and %7D simply don't match the transformation that was done from the original ASCII encoding.  I've found several references for EBCDIC code page 037.  All of them document %C0 and %D0 as the { and } characters.  Not all of them document %7B and %7D. (In fact, %7B and %7D *are* the curly brackets in ASCII.)  You might try %C0 and %D0 and see if you get a match.

    Second, it's possible to use your own web analyzer program to select the task attributes when there is no match to an installed URIMAP.  See https://www.ibm.com/docs/en/cics-ts/5.6?topic=programs-writing-analyzer-program for documentation on how to write and implement a web analyzer program.

    ------------------------------
    Leigh Compton
    ------------------------------



  • 3.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted Tue September 21, 2021 01:57 AM
    Does this explain your issue? https://meta.stackexchange.com/questions/79057/curly-brackets-in-urls

    ------------------------------
    Michael Buckley
    ------------------------------



  • 4.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted 11 days ago
    Hi Leigh,

    Thanks for your feedback. Upon further analysis, the curly braces representing the path parameter are a design time issue, populated by actual values when executing API calls.
    So the issue we are actually trying to overcome is the wildcard capabilities for the Path Parameter i.e. using * in the Path.  The CICS documentation stated that URIMAPs are limited to a single wildcard entry, and it must be the end of the path. This means URIs such as /customer/{id}/orders/{oid} cannot be represented as /customer/*/orders/* in the URIMAP, but only /customer/*

    So I am looking to understand how others have dealt with the need to insert  a wildcard into the middle of a URI Path, as per the example above.


    ------------------------------
    Ryan Johnson
    ------------------------------



  • 5.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted 30 days ago
    I have not done this for a while and I currently do not have access to a CICS system, but when I was trying to get pure sockets to work I put COBOL DISPLAY statements in the CICS programs. The DISPLAYS showed up on one of the CICS output files. You can use whatever is the equivalent in the language that you are using. That way you know exactly what is going in. Also, PRINT what happens after the translation. I was thinking that one way to trick the system into accepting your inputs would be to enclose the entire string in double quotes "". Good luck, sounds like an interesting problem. My educated guess is the translation program was not set up to do what you want, but you may be able to get around it. Maybe create your own translation program. 

    Patrick J. Hagan
    305 East 40th Street Apt. 20E
    New York, N.Y. 10016
    (917) 495-8789





  • 6.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted 29 days ago
    Ryan,

    An easy way to see exactly what is coming in from a client is to turn on AUXTRACE and look to see exactly what is being sent.  Make sure you have SO=1-2 and the SIT par CONFDATA=SHOW.

    The trace entries SO0201 and SO0202 will show the entire HTTP request and response.  This way you can at least verify you are getting what they claim to be sending.

    Ezriel Gross
    Rocket Software.

    ------------------------------
    Ezriel Gross
    Rocket Software
    Waltham NJ
    17816842672
    ------------------------------



  • 7.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted 8 days ago
    Edited by Leigh Compton 8 days ago
    Ryan, from your explanation, I don't think you need two wildcards.  But let's confirm what you want to do.

    If your URIMAP will direct processing to the same JVMSERVER with the same CICS transaction ID, regardless of which customer number is in the URL, then a simple URIMAP resource definition with PATH attribute of /customer/* would work just fine.


    Once your target program is attached, it can retrieve the customer number and order number from the URL and then use those to look up the details necessary to perform the business processing.

    Note that for USAGE(JVMSERVER), the only values being set by the URIMAP are the CICS transaction ID and possibly the user ID that the task is to run under. (The HOST and PORT attributes could be used in the event that you want requests arriving to a specific host name or on a specific port to be assigned a given CICS transaction ID or user ID.  For example, you could have two URIMAPs so that requests to port 9999 will run under transaction ID AAAA, while those arriving on port 8888 would run under transaction ID BBBB.)



    ------------------------------
    Leigh Compton
    ------------------------------



  • 8.  RE: Support for Path Parameters in URIMAP Path Attribute

    Posted 8 days ago
    And now I need to circle back, because I missed one key point in your original message:
    > This means URIs such as /customer/{id}/orders/{oid} cannot be represented
    > as /customer/*/orders/* in the URIMAP, but only /customer/*

    So I think you're saying that you want the simple case of /customer/* to run under transaction ID 22SU, but if /orders/ is in the path, you'd want to use a different transaction ID.

    Yep, in that case, you're limited by what the URIMAP wildcarding can support.  The only options are to run all the requests under the same transaction ID with PATH=/customer/* or to change your path design.  Is there ever a case where the same order number would be used with two different customers?  If not, the you could just remove the /customer/{id} from your path design and just use /orders/{oid} with a URIMAP PATH attribute of /orders/*.   Or, if the customer number is needed in the request (as opposed to the Java program being able to look it up from the order number, you could rearrange the two path elements to have /orders/{oid}/customer{id} as your designed path and a URIMAP PATH attribute of /orders/*


    ------------------------------
    Leigh Compton
    ------------------------------