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;

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.

action

Specify the following items in the format shown below:

• Whether the segment to be passed to the MHP or SPP to be activated is the last segment of a logical message
• When to activate the MHP or SPP
• Buffer format to be used
  

  {DCMCFESI|DCMCFBUF1}[|{DCMCFJUST|DCMCFINTV|DCMCFTIME}] [|{DCMCFEMI|DCMCFBUF2}]

DCMCFESI

Specify DCMCFESI to pass the first segment or an intermediate segment. If the function dc_mcf_execap() with DCMCFESI specified is called, the function dc_mcf_execap() with DCMCFEMI specified for action must be called.

DCMCFEMI

Specify DCMCFEMI to pass the last segment. If the logical message comprises only a single segment, also specify DCMCFEMI. Also specify DCMCFEMI if the sending of the first or an intermediate segment is to be followed by the notice of the completion of message sending.

DCMCFJUST

Specify DCMCFJUST to enable immediate start. The value specified for active is ignored in this case.

DCMCFINTV

Specify DCMCFINTV for an interval timer. The MHP or SPP will be activated the time specified for active after the function dc_mcf_execap() is called.

DCMCFTIME

Specify DCMCFTIME for a time-point timer. The MHP or SPP will be activated at the time specified for active.

DCMCFBUF1

Specify DCMCFBUF1 when using buffer format 1.

DCMCFBUF2

Specify DCMCFBUF2 when using buffer format 2.

commform

Specify DCNOFLAGS.

resv01

Specify a null character.

active

• Interval timer drive (specification of DCMCFINTV for action)
  Specify the number of seconds which will elapse from the call of the function dc_mcf_execap() to the activation of the MHP or SPP. The value must be 1 to 360000 (1 second to 100 hours).
  
• Time-point timer drive (specification of DCMCFTIME for action)
  Specify when to activate the MHP or SPP specified for apnam. The time is in seconds relative to 00:00:00 in local time.
  Time setting example
  To activate the MHP or SPP at 2:30:30 p.m. in local time:
  

  14*3600+30*60+30=52230

  Assign 52230 to active.
  

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.

1. The activation order of application programs varies depending on the mcfmuap -c order specification in the UAP common definition of the MCF manager definition.
2. If you use a single service function to update a TAM or DAM file and call the function dc_mcf_execap() to start an application that will reference the updated file, make sure that the application will lock the file. If the application references the file without locking the file, the data existing before the file was updated might be referenced.