By convention, active participant lists (those used in xOpen) have the remote participant(s) first, followed by an optional local participant. The local participant can often be omitted, in which case the protocol tries to use a reasonable default. For example, a UDP participant contains a UDP port and an IP host. If the local participant is missing from an active participant list, UDP selects an available port for the local participant.
In some cases, it is necessary to specify part of the information in a participant, but it is convenient to allow the lower protocol to ``fill in'' the rest. To allow this flexibility, the constant pointers ANY_HOST and ANY_PORT can be used to specify ``wildcard'' values. For example, if you want to open UDP with a specific local port, but don't care which local host number is used, you could construct a local participant with the specific local port but with the pointer ANY_HOST pushed on the stack. The protocol that interprets the host part of the participant stack could then choose a reasonable default. Similarly, the pointer ANY_PORT could be used for protocols that use ports on their stacks. Protocols that support wildcards indicate this in their manual page.
Figure 2 illustrates how a protocol that is about to invoke xOpen on a low-level protocol initializes the participant list, and then how the low-level protocol extracts that information from the participant list.
Figure 2: Using the participant list
Notice in this example how the high-level protocol pushes two items (a host address and a port number) onto each participant's address stack, but the low-level protocol pops off only one item. This is because the low-level protocol does not interpret the first item (the host address); it just passes it on to its low-level protocol. Also note that when using participants that have been passed from other protocols, you must keep in mind that the address pointers may be valid only for the duration of the current subroutine. Data that is needed beyond this time should be explicitly copied into static storage. In addition, because the participant structure is passed by reference in the xOpen call, the caller should consider the contents invalid after the return.
In general, passive participant lists (those used in xOpenEnable) contain only the local participant, with no remote participant specified. This indicates that an upper protocol is willing to accept connections from any remote participant, as long as the connection is addressed to the correct local participant. Protocols which provide different semantics for their openEnable participants will indicate this explicitly in their manual page in the Appendix.