Function format of user exit routine that determines the inheriting timer-start message

ANSI C , C++

#include <dcmpsv.h>
long uoc_func (dcmpsv_uoc_rtime *parm)

K&R C

#include <dcmpsv.h>
long uoc_func(parm)
 
dcmpsv_uoc_rtime *parm ;

If the use of the timer-started application program activate (CBLDCMCF('EXECAP ')) is followed by an error which raises the need for rerunning OpenTP1, this user exit routine can change the timer-start environment. It can perform the following:

Inherit or cancel the current timer-start
Make inherited timer-start immediate start
Change the name of the application to be timer-started

When installing in the MCF the user exit routine that determines the inheriting timer-start message, specify the address of the user exit routine function in the MCF main function for the application startup service. The MCF main function for the application startup service does not depend on the communication protocol.

For details on how to create the MCF main function for the application startup service, see the OpenTP1 Operation manual.

When uoc_func (user exit routine that determines the inheriting time-start message) is called, the following parameters are passed from the MCF to parm.

dcmpsv_uoc_rtime

typedef struct {
     char le_name[9] ;     ... Input source logical terminal name
     char reserve1[7] ;    ... Reserved
     char ap_name[9] ;     ... Application name
     char reserve2[7] ;    ... Reserved
     long exec_time ;      ... Timer start time
     char ap_type ;        ... Application type
                               'a': ans type; 'n': noans type
     char time_type;       ... Timer-start type
                               'i': Interval specification
                                  for timer start
                               't': Time point specification
                                    for timer start
     char reserve3[26] ;   ... Reserved
} dcmpsv_uoc_rtime;

le_name

The input source logical terminal name is set here. If the application program activate (CBLDCMCF('EXECAP ')) is called from the SPP, '*' is set here.

ap_name

The application name specified by the UAP in the timer-started application program activate (CBLDCMCF('EXECAP ')) is set here.

exec_time

The MHP start time specified by the UAP in the timer-started application program activate (CBLDCMCF('EXECAP ')) is set here, as the number of seconds counted from 00:00:00 on January 1, 1970.

ap_type

The application type of the UAP which issued the timer-started application program activate (CBLDCMCF('EXECAP ')) is set here:

'a': ans type

'n': noans type

time_type

The timer-start type specified by the UAP in the timer-started application program activate (CBLDCMCF('EXECAP ')) is set here:

'i': Interval specification for timer start

't': Time point specification for timer start

uoc_func() must return the following values:

Return value	Explanation
DCMPSV_UOC_TIME_CONTINUE	Timer-start is inherited
DCMPSV_UOC_TIME_JUST	Immediate start will be in effect
DCMPSV_UOC_TIME_DEQ	Timer-start is canceled

The subsequent MCF processing varies depending on the return value from uoc_func() as follows:

DCMPSV_UOC_TIME_CONTINUE
If this value is returned from the user exit routine, the MCF counts the seconds from 00:00:00 on January 1, 1970 to the present time and compares it with the time specified in the application program activate (CBLDCMCF('EXECAP ')). If the present time is later than the time specified in the function, the MCF immediately starts the pertinent MHP. Otherwise, the application will be timer-started.
DCMPSV_UOC_TIME_JUST
If this value is returned from the user exit routine, the MCF immediately starts the pertinent MHP. If this value is to be returned, the application to be immediately started can be changed in the user exit routine. However, change to an MHP for MCF event processing is not allowed. If the specified new application name is not defined, ERREVT4 is reported.
If the application name of the UAP to be immediately started by the user exit routine is changed and the application types of the old and new MHPs to be started are different, the segments to be timer-started are deleted from the output queue, with the output of a warning message (KFCA10711-W).
DCMPSV_UOC_TIME_DEQ
If this value is returned from the user exit routine, the MCF cancels timer-start. The segments to be timer-started are deleted from the output queue, with the output of an information message (KFCA10700-I).

If another value is returned from the user exit routine, the segments to be timer-started are deleted from the output queue, with the output of a warning message (KFCA10710-W).

Functions available to user exit routines
When creating a user exit routine, keep in mind that only the functions listed below can be used. If a function that is not listed below is used for a user exit routine, operation is unpredictable.
- Memory manipulation functions
  Data area management (example: malloc, free)
  Shared memory management (example: shmctl, shmget, shmop)
  Memory manipulation (example: memcpy)
  Character string manipulation (example: strcpy)
- Time acquisition functions
User exit routine errors
If an error is detected by a user exit routine, it must be reported to the MCF using the MCF-specified return code. If a process terminating signal or abort() is issued in a user exit routine, the MCF will terminate abnormally.
User exit routine execution timing
Execution timing of a user exit routine started by the MCF may not be executed in synchronization with the OpenTP1 system and UAP startup and termination sequences. Design the user exit routine to ensure that no problems will occur even if the routine is executed before the UAP, or if it is called after all UAPs have terminated.
Local variable size of user exit routines
The sum of the sizes of the local variables used in a single user exit routine must be within 1 kilobyte. Do not call a function recursively within a user exit routine.