Using Container in Recipe Services

This section describes the recipe service process with the CICS program using a single container for input and output data.

The size of the input and output container can vary greatly, for instance:
  • The input container can only be a couple of hundred bytes and the output container can be up to 4 megabytes.
  • The input container can be a couple of megabytes and the output container can be only a couple of hundred bytes.

Below is the sample that demonstrates how to define the configuration definition of Substation ES recipe service for EMS ESB.

  1. Setup Message Definition 
    SXTP01F ------------------ Define Fields in a Message ------ Row 1 to 18 of 20 
Command ===>                                                   Scroll ==> CSR  
(Types: DAT, OPA, MSG, STR, BOL, I8, U8, I16, U16, I32, U32, I64, U64,         
        F32, F64, POR, IPA)                                                    
  Message Id   ===> MESSAGE-BYTE                                               
                                                                               
Sel Type Dec  Id   Seq  Name                                                   
-   ---   -   ---  ---- ------------------------------------------------------ 
    OPA   0     0  0    DATA                                                   
          0     0  0
    Note: You can use OPA for conversion processing and STR for text data.
  2. Setup Buffer Definition 
    SXTP02F ------------------ Define Fields in a Buffer ------- Row 1 to 18 of 20  
Command ===>                                                   Scroll ==> CSR   
  (Types are Str, Text, Pdec, Updec, Zdec, Uzdec, Ubin, Bin, Float, Opa)        
  Buffer  Id   ===> BUFFER-BYTES                                                
  Maximum Size ===> 0                                                           
                                                                                
Sel  Type  Start   Len     Dec Name                                             
-   ------ ------- -------  -  ---------------------------------------------    
    OPA    0       10000    0  DATA
    Note: You can use OPA for conversion processing and STR for text data.
  3. Setup Conversion Rule 
    SXTP03F --------- Define Msg-Field / Buffer-Field Conversion - Row 1 to 1 of 1
Command ===>                                                   Scroll ==> CSR 
                                                                              
  Conversion Id   ===> CVR-BYTES                                              
  Using Message   ...: MESSAGE-BYTE                                           
  Using Buffer    ...: BUFFER-BYTES                                           
  Max Buffer Size ===> 0                                                      
                                                                              
Trunc Reqd BfFld Msg Field                | Num  Buffer Field                 
  -    -   ----- ------------------------ | ---- -----------------------------
  Y    Y   1     DATA                     | 1    DATA                         
******************************* Bottom of data *******************************
    Note: Map Msg Field “DATA” to Buffer Field “DATA”. 
    SXTP03 ----------------------- Conversion Rules ------------ Row 1 to 14 of 14 
Command ===>                                                   Scroll ==> CSR  
 (ADD=Create new Conversion Rule, CAN=Cancel updates, F=Find)                  
 (Use line cmd 'M' to relate Message fields to conversion rules)               
          Max    EMS  S                                                        
Sel Flds Bufsz   Type Z  Conversion Id    Message Id       Buffer Id           
-   ---- ------- ---- -  ---------------- ---------------- ----------------    
       1 0         M  M  CVR-BYTES        MESSAGE-BYTE     BUFFER-BYTES
    Note: Change SZ to “M” for message size being the buffer size. Substation ES will ignore the 10,000 number specified on the buffer definition and use the size of the JMS message which may be more or less than the 10,000 number.
  4. Setup Recipe 
    SXTP05N ----------------------- Recipe Details --------------------------------
Command ===>                                         (CICS,IMS,EMS,PROP,SEL)   
                                                                               
 Recipe Identifier    ===> CONTAINER-NOCVR                                     
 Listen To            ===> YOUR.INPUT.DESTINATION                              
 Reply To             ===>                                                     
 Reply To Always      ===> N                                                   
 Error Subject        ===> tibss.error.out                                     
 Error Threshold      ===> 0     (0 - 99999)  Error Percentage  ===> 0         
 Reply To Len (Dyn)   ===> 0    Start ===> 0       Usage Limit  ===> 0         
 Input Conversion (?) ===> CVR-BYTES         (SEE CICS OPT FOR NO CONVERSION)  
 Output Conversion(?) ===>                                                     
 Back End System  (?) ===> Interface-CICS     BES2(?):
            BES3  (?) ===>                    BES4(?):                      
 ESB Endpoint     (?) ===> EMS-SERVER         SS-Id Filter: N (N or Y)         
 Resource Name        ===> YOURPGM                                             
 Method of Invocation ===> 10   2  DPL   3 PGM    9 DPL MRO   12 DPL TSQ       
  DPL > 32K Invocations        10 Container      11 Storage                    
                                5 TDQ Write       6 TSQ Write  8 Command       
                                4 Task/IMS Tran   7 IMS Conversational Tran    
 Trace Level          ===> 0  0-5 (Debugging)                                  
 Reply Method         ===> 3  0 None      2 Message                            
                              1 Status    3 Both Status and Message
    Note: It is necessary to fill in both Input and Output Conversion (use same CVR), then go to the CICS panel and change “Container Process” to “M” and then return to recipe detail and remove “Output Conversion”. 
    SXTP05E ---------------- EMS Recipe Details Extension -------------------------
Command ===>                                                                   
                                                                               
 Recipe Identifier    ===> CONTAINER-NOCVR                                     
 Input Dest Type      ===> Q  Name: YOUR.INPUT.DESTINATION                     
 Output Dest Type     ===> Q  Name:                                            
 Error Dest Type      ===> Q  Name: tibss.error.out                            
                                                                               
 Durable Subscriber   ===> N   (N/Y)                                           
 Durable Client Id    ===>                                                     
                               (Service Levels G=Guaranteed,  R=Reliable)      
 SMSL Mode            ===> RN  (RA Auto-Ack, RN No-Ack,  GA All, GS SS Recv)   
 Delivery Mode        ===> R   (P Persistent,  N Non-Persistent,  R Reliable)  
                                                                               
 Output Message properties:                                                    
  Priority            ===> N   (N/Y) Value  ===> 4     (0 - 9)                 
  Expiration          ===> N   (N/Y) Value  ===> 0     Unit ===> S (S,M,H,D)   
  Compression         ===> N   (N/Y)                                           
  Preserve            ===> N   (N/Y, undelivered messages)                     
  Body Trace          ===> N   (N/Y)                                           
  Message Type        ===> B   M(ap)/S(tream)/T(ext)/B(ytes)                   
  Copy JMSCorrelation ===> N   N(o)/Y(es)/E(nvelope)/M(sgId)/W(CorId or MsgId)
    Note: User Message Type “B” (bytes output message) which is the most efficient for conversion-less output, or "T" for text if the input message is an EMS text message. 
    SXTP05I -------------------- CICS Service Details -------------
Command ===>                                                   
                                                               
 Recipe Identifier      ===> CONTAINER-NOCVR                   
 Resource Name          ===> YOURPGM                           
 Method of Invocation   ===> 10 Method of Reply  ===> 3        
                                                               
 Mirror Transaction     ===>      Default SXEX                 
 CSMI User Transaction  ===> N    N/Y                          
                                                               
 Container (CTN) Extended Options                              
 Channel Name           ===> Channel-You-Want                                  
 Single CTN Name        ===> Container-Name-You-Want
 Container Invocation   ===> P P/T - Program / Transaction     
 Container Process      ===> M S/M Single CTN, Message         
 FWD Destination Names  ===> N N/Y as Containers               
                                                               
 Remote Region Execution                                       
 Transaction Id         ===>                                   
 System Name            ===>                                   
                                                               
 Multi-Execution                                               
      Resource 2:            3:            4:            5:
    Note: Change “Container Process” to “M” for Message.

  5. What will happen next

    • Producer will send a Bytes JMS message to “YOUR.INPUT.DESTINATION” (topic or queue based on recipe) with:
      • ReplyTo set

      • Data translated to CP-1047 (which is the typical mainframe code page) You can use TIBCO BusinessWorks Plug-in for Data Conversion to do this

    • Substation ES will receive your message (input message)
    • Substation ES will get a buffer size slightly larger than the JMS Bytes message size
    • Substation ES will send the buffer to CICS

    • Substation ES CICS program SXCOSRVG or SXCO#RED will:

      • Handle input buffer
      • Create the appropriate Container(Container-Name-You-Want) and Channel (Channel-You-Want)
      • Link to your program with Channel feature
    • Your program should clear all containers from channel and create a new one with the output data for which the size does not matter
    • Your program should issue an “EXEC CICS RETURN”
    • Substation ES CICS program SXCOSRVG or SXCO#RED will:
      • Find and transfer the one container to Substation ES

    • Substation ES will take your output data and do the following:

      • Create a bytes JMS message with your data
      • Add a tibss-status property as indicated by “Method of Reply”
        • 2 means just send message - no tibss-status property
        • 3 means add tibss-status to message
      • Publish the JMS message to the “REPLY-TO” destination in the original input message
  6. Example of EMS messages
    • Input Message 
      message=BytesMessage={ Header={ JMSMessageID={ID:ZLINUX-EMS-TEST.80475AB2E0F15:5} JMSDestination={Queue[YOUR.INPUT.DESTINATION]} JMSReplyTo={Queue[YOUR.reply.DESTINATION]} JMSCorrelationID={null} JMSType={null} JMSTimestamp={Mon Apr 02 13:25:08 CDT 2018} JMSDeliveryTime={Mon Apr 02 13:25:08 CDT 2018} JMSExpiration={0} JMSPriority={4} } Properties={ JMSXDeliveryCount={Integer:1} } Bytes={100 bytes} }
    • Output Message (response) 
      message=BytesMessage={ Header={ JMSMessageID={ID:ZLINUX-EMS-TEST.80475AB2E0F15:5} JMSDestination={Queue[YOUR.reply.DESTINATION]} JMSReplyTo={null} JMSCorrelationID={null} JMSType={null} JMSTimestamp={Mon Apr 02 13:25:08 CDT 2018} JMSDeliveryTime={Mon Apr 02 13:25:08 CDT 2018} JMSExpiration={0} JMSPriority={4} } Properties={ JMSXDeliveryCount={Integer:1} tibss-status={Integer:0}  } Bytes={100000 bytes} }