OpenTP1 Version 7 Description
Programs in a system that sends and receives MCF messages do not need to be constantly running. For example, MCF can start an MHP whenever a message is received that needs to be processed by that MHP; or a programmer can write a program that starts whenever an MCF error event occurs. This section describes how programs can be started in a MCF message-exchange system. An MHP or SPP can be started:
MCF can determine the application name (that is, what MHP or SPP should be started) from an input message.
Figure 3-31 shows how the application name is determined.
Figure 3-31 Determination of application name
The application name can be determined by including a user exit routine for determining the application name. Alternatively, you can choose not to include such an exit routine.
MCF regards the string of eight or fewer characters before the first space in an input message as the application name. OpenTP1 converts the application name into the MHP or SPP service group name and service names, and then starts the MHP or SPP. If the first nine characters are all spaces, the application name is regarded as invalid and an error occurs.
Specify the correspondence between the application name and the service group name and service names in the application attribute definition of the MCF application definition.
MCF calls the exit routine and regards the name set in the routine as the application name. OpenTP1 converts the application name into the MHP or SPP service group name and service names, and then starts the MHP or SPP.
Specify the correspondence between the application name and the service group name and service names in the application attribute definition of the MCF application definition. Note that even when an exit routine is included in the OpenTP1 system, if the application name is not set in the routine, the string of eight or fewer characters before the first space in the message will be regarded as the application name. If the first nine characters are all spaces, the application name is regarded as invalid and an error occurs.
An MHP or SPP can issue a function (dc_mcf_execap()) to start another MHP or SPP. This ability of an MHP or SPP to start another UAP is called the Application Activate facility.
Immediately after a normal termination of the MHP or SPP that requested the start or after a specified time has elapsed, the application startup process starts the specified MHP or SPP.
If an MHP issues the function dc_mcf_rollback() to roll back a transaction and retry is specified in the function parameters, the rolled-back MHP can be restarted and processing can be re-executed.
For a UAP to issue the function dc_mcf_execap() or dc_mcf_rollback() and start or restart an application as described above, the application startup process must be started. To enable this, create the MCF communication configuration definition for the application startup process. By creating this definition, you can reduce the load on the MCF communication process because the application startup process performs processing that does not depend on the protocol.
The inter-OpenTP1 logical channel that the MHP or SPP uses to pass data to MCF when requesting the start of another UAP is called the internal channel. The internal channel is defined in the application startup environment definition. MCF also uses the internal channel to pass data to the application program that is to be started.
OpenTP1 administrators should be aware of certain events, such as failures or establishing or releasing a connection, that sometimes occur during online processing. OpenTP1 reports such events in messages produced by MCF events. A programmer can create an MHP that is started by such an MCF event.
MCF error events are events such as errors or failures. MCF communication events are events such as the establishing or releasing of connections.
The two types of events are identified by MCF event codes. In the MCF application definition, you can specify the correspondence between MCF event codes and MCF applications.
The application startup process or the MCF communication process starts the service of the MHP that corresponds to the MCF event code. The application startup process or MCF communication process starts the MHP for an MCF error event. The MCF communication process starts the MHP that processes an MCF communication event. When a programmer develops an MHP that processes an MCF error event, the programmer must also write an MCF communication configuration definition for the application startup process.
You can issue an error event to report an error in a communication event. Use the errevt operand of the application attribute definition to specify whether or not to enable this report. However, you cannot issue an error event to report an error in an error event.
The following subsections list the MCF error events, their causes, and some examples of what kind of actions a program should take when the event occurs. In addition to these error events, there are also communication events for individual protocols: for events such as establishing or releasing connections. For details on MCF events, see the applicable OpenTP1 Protocol manual.
Table 3-5 List of MCF events
MCF event name | MCF event code | Reason for the MCF event notification | Example of processing executed by an MHP started by an MCF event |
---|---|---|---|
MCF event that reports detection of an invalid application name | ERREVT1 | This MCF event occurs when the MCF application definition does not contain the MCF-application name of the message. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that the appropriate MCF-application name was absent, and outputs the corresponding response message for inquiry messages. |
MCF event that reports discarding of a message | ERREVT2 | This MCF event occurs when the message that MCF received from the input queue or the message placed in the input queue by the facility for immediately starting the application is discarded because:
|
A programmer could write an MHP for this MCF event so that the MHP notifies the user that the message was discarded, and outputs the corresponding response message for inquiry messages. |
MCF event that reports UAP abnormal termination | ERREVT3 | This event occurs when an MHP terminates abnormally after the segment has been passed to the dc_mcf_receive function that is called in the MHP, or when the MHP rolls back.# | A programmer could write an MHP for this MCF event so that the MHP notifies the user that the UAP terminated abnormally or rolled back. If the message received is an inquiry message, a response message can be sent. |
MCF event that reports discarding of a timer-start message | ERREVT4 | This event occurs when the message is discarded that was placed in the input queue by the facility for starting the application with the timer because of the reason indicated by ERREVT2. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that a message to request the timer start was discarded, and outputs the corresponding response message for inquiry messages. |
MCF event that reports discarding of an unprocessed message | ERREVTA | This MCF event occurs when an unprocessed message to be sent to a remote system is discarded because:
|
A programmer could write an MHP for this MCF event so that the MHP notifies the user that an unprocessed send message was discarded. |
MCF event that reports a send error | SERREVT | This MCF event occurs when a protocol error occurs during message transmission. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that the message could not be sent due to a protocol error. |
MCF event that reports completion of send processing | SCMPEVT | This MCF event occurs when a message is successfully sent to the other system. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that the message was successfully sent to the other system. |
MCF event that reports an error | CERREVT(VERREVT) | This MCF event occurs when a connection error or logical terminal error occurs in the communication management program. No error is reported when a connection retry is defined in the program. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that an error occurred in the connection or logical terminal. |
MCF event that reports the connection status | COPNEVT(VOPNEVT) | This MCF event occurs when a connection is established. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that messages can be sent and received. |
CCLSEVT(VCLSEVT) | This MCF event occurs when a connection is successfully released. | A programmer could write an MHP for this MCF event so that the MHP notifies the user that messages can no longer be sent and received. |
The facility for reporting a communication event error to the user by an error event is available. This facility allows the user to use an MHP for an MCF event to recover the failed communication event. A communication event message can be received at the second segment.
To use the facility for reporting a communication event error, specify yes in the errevt operand of the -n option in the application attribute definition.
Figure 3-32 shows an overview of ERREVT2 report for a COPNEVT error.
Figure 3-32 Overview of ERREVT2 report for a COPNEVT error
A user can use the command mcfuevt to start an MHP or SPP. Even for MHPs that start when a message is received, using mcfuevt immediately to start an MHP enables a message to be sent to another system.
Only noans MHPs can be started with mcfuevt, so specify noans in the MCF application definition of the MHP that is to be started by mcfuevt.
For a program to be started by mcfuevt, you must specify various operands in the MCF application definition mcfaalcap. In the -n operand of mcfaalcap, specify:
name=UCMDEVT
kind=user (or omit)
type=noans (or omit)
Execute the command mcfuevt to start an MHP or SPP. As parameters of the mcfuevt command, specify the MCF communications process identifier, and the input message to be passed to the MHP or SPP.
If UCMDEVT is not defined and the mcfuevt command is executed, the mcfuevt command returns an error. In such a case ERREVT1 does not occur.
An MHP or SPP that is started by a command does not depend on a communications protocol, so it is recommended that you specify the application startup process in the MCF communication process that is specified in the mcfuevt command.
Figure 3-33 shows the causes of MCF starting a UAP.
Figure 3-33 Causes of MCF starting a UAP
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.