dc_mcf_receive - Receive a message

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;

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:

Messages which are sent from the remote system via communication protocol
MCF events which are reported from the local system
Messages which are sent by the function dc_mcf_execap() (Activate an application program) from a UAP of the local system
Messages which are sent by executing the mcfuevt command on the local system

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.

[Figure]

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}]

DCMCFFRST: Specify DCMCFFRST to receive the first segment. If the message comprises only a single segment, also specify DCMCFFRST.

DCMCFSEG: Specify DCMCFSEG to receive an intermediate segment or the last segment.

DCMCFBUF1: Specify DCMCFBUF1 when using buffer format 1. In general, buffer format 1 is used.

DCMCFBUF2: Specify DCMCFBUF2 when using buffer format 2.

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.

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 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.
DCMCFRTN_71002	-12002	The message queue is in shutdown state.
DCMCFRTN_72000	-13000	Return at MHP execution The function dc_mcf_receive() for receiving an intermediate segment or the last segment was called before the function dc_mcf_receive() for receiving the first segment was called. To receive the first segment, call the function dc_mcf_receive() with DCMCFFRST specified for action. The function dc_mcf_receive() was called again after the return value DCMCFRTN_71001 was returned.
DCMCFRTN_72000	-13000	Return at SPP execution The function dc_mcf_receive() cannot be called from an SPP.
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.