User Routine Processing

When an active member of an XCF group issues the IXCMSGOX macro to send a message to another active member of the same group, XCF asynchronously passes control to the message user routine of the target member. The message user routine runs in SRB mode in the target member's primary address space (the joiner's address space).

You are responsible for writing a message user routine that can:

Determine if the member's initialization is complete. A member might issue IXCJOIN and its message user routine could get control before IXCJOIN returns to the caller. To determine if the member's initialization is complete, the message user routine might examine a bit that the member sets on or off. The member might want its message user routine to ignore or defer any messages until the routine determines that initialization is complete.
Check the message control information area (32 bytes of data passed as part of the parameter list).
Determine the following from the contents of the message control information area:
- Whether there is a message to be received. (The message user routine could also determine this from the parameter list. If the length of the message is zero (MEPLMLEN=0), then the message buffer does not contain any data.)
- Whether to receive the message if there is one in the message buffer area.
- Whether to receive the message into a single buffer or into multiple buffers.
- Where to place the data from the message buffer area.
- The type or format of the data in the message buffer area.
If the message user routine elects to receive the message, it can:
- Check the member data to determine which member the message was sent to, if more than one member is using the same message user routine. The member data would have been defined when the member joined the group (MEMDATA parameter on IXCJOIN). XCF passes that information to the message user routine as part of the parameter list.
- Obtain enough storage to contain all the data from the message buffer area or obtain less storage but plan to specify MULTIPART=YES on the IXCMSGIX macro so you can reissue IXCMSGIX multiple times to receive the entire message. If you receive messages very frequently, you might use a pre-allocated buffer. For less frequent messages, you can obtain storage using one of the system services.
- Receive the message by invoking the IXCMSGIX macro.
- Process the data in the message, or queue the message to a task for processing and post the task.
- Issue IXCMSGOX if the sender requires an acknowledgment, possibly using the MSGCNTL field to contain the acknowledgment.

If the message user routine chooses not to issue IXCMSGIX to receive the data, XCF discards the data as soon as the message user routine returns to XCF, and does not notify the sender that the message was discarded.