Modifying the initial terminal data

The dynamic routing program must not perform an EXEC CICS RECEIVE or an EXEC CICS GDS RECEIVE command, because this prevents the routed-to transaction from obtaining the initial terminal data.

The CICS® relay program, DFHAPRT, places a copy of the user's initial terminal input into a separate buffer. This information includes SNA presentation services headers for APPC mapped and unmapped conversations. A pointer to this buffer (DYRBPNTR), and its length (DYRBLGTH), are provided in the communications area passed from DFHAPRT to the dynamic routing program.

Note that:
  • The buffer pointed to by DYRBPNTR contains the data that arrived in the first request unit (RU) of the message. If the RU size is large enough to hold the full message, the buffer contains the full message. However, if the RU size is less than the message length, the buffer contains only the data from the first RU (even if the buffer itself is large enough to hold the full message).
  • The length field DYRBLGTH is the length of the message, not the length of the data in the buffer. DYRBLGTH contains the length of data in the buffer only if the full message arrived in a single RU.
  • If all the following are true, no initial terminal input data is passed to the routing program:
    1. The routing program is running in the AOR.
    2. The original request was transaction-routed from the TOR.
    3. The originating facility is an APPC parallel session.

Because the transaction profile has not been queried at this point, uppercase translation has not been performed on the input data unless UCTRAN(YES) is specified on the TYPETERM definition.

Sometimes you may want to modify the initial data input by the user. (It may be necessary to do this if, for example, you change the ID of the remote transaction, using field DYRTRAN of the communications area.) To modify the input data, your routing program should, when invoked for route selection:
  1. Copy the input data pointed to by DYRBPNTR into a named variable, of length DYRBLGTH
  2. Modify the data in the named variable
  3. Use the INPUTMSG option of the EXEC CICS RETURN command to make the modified data available to the application program.

For guidance information about using INPUTMSG on EXEC CICS RETURN commands, see the other methods described in INPUTMSG. For programming information about the INPUTMSG option, see RETURN.

Note: If, after modifying the input data, the dynamic routing program is reinvoked because an error occurs in routing to the selected transaction, it should “remember” that it has modified the original user-input.