OpenTP1 Version 7 Programming Reference C Language
dc_mcf_timer_set - Set user timer monitoring
Format
ANSI C, C++
#include <dcmcf.h> int dc_mcf_timer_set(DCLONG flags,DCLONG timer,DCLONG timer_id, char *lename,char *apname,char *data,DCLONG data_leng, DCLONG resv01,DCLONG resv02) |
K&R C
#include <dcmcf.h> int dc_mcf_timer_set (flags, timer, timer_id, lename, apname, data, data_leng, resv01, resv02) DCLONG flags; DCLONG timer; DCLONG timer_id; char *lename; char *apname; char *data; DCLONG data_leng; DCLONG resv01; DCLONG resv02; |
Description
Use the function dc_mcf_timer_set() from a UAP to set user timer monitoring for monitoring the desired interval. To call this function, you must specify usertime=yes in the -p option of the MCF communication configuration definition mcfttim.
Only a user server can call the function dc_mcf_timer_set().
When the time (in seconds) specified for timer elapses (when timeout occurs), the logical terminal specified for lename generates an event and starts the MHP having the application name specified for apname. You can omit lename only when the UAP is an MHP. In this case, the input source logical terminal is assumed.
The MHP to be started when timeout occurs must be a non-response-type (noans type) MHP. The figure below shows the format of the message segment when a message is passed to the MHP. With buffer format 1, L is 8 bytes; with buffer format 2, L is 4 bytes.
To cancel the user timer monitor set by the function dc_mcf_timer_set(), call the function dc_mcf_timer_cancel() with the same values specified for timer_id and lename as specified in the function dc_mcf_timer_set().
The time monitor starts as soon as the function dc_mcf_timer_set() is called.
The maximum number of time monitors you can run concurrently is indicated by the maximum number of time monitoring requests specified for the timereqno operand in the -p option of the MCF communication configuration definition mcfttim.
Arguments whose values are set in the UAP
flags
Specify DCNOFLAGS.
timer
Specify the number of seconds that are to elapse before the MHP is started after the function dc_mcf_timer_set() is called. The specifiable range is 1 to 360000 (from 1 second to 100 hours).
Since OpenTP1 monitors timeout at fixed intervals, an error arises between the time specified for timer and the time that elapses before actual detection of timeout. The accuracy of time monitoring depends on the value of the interval of time monitoring specified for the btim operand in the -t option of the MCF communication configuration definition mcfttim.
timer_id
Specify the timer request identifier.
timer_id provides information for identifying this timer. Be sure to specify a value for timer_id that is unique in the logical terminal specified for lename.
lename
Specify in 8 or fewer bytes the name of the logical terminal that is to generate an event when timeout occurs. Append a null character to the end of the logical terminal name. When omitting this value, specify a null character. The default is the input source logical terminal.
apname
Specify the application name of the MHP to be started. The attribute of this application must be defined in the application attribute definition (mcfaalcap) field within the MCF application definition that is specified by the -a option to the MCF communication configuration definition mcftenv. This MCF communication configuration definition (mcftenv) is for the MCF communication server that serves the logical terminal specified by lename. server having the logical terminal name specified for lename. Specify the application name in up to 8 bytes. Append a null character to the end of the application name. The MHP must be a non-response-type (noans type) MHP. The specified application name must be a user event.
data
Specify the contents of the message segment to be passed to the MHP to be started. You cannot specify multiple segments. If no segment is to be passed to the MHP to be started, specify a null character.
data_leng
Specify the length of the segment to be passed to the MHP to be started. If no segment is to be passed to the MHP to be started, specify 0.
The specifiable range is 0 to 256. The maximum specifiable value depends on the maximum message length specified for the msgsize operand in the
-p option of the MCF communication configuration definition mcfttim.
resv01
Specify DCNOFLAGS.
resv02
Specify DCNOFLAGS.
Return values
Return value | Return value (numeric) | Explanation |
---|---|---|
DC_OK | 0 | Normal termination. |
DCMCFER_PARAM_FLAGS | -11911 | The value specified for flags is invalid. |
DCMCFER_PARAM_LENAME | -11912 | The value specified for lename is invalid. |
DCMCFER_PARAM_TIMER | -11909 | The value specified for timer is invalid. |
DCMCFER_PARAM_APNAME | -11913 | The value specified for apname is invalid. |
DCMCFER_PARAM_DATA | -11915 | The value specified for data is invalid. |
DCMCFER_PARAM_LENG | -11914 | The value specified for data_leng is invalid. |
DCMCFER_PARAM_TIM_ID | -11910 | The timer request identifier specified for timer_id is already registered. |
DCMCFER_INVALID_ARGS | -11900 | The value specified for an argument is invalid. |
DCMCFER_NO_DEFINE | -11916 | The requested facility is not defined in the MCF. |
DCMCFER_NO_TIMER_ENT | -11917 | User timer monitoring cannot be set because there is no free space in the timer registration area. To reserve the timer registration area, revise the value of the timereqno operand in the -p option of the MCF communication configuration definition mcfttim. If required, check the values of the -p option of the MCF manager definition mcfmcomn and the static_shmpool_size operand in the system environment definition. |
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.