OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/W, TP1/Client/P

[Contents][Index][Back][Next]

2.5.4 Message assembly facility and delivery confirmation facility

TP1/Client includes functionality that automatically prefixes four-byte message length information to a message when the message is sent and automatically deletes the information when the message is received. This functionality is called the message assembly facility. If you use this facility, you do not need to take the message length into account when creating a CUP.

In addition to the four-byte message length information, you can send a message with one-byte segment information and a six-byte message ID added so that response-only data can be received to confirm delivery of the message. This functionality is called the message delivery confirmation facility. If you use this facility, you do not need to take into account the validity of a message and whether a message that has been sent is delivered when you create a CUP.

The message assembly facility and message delivery confirmation facility are implemented by using the following functions to send and receive messages:

Whether the message assembly facility or message delivery confirmation facility is used when these functions are issued is specified by using DCCLTDELIVERYCHECK of the client environment definition as shown in the following table.

Table 2-4 Relationship between the facility to be used and the DCCLTDELIVERYCHECK specification of the client environment definition

Facility to be used DCCLTDELIVERYCHECK specification of the client environment definition
Message assembly facility Specify N or omit DCCLTDELIVERYCHECK.
Message delivery confirmation facility Specify Y.
Organization of this subsection
(1) Conditions for using the facilities
(2) Message formats
(3) Flow of sending and receiving a message when the message assembly facility is used
(4) Flow of sending and receiving a message when the message delivery confirmation facility is used
(5) Validity checking

(1) Conditions for using the facilities

Both facilities require issuing of the dc_rpc_open_s function with DCCLT_ONEWAY_SND, DCCLT_ONEWAY_RCV, or DCCLT_SNDRCV specified in the flags argument.

In addition, TP1/NET/TCP/IP in the remote system must be set to use the message assembly facility or message delivery confirmation facility. For details about how to set TP1/NET/TCP/IP, see the manual OpenTP1 Version 7 Protocol TP1/NET/TCP/IP. Note, however, that the remote system need not use TP1/NET/TCP/IP if send messages and receive messages have the same format.

(2) Message formats

The following explains the format of messages sent or received when the message assembly facility and the message delivery confirmation facility are used.

(a) Format of messages sent or received when the message assembly facility is used

The following figure shows the format of messages sent or received when the message assembly facility is used.

Figure 2-22 Format of messages sent or received when the message assembly facility is used

[Figure]

Note that the message length indicates the length of the assembled message.

(b) Format of messages sent or received when the message delivery confirmation facility is used

This subsection explains the format of messages sent or received when the message delivery confirmation facility is used, and the format of response-only data.

(3) Flow of sending and receiving a message when the message assembly facility is used

This subsection explains how a message is assembled and disassembled when the message assembly facility is used.

(a) When a message is sent

When TP1/Client uses the message assembly facility to send a message, the dc_clt_assem_send_s function is issued. Four-byte message length information is prefixed to the message.

The following figure shows the flow of sending a message when the message assembly facility is used.

Figure 2-25 Flow of sending a message when the message assembly facility is used

[Figure]

If you want to release a connection immediately after a message is sent, specify DCCLT_SND_CLOSE in the flags argument of the dc_clt_assem_send_s function. If you specify DCNOFLAGS, the connection is not released until the dc_rpc_close_s function is issued (except when an error has occurred).

The host name of TP1/NET/TCP/IP with which TP1/Client communicates is specified in DCSNDHOST of the client environment definition. The port number is specified in DCSNDPORT of the client environment definition. You can also specify the host name and port number in arguments of the dc_clt_assem_send_s function.

(b) When a message is received

When TP1/Client uses the message assembly facility to receive a message, the dc_clt_assem_receive_s function is issued. TP1/Client receives message data for the message length prefixed to the message body when the message was sent.

The following figure shows the flow of receiving a message when the message assembly facility is used.

Figure 2-26 Flow of receiving a message when the message assembly facility is used

[Figure]

If you want to release a connection immediately after a message is received, specify DCCLT_RCV_CLOSE in the flags argument of the dc_clt_assem_receive_s function. If you specify DCNOFLAGS, the connection is not released until the dc_rpc_close_s function is issued (except when an error has occurred).

The CUP port number is specified in DCRCVPORT of the client environment definition.

(4) Flow of sending and receiving a message when the message delivery confirmation facility is used

This subsection explains how a message is assembled and disassembled, and the flow of sending and receiving response-only data when the message delivery confirmation facility is used.

(a) Sending a message and confirming delivery

When TP1/Client uses the message delivery confirmation facility to send a message, the dc_clt_assem_send_s function is issued. After sending the message, TP1/Client waits for response-only data from TP1/NET/TCP/IP. When it receives the response-only data, TP1/Client returns control to the CUP. The received response-only data is not reported to the CUP.

The following figure shows the flow of sending a message when the message delivery confirmation facility is used.

Figure 2-27 Flow of sending a message when the message delivery confirmation facility is used

[Figure]

When the message delivery confirmation facility is used, you can monitor the sequence of sending a message from the time the message is sent until response-only data is received. If the monitoring times out, TP1/Client releases the connection with TP1/NET/TCP/IP, and returns DCCLTER_TIMED_OUT.

TP1/Client receives response-only data over the same connection it used to send the message. If you want the connection to be released as soon as the response-only data is received, specify DCCLT_SND_CLOSE in the flags argument of the dc_clt_assem_send_s function. If you specify DCNOFLAGS, the connection is not released until the dc_rpc_close_s function is issued (except when an error has occurred).

The host name of TP1/NET/TCP/IP with which TP1/Client communicates is specified in DCSNDHOST of the client environment definition. The port number is specified in DCSNDPORT of the client environment definition. You can also specify the host name and port number in arguments of the dc_clt_assem_send_s function.

(b) Receiving a message and confirming delivery

When TP1/Client uses the message delivery confirmation facility to receive a message, the dc_clt_assem_receive_s function is issued. After receiving the message, TP1/Client sends response-only data to TP1/NET/TCP/IP and returns control to the CUP.

The following figure shows the flow of receiving a message when the message delivery confirmation facility is used.

Figure 2-28 Flow of receiving a message when the message delivery confirmation facility is used

[Figure]

TP1/Client sends response-only data over the same connection that it used to receive the message. If you want the connection to be released as soon as response-only data is sent, specify DCCLT_RCV_CLOSE in the flags argument of the dc_clt_assem_receive_s function. If you specify DCNOFLAGS, the connection is not released until the dc_rpc_close_s function is issued (except when an error has occurred).

(c) Collision between send and receive messages

If a message from TP1/Client collides with a message from TP1/NET/TCP/IP, TP1/Client discards the received message, releases the connection with TP1/NET/TCP/IP, and then returns DCCLTER_COLLISION_MESSAGE.

The following figure shows the flow of processing when send and receive messages collide.

Figure 2-29 Flow of processing when send and receive messages collide

[Figure]

(5) Validity checking

When the message assembly facility or message delivery confirmation facility is used, TP1/Client automatically checks the validity of sent and received messages.

(a) Validity check for message length (message assembly facility)

When the message assembly facility is used and TP1/Client receives a message, TP1/Client checks the validity of the message length. The following table shows the handling if an error is found.

Table 2-5 Handling of an error detected by the validity check for message length

No. Error System User response
1 An invalid message is received (the message length is 0 to 4 bytes). Stops processing. Review the remote system settings.
2 The receive buffer is insufficient (the message length minus four bytes is longer than the value of the recvleng argument). Stops processing. Check whether a valid value is specified in the recvleng argument of the dc_clt_assem_receive_s function. Alternatively, review the MHP.
(b) Validity check for response-only data (message delivery confirmation facility)

When the message delivery confirmation facility is used and TP1/Client sends a message, TP1/Client receives response-only data and checks the validity of the data. The following table shows the handling of an error if detected.

Table 2-6 Handling of an error detected by the validity check for response-only data

No. Error System User response
1 Any of the following invalid messages is received:
  • Message whose length is 0 to 10 bytes
  • Message whose length is 11 bytes and whose segment information is not 0x10
  • Message whose segment information is not 0x10 or 0x18
Stops processing. Review the remote system settings.
2 Messages collide. Stops processing. Try again, if necessary.
3 Message IDs do not match. Retries reception. None
(c) Validity check for a received message (message delivery confirmation facility)

When the message delivery confirmation facility is used and TP1/Client receives a message, TP1/Client checks the validity of the message. If TP1/Client finds an error, it stops processing. The following table shows the handling of an error if detected.

Table 2-7 Handling of an error detected by the validity check for a received message

No. Error System User response
1 Any of the following invalid messages is received:
  • Message whose length is 0 to 11 bytes
  • Message whose segment information is not 0x10 or 0x18
Stops processing. Review the remote system settings.
2 The receive buffer is insufficient (the message length minus 11 bytes is longer than the value of the recvleng argument). Stops processing. Check whether a valid value is specified in the recvleng argument of the dc_clt_assem_receive_s function. Alternatively, review the MHP.