OTMA C/I hints and tips

Use the following hints and tips when programming with OTMA C/I.

  • Some OTMA C/I API calls have an ECB parameter that is posted by the function or by an SRB routine that the function precipitates. The caller must check the ECB and wait for it to be posted before inspecting the return code and output data. Be sure to initialize the ECB with 0 before passing to the OTMA C/I call. The calls that include the ECB parameter are:
    • otma_open
    • otma_openx
    • otma_send_receive
    • otma_send_receivex
    • otma_send_receivey
    • otma_send_async
    • otma_send_asyncx
    • otma_receive_async
  • Each otma_alloc call creates an independent session for the subsequent otma_send_receive call. One of the otma_alloc calls can be used to specify the name of IMS transaction or IMS command to be sent to IMS. The maximum length of the transaction name is 8 characters. If no transaction name or command is specified in the otma_alloc call, the transaction name, followed by one or more blanks, or command needs be specified in the beginning of the send buffer of the otma_send_receive call. After the otma_send_receive call, otma_free is required, except for the IMS conversation transaction. See the invocation sample C for sending a conversation transaction.
  • The OTMA C/I builds the standard LLZZ prefix of IMS application data format. You do not need to build the LLZZ prefix.
  • To send a multi-segment message to IMS, the send segment list of the otma_send_receive call must identify the length of each input segment. The first element in the segment list specifies the number of the segment. The first element is then followed by the length of segment 1, the length of segment 2, and so on.
  • When a multi-segment output message is received, an output segment list is provided for the otma_send_receive call. The first element in the output segment list contains the number of the output segment. The first element is then followed by the length of output segment 1, the length of output segment 2, and so on.
  • Sample programs (DFSYCSMP) are shipped with IMS.
  • The OTMA C/I can be used to send a protected transaction to IMS by passing a context token to the otma_send_receive call.
  • Because some of the OTMA C/I calls require the calling program to wait, implementing the time-out routine in the calling program is highly recommended to avoid long running transactions in IMS and the internal OTMA C/I hang.
  • To run the OTMA C/I application efficiently, limit the number of otma_open and otma_close calls in the application. Also, for all otma_open and otma_create calls, try to use the same member name rather than generating a different member name for each call.
  • If the size of the output receive buffer specified in the otma_send_receive call is too small, the actual data returned is limited by the size of the receive buffer. The output can be rejected if a special option, SyncLevel1, is specified in the otma_alloc call. However, if the size of the output receive buffer is too small for the otma_receive_async call, the OTMA C/I always rejects the output.
  • The OTMA C/I can support various program-to-program switches in IMS. See IMS Version 15 Communications and Connections for more information.
  • In some cases, OTMA C/I returns a return code to inform the caller about an abnormal condition. Logging or saving the return code for debugging purpose is recommended.
  • The otma_send_receive call sends an OTMA send-then-commit message with synclevel=none to IMS. The caller can set a synclevel=confirm for otma_send_receive.
  • When an input z/OS® Resource Recovery Services (RRS) context token is given in the otma_send_receive call, the synclevel is then changed to SYNCPT to support the protected transaction.
  • For complex program-to-program switches in IMS, a send-then-commit input message could result in a commit-then-send output message instead of the expected send-then-commit output message. The OTMA C/I works in this scenario. See IMS Version 15 Communications and Connections for more information on program-to-program switches.
  • The otma_send_async call sends an OTMA commit-then-send message to IMS.
  • The otma_receive_async call receives an OTMA commit-then-send output message from IMS.
  • The OTMA C/I does not support either the OTMA resync protocol or the OTMA security PROFILE option.