OpenTP1 Version 7 Programming Reference C Language
dc_mcf_receive - Receive a message
Format
ANSI C, C++
#include <dcmcf.h> int dc_mcf_receive(DCLONG action,DCLONG commform,char *termnam, char *resv01,char *recvdata,DCLONG *rdataleng, DCLONG inbufleng,DCLONG *time) |
K&R C
#include <dcmcf.h> int dc_mcf_receive (action, commform, termnam, resv01, recvdata, rdataleng, inbufleng, time) DCLONG action; DCLONG commform; char *termnam; char *resv01; char *recvdata; DCLONG *rdataleng; DCLONG inbufleng; DCLONG *time; |
Description
The function dc_mcf_receive() receives a segment of a message. When a whole logical message is received, call this function as many times as there are segments.
The function dc_mcf_receive() can receive the following messages:
When receiving a message which is sent from the remote system via communication protocol, the syntax of the function dc_mcf_receive() varies according to communication protocol in use. For the syntax of the function dc_mcf_receive() which receives a message from the remote system, see the explanation in the applicable OpenTP1 Protocol manual.
The maximum length of a single segment that can be received is 1 megabyte. Note that the actual value might be smaller depending on the protocol. For details, see the applicable OpenTP1 Protocol manual.
The figure below shows the format of the receive segment area. With buffer format 1, L is 8 bytes; with buffer format 2, L is 4 bytes.
Arguments whose values are set in the UAP
action
Specify whether the first segment of the message is received and the buffer format to be used in the format shown below:
{DCMCFFRST|DCMCFSEG}[|{DCMCFBUF1|DCMCFBUF2}] |
commform
Specify DCNOFLAGS.
termnam [when an intermediate segment or the last segment is received]
Specify the input logical terminal name. Specify the logical terminal name returned when the first segment is received.
resv01
Specify a null character.
recvdata
Specify the receive segment area. When the message is sent from the local system, the maximum length of receive segment is 32,000 bytes.
When the message is sent from the remote system, the maximum length of receive segment depends on the product adopting the communication protocol.
When the function dc_mcf_receive() terminates, a segment of the message is returned.
inbufleng
Specify the length of the receive segment area.
Arguments whose values are returned from OpenTP1
termnam [when the first segment is received ]
The input logical terminal name is returned.
Specify the returned logical terminal name when an intermediate segment or the last segment is received.
recvdata
The contents of the receive segment are returned.
rdataleng
The length of the receive segment is returned.
time
The time when the message is received is returned in total seconds since 00:00:00 on January 1, 1970.
Return values
Return values | Return value (numeric) | Explanation |
---|---|---|
DCMCFRTN_00000 | 0 | Normal termination. |
DCMCFRTN_71000 | -12000 | The function dc_mcf_receive() for receiving the first segment was called more than once. To receive an intermediate segment or the last segment, call the function dc_mcf_receive() with DCMCFSEG specified for action. |
DCMCFRTN_71001 | -12001 | The function dc_mcf_receive() for receiving the next segment was called after the last segment of the message is received. The function dc_mcf_receive() called immediately before receives a message completely. If the function dc_mcf_receive() is called again after this value is returned, the return value DCMCFRTN_72000 is returned. |
DCMCFRTN_71002 | -12002 | An error occurred during input processing for the message queue. |
The message queue is in shutdown state. | ||
DCMCFRTN_72000 | -13000 |
|
|
||
DCMCFRTN_72001 | -13001 | The logical terminal name specified for termnam is invalid. |
DCMCFRTN_72013 | -13013 | A segment exceeding the length of the receive area was received. The excess portion was truncated. |
DCMCFRTN_72016 | -13016 | The value specified for action is invalid. |
The value specified for resv01 is invalid. | ||
The value specified for the argument is invalid. | ||
DCMCFRTN_72024 | -13024 | The value specified for commform is invalid. |
DCMCFRTN_72025 | -13025 | The value of the segment type specified for action is invalid. The value must be DCMCFFRST or DCMCFSEG. |
DCMCFRTN_72036 | -13036 | The segment receive area is insufficient. Allocate an area of 9 bytes or more for buffer format 1; 5 bytes or more for buffer format 2. |
Other than the above | An unprecedented error (e.g., program damage) occurred. |
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.