OpenTP1 Version 7 Programming Reference COBOL Language

[Contents][Index][Back][Next]

CBLDCMCF('EXECAP ') - Activate an application program

Format

PROCEDURE DIVISION specification

CALL  'CBLDCMCF'  USING  unique-name-1  unique-name-2
                         unique-name-3

DATA DIVISION specification

01  unique-name-1.
    02  data-name-A    PIC X(8) VALUE 'EXECAP  '.
    02  data-name-B    PIC X(5).
    02  FILLER        PIC X(3).
    02  data-name-C    PIC X(4).
    02  data-name-D    PIC X(4).
    02  data-name-E    PIC 9(8).
    02  data-name-F    PIC 9(8).
    02  data-name-G    PIC 9(9) COMP.
    02  data-name-H    PIC X(4).
    02  data-name-I     PIC X(4).
    02  data-name-J     PIC X(4).
    02  data-name-K    PIC X(4).
    02  data-name-L    PIC X(8).
    02  data-name-M    PIC X(4).
    02  data-name-N    PIC X(8).
    02  data-name-O1   PIC X(4).
    02  data-name-O2   PIC 9(9) COMP.
    02  data-name-O3   PIC 9(9) COMP.
    02  data-name-O4   PIC X(1).
    02  data-name-O5   PIC X(1).
    02  data-name-P    PIC X(14).
01  unique-name-2.
    02  data-name-Q    PIC X(4).
    02  data-name-R    PIC X(8).
    02  data-name-S    PIC X(8).
    02  data-name-T    PIC X(6).
    02  data-name-U    PIC X(2).
    02  data-name-V    PIC X(28).
01  unique-name-3.
    02  data-name-W    PIC 9(x) COMP.
    02  data-name-X    PIC X(x).
    02  data-name-Y    PIC X(n).

Description

CBLDCMCF('EXECAP ') starts the MHP or SPP of the application name specified for data-name-N from a UAP (SPP or MHP). After the transaction or service function has terminated, the MHP or SPP with the application name specified for data-name-N can be started immediately or after a preset length of time.

To start an application program from an SPP, process the SPP as a transaction and call CBLDCMCF('OPEN ') in the SPP main function.

If an MHP is activated 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 application program is started 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 from an SPP, "*" is used as the logical terminal name of the input source that receives messages through the activated MHP. If the application program is started from the MHP, "*" 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 format of the area (indicated by unique-name-3) of the segment which is passed to the MHP to be started.

[Figure]

Data areas whose values are set in the UAP

data-name-A

Specify VALUE 'EXECAP[Figure]' for the request code indicating activation of an application program.

data-name-C, data-name-D

Specify space.

data-name-E, data-name-F

These areas are used by the MCF.

data-name-G

Specify 0.

data-name-H

Specify whether the segment to be passed to the MHP or SPP is the last segment of a logical message. The following values are available:

'ESI[Figure]': Specify this value to pass the first segment or an intermediate segment. If CBLDCMCF('EXECAP ') with 'ESI[Figure]' specified is used, CBLDCMCF('EXECAP ') with 'EMI[Figure]' specified for data-name-H must be used.

'EMI[Figure]': Specify this value to pass the last segment. If the logical message comprises only a single segment, also specify 'EMI[Figure]'.

Also specify 'EMI[Figure]' if the sending of the first or an intermediate segment is to be followed by the notice of the completion of message sending.

data-name-I, data-name-J, data-name-K

Specify space.

data-name-L

data-name-M

Specify space.

data-name-N

Specify the application name of the MHP or SPP to be started after the MHP that called CBLDCMCF('EXECAP ') terminates. The application name can be specified with up to 8 bytes. The application name must end with space. If the specified name comprises less than 8 bytes, pad the remaining portion with space.

data-name-O1

Specify when to activate the MHP. The following values are available:

'JUST': Specify this value for immediate start. When VALUE 'JUST' is specified, the value specified for data-name-L is ignored.

'INTV': Specify this value for interval timer start. The MHP will start the time specified for data-name-L after CBLDCMCF('EXECAP ') is called.

'TIME': Specify this value for time point timer start. The MHP or SPP will start at the time specified for data-name-L.

Space: The default value 'JUST' (immediate start) is assumed.

data-name-O2, data-name-O3

Specify 0.

data-name-O4

Specify space.

data-name-O5

Specify the buffer format to be used. The following values are available:

'1': Specify this value to use buffer format 1.

'2': Specify this value to use buffer format 2.

Space: The specification for data-name-O5 is assumed to be omitted. '1' (buffer format 1) is assumed.

data-name-P

Specify LOW-VALUE.

data-name-Q, data-name-R, data-name-S, data-name-T, data-name-U

Specify space.

data-name-V

Specify LOW-VALUE.

data-name-W

With buffer format 1: PIC 9(9)
Specify the send segment length.

With buffer format 2: PIC 9(4)
Specify the send segment length + 4.

Specify 0 as the send segment length if the sending of the first or an intermediate segment is to be followed by the notice of the completion of message sending.

data-name-X

With buffer format 1: PIC X(8)

With buffer format 2: PIC X(2)

This area is used by the MCF.

data-name-Y

Specify the contents of the message segment to be passed to the MHP or SPP to be activated. Specify data-name-Y also when the sending of the first or an intermediate segment is to be followed by the notice of the completion of message sending.

Data area to which a value is returned from OpenTP1

data-name-B

A status code of 5 digits is returned.

Status codes

Status code Explanation
00000 Normal termination.
71002 An error occurred during input/output processing for the message queue.
The message queue is in descriptor state.
No message queue was allocated.
The value specified for the segment length exceeds 32,000 bytes.
The MHP or SPP specified for data-name-N cannot be activated because the MCF is being terminated.
71003 The message queue is full.
71004 The buffer for storing messages could not be acquired in the memory.
71108 An attempt was made to start the MHP or SPP of the application name specified for data-name-N, but the MHP or SPP management table could not be acquired.
The local memory of the process is insufficient.
72000 Return at MHP execution:
The MHP called CBLDCMCF('EXECAP ') before CBLDCMCF('RECEIVE ') for receiving the first segment.
Return at SPP execution:
CBLDCMCF('EXECAP ') was called from a nontransactional SPP process.
72001 The specified application name is not defined with the MCF.
The application name is incorrect.
The application startup process name is not specified in the communication service definition (mcfmcname definition command) included in the MCF manager definition.
No application startup process identifier is specified in the environment definition (-p option to the mcfaenv definition command) included in the MCF application definition for the application startup process.
The following two values do not match:
  • Application startup process identifier specified in the application environment definition (-p option to the mcfaenv definition command)
  • Application startup process identifier specified in the communication configuration definition (mcftenv definition command) for the application startup process
If a non-response type MHP or SPP is to be started:
  • No logical terminal (the lname operand of the -n option to the mcfaalcap definition command) is specified in the application attribute definition for the application to be started.
  • The logical terminal specified in the application attribute definition for the application to be started is not defined in the communication configuration definition (mcftalcle definition command) for the application startup process.
  • The logical terminal specified in the application attribute definition of the application to be started is not for send-only communication (mcftalcle -t=send).
  • The logical terminal specified in the application attribute definition for the application to be started cannot use the application startup process.
If an MHP of the response type or continuous inquiry-response type is to be started:
  • No internal communication path (cname operand of the -n option to the mcfaalcap definition command) is specified in the application attribute definition for the application to be started.
  • The internal communication path specified in the application attribute definition for the application to be started is not defined in the communication configuration definition (-c option to the mcftpsvr definition command) for the application startup process.
  • The inquiry logical terminal (mcftalcle -t=request) is not specified in the communication configuration definition (mcftalcle definition command) of the application start process.
If an application is to be started from an SPP:
  • The mcf_psv_id operand in the user service definition or user service default definition for the caller UAP is assigned no application startup process identifier.
  • The following two values do not match:
    Application startup process identifier assigned to the mcf_psv_id operand in the user service definition or user service default definition for the caller UAP
    Application startup process identifier specified in the communication configuration definition (-s option to the mcftenv definition command) for the application startup process or in the application environment definition (-p option to the mcfaenv definition command)
  • The following two values do not match:
    MCF manager identifier assigned to the mcf_mgrid operand in the user service definition or user service default definition for the caller UAP
    Identifier of the MCF manager to which the application startup process belongs
72005 A value less than 1 byte (with buffer format 1) or less than 5 bytes (with buffer format 2) was specified for the message segment length (data-name-W) in CBLDCMCF('EXECAP ') in which 'ESI[Figure]' was specified for data-name-H.
72007 From a response type (type=ans) MHP that called CBLDCMCF('REPLY '), another response type MHP was started by calling CBLDCMCF('EXECAP ').
From a continuous-inquiry-response type (type=cont) MHP that called CBLDCMCF('REPLY '), another continuous-inquiry-response type MHP was started by calling CBLDCMCF('EXECAP ').
72009 CBLDCMCF('EXECAP ') was called more than once from a response type (type=ans) MHP.
CBLDCMCF('EXECAP ') was called more than once from a continuous-inquiry-response type (type=cont) MHP.
72011 From an MHP which is not response type (type=ans), a response type MHP was started by calling CBLDCMCF('EXECAP ').
From an MHP which is not continuous-inquiry-response type (type=cont), a continuous-inquiry-response type MHP was started by calling CBLDCMCF('EXECAP ').
72016 The value specified for data-name-O1, data-name-O2, data-name-O3, data-name-P, or data-name-V is invalid.
72024 The value specified for data-name-Q is invalid.
72026 The value specified as the segment type for data-name-H is invalid. 'EMI[Figure]' must be specified for the last segment. 'ESI[Figure]' must be specified for a segment other than the last segment.
72028 The value specified for data-name-A is invalid.
72041 When the logical message comprised a single segment, the CBLDCMCF('EXECAP ') in which send segment length = 0 (with buffer format 1) or send segment length = 4 or less (with buffer format 2) was specified was called.
72044 From a continuous-inquiry-response type (type=cont) MHP that called CBLDCMCF('CONTEND '), another continuous-inquiry-response type MHP was started by CBLDCMCF('EXECAP ').
72108 The value specified for data-name-L exceeds the limit.
72109 An attempt was made to activate an MHP, for which type=cont (continuous-inquiry-response type) was specified, by CBLDCMCF('EXECAP ') with timer start specified.
77001 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.

Notes

  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 CBLDCMCF('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.