Quantity, FetchUnit, and listen time method invocation examples

These are examples of the sequence of calls that occur for Quantity, FetchUnit, or Listen Time method within a map.

For an input card that is not a source event, the Resource Manager might call the Get method more than once if it determines there is more data to be returned. The Resource Manager interprets two special command line options that can be specified in the adapter's command line:

  • -QTY: number of messages to be processed by the map
  • -LSN: amount of time to listen for messages for each burst of the map

In addition to these command options, the FetchUnit card setting determines how many messages are returned from each burst. Therefore, if the FetchUnit is greater than one (1) or the -QTY (quantity) command is provided on the adapter command line, the Get method will be called more than once.

Carefully adhere to the following rules to ensure that the Get method is called correctly. Note that "X messages" means X messages per burst of the map. For example, if the map has multiple bursts, then each burst will fetch the FetchUnit and decrement this number from the quantity. Therefore, if FetchUnit = 3 and QTY = 7, X is 3 (burst #1), 3 (burst #2), and 1 (burst #3).
  • When X messages, -LSN Y (where Y > 0) The Get method is called repeatedly until either: The adapter has been listening for Y seconds (cumulatively across all Get calls for the burst). X messages have been returned for the burst. Note that returning zero (0) messages from a Get call does not mark the end of the data. The Get will be called again as long as the elapsed time does not exceed Y and the total number of messages does not exceed X.
  • When X messages, -LSN 0

    The purpose of -LSN 0 is to fetch all data that is immediately available, such as all messages that are sitting on a queue, without ever waiting for data to arrive. Therefore, whenever an absence of data is detected, it marks the end of the input.

    The Get method is called repeatedly until either:
    • The adapter returns no messages from a call to Get if (MPIP_ADAPTER_NUM_MESSAGES) is 0. The adapter will not be called again for this burst (contrast with -LSN Y where Y > 0)
    • X messages have been returned for the burst
  • X messages, -LSN not specified

    If -LSN is not specified, this implies listen forever (an infinite time). Therefore, the Get will be called repeatedly until -QTY messages have been received.

  • -QTY S, -LSN not specified

    This is an invalid configuration because it means get all of the messages that are returned in an infinite amount of time, (that is, the map will never complete). The Resource Manager will detect this and return an error at the point of property validation.

On each call to Get, the adapter must set the MPIP_ADAPTER_NUM_MESSAGES property to the number of messages being returned.

If an adapter recognizes that there is no more data (for example, a database query has retrieved all of the rows in the result set), the adapter should return MPIRC_W_END_OF_DATA. The adapter will not be called back for more data.