OpenTP1 Version 7 Programming Reference COBOL Language

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

Create a service program (SPP)

Format

PROGRAM-ID.    program-name.
LINKAGE SECTION.
01  unique-name-1.
    02  data-name-A    PIC X(n).
01  unique-name-2.
    02  data-name-B    PIC S9(9) COMP.
01  unique-name-3.
    02  data-name-C    PIC X(n).
01  unique-name-4.
    02  data-name-D    PIC S9(9) COMP.
PROCEDURE DIVISION USING unique-name-1 unique-name-2
                         unique-name-3 unique-name-4
                  :
                  :
Service processing
                  :
                  :
EXIT PROGRAM.

Description

The SPP service program executes a service and returns the results. CBLDCRPC('CALL ') called from the client UAP requests a service.

Create the service program in the above format as required. The service name corresponds to the program ID of the service program. Specify the correspondence when setting the UAP execution environment. The methods of setting the UAP execution environment are as follows:

Data area specification

The values listed below are passed to the data areas of the service program. These values are specified by the client UAP for CBLDCRPC('CALL ').

Specify the following values for the data areas of the service program:

Set a response for data-name-C, set the response length for data-name-D then return the service program.

A response is sent to the service client UAP regardless of whether the service program was executed as a transaction or whether commitment or rollback processing was executed. Create a response with which the service program informs the client UAP of the occurrence of an error if necessary.

If the service program terminates abnormally because the program malfunctions, this abnormal termination is not reported to the client UAP. The client UAP gets to know the abnormal termination of the service program when the maximum response wait time specified in the user service definition is exceeded.

Data areas to which values are passed from the client UAP

data-name-A

The input parameter set in the client UAP is passed.

data-name-B

The input parameter length set in the client UAP is passed.

data-name-D

The response length set in the client UAP is passed.

Data areas whose values are set in the UAP

data-name-C

The response from the service program is set here. Before the service program can return, it must set the processing result in the data-named area.

data-name-D

Specify the length of the actual response from the service program. Set a numeric value which is equal to or smaller than the data-name-D value passed from the client UAP.

Notes on service program processing

  1. The service program called by CBLDCRPC('CALL ') (with 1 set in data-name-C) of a non-response-type RPC cannot reference data-name-C or data-name-D.
  2. If the service program is a COBOL initialization program (INITIAL clause specified in the program header), the data item values are initialized each time a service request is used. If the INITIAL clause is not specified in the program header, the values upon the previous service request remain in the data items. Thus, initialize the values before using them if necessary.
  3. The following COBOL-UAP creation programs cannot be called from the SPP service program:
    • CBLDCRPC('OPEN ') - Start an application program
    • CBLDCADM('COMPLETE') - Report the completion of user server start processing
    • CBLDCRSV('MAINLOOP') - Start an SPP service
    • CBLDCRPC('CLOSE ') - Terminate an application program
    Do not use a statement in the service program to exit the program. If used, UAP operation is not guaranteed. Once a system call is used to create a child process, COBOL-UAP creation programs can no longer be called from the child process.
  4. In order to call an MCF facility (CBLDCMCF) from the SPP service program, the main program should call the following COBOL-UAP creation programs:
    • CBLDCMCF('OPEN ') - Open the MCF environment
    • CBLDCMCF('CLOSE ') - Close the MCF environment
  5. An SPP service program cannot call CBLDCMCF('RECEIVE ').
  6. Do not execute an operation or reference that extends beyond the area of the input parameter length passed to data-name-B, for the input parameter passed to data-name-A. If you execute such an operation or reference, operation cannot be guaranteed. The process may terminate abnormally.
  7. Before an MCF function (CBLDCMCF) can be called from an SPP service program, data areas such as unique-name-1 must begin at an even-numbered address. If a data area such as unique-name-1 begins at an odd-numbered address, a bus error will occur.
    For example, assume that the unique-name-3 data area to be used for CBLDCMCF is defined as an array, the send data contains an odd number of bytes, and SYNC is not specified in the structure (no boundary adjustment used). In this situation, using the second element of the array as a CBLDCMCF parameter will cause a bus error during function execution.

Relationship between transactions and the service program

When the transaction attribute has been specified in the UAP execution environment, and the client UAP has been executed as a transaction, the service program is also executed as a transaction. In this case, do not call CBLDCTRN('BEGIN ') from the service program.

Commitment or rollback processing is ensured for all global transaction services. When the service program operating as a transaction branch is terminated by EXIT PROGRAM, the service program is assumed to request normal termination of the transaction branch.

When the transaction attribute has been specified in the UAP execution environment, but the client UAP has not been executed as a transaction, the service program is not executed as a transaction. To execute the service program as a transaction, call CBLDCTRN('BEGIN ') and the program which acquires a synchronization point at any time.

When no transaction attribute is specified in the UAP execution environment, the service program cannot be executed as a transaction by CBLDCTRN('BEGIN ') from the service program.

Status code

There is no status code. OpenTP1 does not reference status codes. The return of -1 from the service program would not mean a request for rollback.