OpenTP1 Version 7 Programming Reference C Language
dc_mcf_execap - Activate an application program
Format
ANSI C, C++
#include <dcmcf.h> int dc_mcf_execap(DCLONG action,DCLONG commform,char *resv01, DCLONG active,char *apnam,char *comdata, DCLONG cdataleng) |
K&R C
#include <dcmcf.h> int dc_mcf_execap (action, commform, resv01, active, apnam, comdata, cdataleng) DCLONG action; DCLONG commform; char *resv01; DCLONG active; char *apnam; char *comdata; DCLONG cdataleng; |
Description
The function dc_mcf_execap() starts the MHP or SPP of the application name specified for apnam from a UAP (SPP or MHP). After the UAP terminates, it can be started immediately or after a specified interval has passed. After the transaction or service function has terminated, the MHP or SPP with the application name specified for apnam can be started immediately or after a preset length of time.
To call the function dc_mcf_execap() from an SPP, process the SPP as a transaction and call the function dc_mcf_open() in the SPP main function.
If an MHP is activated by issuing the function dc_mcf_execap() from another MHP, the name in the first-received message is used as the logical terminal name of the input source that receives messages through the activated MHP. If the function dc_mcf_execap() is called from the MHP, the name in the first-received message is also used as the logical terminal name of the input source that receives messages.
If an MHP is activated by issuing the function dc_mcf_execap() from an SPP, an asterisk (*) is used as the logical terminal name of the input source that receives messages through the activated MHP. If the function dc_mcf_execap() is called from the MHP, an asterisk (*) is also used as the logical terminal name of the input source that receives messages.
The maximum length of a single message segment that can be sent is 32 kilobytes. 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 segment format of the message to be passed to the MHP to be activated. 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 the following items in the format shown below:
{DCMCFESI|DCMCFBUF1}[|{DCMCFJUST|DCMCFINTV|DCMCFTIME}] [|{DCMCFEMI|DCMCFBUF2}] |
commform
Specify DCNOFLAGS.
resv01
Specify a null character.
active
14*3600+30*60+30=52230 |
The range of specifiable values is 0 (activation at 00:00:00) to 86399 (activation at 23:59:59).
The value specified for active is valid only for timer-driven activation. If immediate activation is specified, the value specified for active is ignored.
Since OpenTP1 checks whether the activation time has been reached at regular intervals, there is a difference between the time specified for active and the actual activation time. The accuracy of time monitoring depends on the value for the time monitoring interval specified for the btim operand in the -t option of the MCF communication configuration definition mcfttim.
apnam
Specify the application name of the MHP or SPP to be started. The application name can be specified with up to 8 bytes. The application name must end with a null character.
comdata
Specify the contents of the message segment to be passed to the MHP or SPP which is to start. Specify also segment if the sending of the first or an intermediate segment is to be followed by the notice of the completion of message sending.
cdataleng
Specify the length of the segment to be passed to the MHP or SPP to be started. Specify 0 for cdataleng if the sending of the first or an intermediate segment is to be followed by the notice of the completion of message sending.
Return values
Return value | Return value (numeric) | Explanation |
---|---|---|
DCMCFRTN_00000 | 0 | Normal termination. |
DCMCFRTN_71002 | -12002 | An error occurred during input/output processing for the message queue. |
The message queue is in shutdown state. | ||
No message queue was allocated. | ||
The value specified for the segment length exceeds 32,000 bytes. | ||
The MHP or SPP specified for apnam cannot be activated because the MCF is being terminated. | ||
DCMCFRTN_71003 | -12003 | The message queue is full. |
DCMCFRTN_71004 | -12004 | The buffer for storing messages could not be acquired in the memory. |
DCMCFRTN_71108 | -12108 | An attempt was made to start the MHP or SPP of the application name specified for apnam, but the MHP's or SPP's management table could not be acquired. |
The local memory of the process is insufficient. | ||
DCMCFRTN_72000 | -13000 |
|
|
||
DCMCFRTN_72001 | -13001 | The specified application name is not defined in the MCF. |
The application name is incorrect. | ||
The application startup process name is not specified in the communication service definition (mcfmcname definition command) for the MCF manager. | ||
The application startup process identifier is not specified in the MCF application environment definition (the -p option of the mcfaenv definition command) corresponding to an application startup process. | ||
The application startup process identifier specified in the application environment definition (the -p option of the mcfaenv definition command) does not match the identifier specified in the communication configuration definition (the mcftenv definition command) for the process. | ||
For starting of non-response MHPs and SPPs:
|
||
For starting of response and continuous inquiry response MHPs:
|
||
When starting an application from an SPP:
|
||
DCMCFRTN_72005 | -13005 | A value less than 1 byte was specified as the message segment length in the function dc_mcf_execap() in which DCMCFESI was specified for action. |
DCMCFRTN_72007 | -13007 | From a response type (type=ans) MHP which already called the function dc_mcf_reply(), another response type MHP was started by the function dc_mcf_execap(). |
From a continuous-inquiry-response type (type=cont) MHP which already called the function dc_mcf_reply(), another continuous-inquiry-response type MHP was started by the function dc_mcf_execap(). | ||
DCMCFRTN_72009 | -13009 | From a response type (type=ans) MHP, a response type MHP was started by the function dc_mcf_execap() more than once. |
From a continuous-inquiry-response type (type=cont) MHP, a continuous-inquiry-response type MHP was started by the function dc_mcf_execap() more than once. | ||
DCMCFRTN_72011 | -13011 | From an MHP which is not response type (type=ans), a response type MHP was started by the function dc_mcf_execap(). |
From an MHP which is not continuous-inquiry-response type (type=cont), a continuous-inquiry-response type MHP was started by the function dc_mcf_execap(). | ||
DCMCFRTN_72016 | -13016 | The value specified for action is invalid. |
The value specified for resv01 is not a null character. | ||
The application start method specified for action is invalid. | ||
The specified argument is invalid. | ||
DCMCFRTN_72024 | -13024 | DCNOFLAGS was not specified for commform. |
DCMCFRTN_72026 | -13026 | The value specified as the segment type for action is invalid. DCMCFEMI must be specified for the last segment. DCMCFESI must be specified for a segment other than the last segment. |
DCMCFRTN_72041 | -13041 | The function dc_mcf_execap() with a segment other than the last segment (DCMCFESI) specified was not called for the application name, but the function dc_mcf_execap() with the last segment (DCMCFEMI send segment length = 0) specified was called for the application name. |
DCMCFRTN_72044 | -13044 | From a continuous-inquiry-response type (type=cont) MHP which already called the function dc_mcf_contend(), another continuous-inquiry-response type MHP was started by the function dc_mcf_execap(). |
DCMCFRTN_72108 | -13108 | The value specified for active exceeds the limit. |
DCMCFRTN_72109 | -13109 | An attempt was made to activate an MHP, for which type=cont (continuous-inquiry-response type) was specified in the MCF application definition, by the function dc_mcf_execap() with timer start specified. |
DCMCFRTN_77001 | -18001 | The logical terminal (LE) corresponding to the application to be activated is being started and cannot be used, or no logical terminals are available. |
Other than the above | An unprecedented error (e.g., program damage) occurred |
Note
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.