PROCEDURE DIVISION specification

CALL  'CBLDCRPC'  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 'CALL    '.
    02  data-name-B    PIC X(5).
    02  FILLER        PIC X(3).
    02  data-name-C    PIC S9(9) COMP VALUE ZERO.
    02  data-name-D    PIC S9(9) COMP.
    02  data-name-E    PIC X(32).
    02  data-name-F    PIC X(n).
01  unique-name-2.
    02  data-name-G    PIC S9(9) COMP.
    02  data-name-H    PIC X(n).
01  unique-name-3.
    02  data-name-I    PIC S9(9) COMP.
    02  data-name-J    PIC X(n).

CBLDCRPC('CALL ') requests an SPP service. This function can be called without consideration of the node containing the requesting service.

Specify a service group name and service name for a data area of CBLDCRPC('CALL ') to request a service. A service request is addressed to the service program corresponding to the specified names.

A UAP which calls CBLDCRPC('CALL ') can be used regardless of whether it has been executed as a transaction. When a service is requested by CBLDCRPC('CALL ') from the process which has been executed as a transaction, the requested service process runs as a transaction branch.

Before this function can be used, the OpenTP1 at the node containing the server UAP to which the service request is addressed must be active.

Receiving a signal while waiting for a response after execution of CBLDCRPC('CALL ') does not cause CBLDCRPC('CALL ') to be returned.

The following items are described after the list of status codes. See each description for details on CBLDCRPC('CALL ').

(1) Data areas of CBLDCRPC('CALL ')

(2) Error cases of CBLDCRPC('CALL ')

(3) Timing when CBLDCRPC('CALL ') results in error

(4) Specification for reexecuting the service request if CBLDCRPC('CALL ') results in error

(5) When a priority is given to a service request

(6) Difference between status codes 00310 and 00306

(7) Specification for the return of status code 00378

(8) Relationship between status codes and synchronization point processing

(9) Notes on requesting a service

(10) When a service is requested with domain qualification

data-name-A

Specify VALUE 'CALL' for the request code indicating that a remote service is requested.

data-name-C

Specify the RPC mode and option with a value:

0: Synchronous response-type RPC

2: Asynchronous response-type RPC

1: Nonresponse-type RPC

4: Chained RPC

Add 32 to the value indicating the RPC mode to avoid having the requested processing handled as a transaction. When 32 is added, the processing of the service function is not handled as a transaction even if the service request is issued from the transaction.

Add 256 to the value indicating the RPC mode when the service group name is specified with domain qualification. An RPC with domain qualification cannot be a transaction branch. Therefore, add (256 + 32) to the value indicating the RPC mode whenever CBLDCRPC('CALL ') is used from the transaction.

Example 1:

When a nontransaction service is requested by using a synchronous response-type RPC, specify 32 (0 + 32) for data-name-C.

Example 2:

When a service is requested by using a synchronous response-type RPC with domain qualification from the transaction, specify 290 (2 + 256 + 32) for data-name-C.

data-name-E

Specify the SPP service name with an ASCII character string of up to 31 bytes. End the character string with space. The space is not counted in the length of the character string.

data-name-F

Specify the SPP service group name with an ASCII character string of up to 31 bytes. End the character string with space. The space is not counted in the length of the character string.

When requesting a service with domain qualification, specify the service group name suffixed by an at mark (@) and the DNS domain name, and end the character string with space.

data-name-G

Specify the input parameter length of the service (the length of data-name-H) within the range from 1 to DCRPC_MAX_MESSAGE_SIZE^#. DCRPC_MAX_MESSAGE_SIZE is defined in dcrpc.h.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

data-name-H

Specify the input parameter of the service.

data-name-I

Specify the length of the response (the length of data-name-J) within the range from 1 to DCRPC_MAX_MESSAGE_SIZE^#. DCRPC_MAX_MESSAGE_SIZE is defined in dcrpc.h.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

data-name-B

A status code of 5 digits is returned.

data-name-D

The descriptor is returned when asynchronous response-type RPCs are used.

data-name-I

The length of the response set by the service program is returned.

data-name-J

The response set by the service program is returned.

The following status codes are returned from OpenTP1, not from the service program.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Data areas of CBLDCRPC('CALL ') are explained below.

Values passed to server UAP

Allocate an area (data-name-J) for the response from the service program before requesting a service. The client UAP sets the following values in CBLDCRPC('CALL ').

• Input parameter (data-name-H)
• Input parameter length (data-name-G)
• Response length (data-name-I)

The input parameter, input parameter length, and response length values which are set in CBLDCRPC('CALL ') of the client UAP are passed to the service program as is. Change the notation of character codes or digits in the processing of the client UAP or requested service program if required. If a service request is addressed to a service program which does not return any response, the specified response length is ignored.

The maximum values of input parameter length and response length are declared as DCRPC_MAX_MESSAGE_SIZE^# in the header file dcrpc.h. See the contents of dcrpc.h to confirm the maximum values.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Values returned from server UAP

When the service program terminates and response is returned, the following values can be referenced:

• Response from service program (data-name-J)
• Length of response from service program (data-name-I)

The value of data-name-I is the length of the response which is actually returned from the service program. The values of data-name-J and data-name-I can be referenced in the following cases depending on the RPC mode:

• In the case of synchronous response-type RPC and chained RPC
  The values of data-name-J and data-name-I can be referenced when CBLDCRPC('CALL ') returns.
  
• In the case of asynchronous response-type RPC
  The value of data-name-J can be referenced when CBLDCRPC('POLLANYR') which receives the response returns. The value of data-name-I cannot be referenced.
  
• In the case of nonresponse-type RPC
  The values of data-name-J and data-name-I cannot be referenced.
  

If CBLDCRPC('CALL ') or CBLDCRPC('POLLANYR') returns with an error, the values of data-name-J and data-name-I cannot be referenced.

If the returned response is larger than the response area acquired by the client UAP (data-name-I), CBLDCRPC('CALL ') returns with an error, giving the status code 00309.

Value specified for data-name-C

The value specified for data-name-C and the execution result of CBLDCRPC('CALL ') are explained below.

• Synchronous response-type RPC (when 0 is specified for data-name-C)
  CBLDCRPC('CALL ') will not return until a response returns or a communication error occurs.
  
• Asynchronous response-type RPC (when 2 is specified for data-name-C)
  CBLDCRPC('CALL ') will return immediately. The response can be referenced after the response is received asynchronously in CBLDCRPC('POLLANYR'). Do not free the response storage area (data-name-J) until the asynchronous response-type RPC is terminated due to one of the following causes:
  
  • A response is received by CBLDCRPC('POLLANYR')
  • The receiving of responses is rejected by CBLDCRPC('DISCARDF')
  • Commitment or rollback is performed when a service is requested from a transaction.

When an asynchronous response-type RPC is used in a transaction, receive responses by using CBLDCRPC('POLLANYR') before performing the synchronization point processing (commitment or rollback). No response can be received by CBLDCRPC('POLLANYR') after the synchronization point processing. To designate a specific response received by CBLDCRPC('POLLANYR'), specify the positive integer (descriptor), which is returned by CBLDCRPC('CALL '), as the argument of CBLDCRPC('POLLANYR'). Thus, hold the value of data-name-D of CBLDCRPC('CALL ') to designate a specific response received.

To receive responses after the synchronization point processing in non-transaction processing, specify the corresponding option in rpc_extend_function of the system service definition. For details about rpc_extend_function, see the manual OpenTP1 System Definition.

• Nonresponse-type RPC (when 1 is specified for data-name-C)
  CBLDCRPC('CALL ') will return immediately without waiting for completion of the service program processing. The service program is treated as a function which does not return any response. Therefore, the UAP requesting a service cannot determine whether the service program has been performed. With this specification, the response (data-name-J) and its length (data-name-I) cannot be referenced.
  
• Chained RPC (when 4 is specified for data-name-C)
  CBLDCRPC('CALL ') will not return until a response is returned or a communication error occurs. When the same service is requested more than once using a chained RPC, the process used for the first request can be used for the subsequent requests.
  There are the following restrictions on the use of chained RPCs:
  
  1. The shutdown state of the user server or service cannot be detected by the second and subsequent calls of CBLDCRPC('CALL ').
  2. The entire user server enters shutdown state if an error occurs during the service program processing of the second and subsequent calls of CBLDCRPC('CALL '). Services do not enter shutdown state individually.

Reasons why CBLDCRPC('CALL ') returns with an error are explained below.

If the OpenTP1 at the node containing the server UAP is not active

If the OpenTP1 to which the service is requested is not running, CBLDCRPC('CALL ') returns with an error and sets one of the following status code values:

00306

00314

00315

00320

If the server UAP is not active

When the server UAP is a multiserver, the service request is dealt with a new process which is activated by the OpenTP1 even if the server UAP is being terminated abnormally or being partially recovered. However,CBLDCRPC('CALL ') returns with an error in the following cases:

1. No service request can be addressed to the SPP in shutdown state. If the service group is shut down, CBLDCRPC('CALL ') returns with an error, giving the status code 00312.
2. If the SPP is being terminated or has been terminated by the stop command for the user server (dcsvstop command) or for OpenTP1 (dcstop command), CBLDCRPC('CALL ') returns with an error and sets one of the following status code values:
   00310
   00312
   00313
   Which status code returns depends on the timing when CBLDCRPC('CALL ') was called.
   
3. If the OpenTP1 is being started, CBLDCRPC('CALL ') returns with an error, giving the status code 00320. In this case, a service may be requested normally after activation of the server UAP or OpenTP1 is completed. Since activation of the OpenTP1 is completed when a message log with the message ID KFCA01809-I is output, request a service again after this message appears.

When a service request is issued in an environment where internode load-balancing and extended internode load-balancing are in use:

If a service request is issued in an environment where internode load- balancing and extended internode load-balancing are in use and the requested service at the addressed node is unavailable because of a closed schedule, the OpenTP1 automatically transfers that service request to another node. If one of the following events occurs, however, CBLDCRPC('CALL ') returns with an error, giving the status code 00327:

1. The service was requested from a transaction process and the transaction attribute of the service at the transfer destination node disagrees with that of the closed service.
2. The version of the OpenTP1 residing in the transfer destination node is earlier than the version of the OpenTP1 residing in the node that requested the service.

If the above error return occurs, take actions to reach consistency among:

1. Transaction attributes of SPPs that participate in internode load-balancing and extended internode load-balancing.
2. Versions of OpenTP1 that participate in internode load-balancing and extended internode load-balancing.

When a service request is addressed to the server that receives requests from a socket

The server that receives requests from a socket controls message congestion according to the specified values for max_socket_msg and max_socket_msglen in the user service definition. It is probable that service requests cannot be accepted if a message reaches the defined value. In this case, CBLDCRPC('CALL ') returns with an error, giving the status code 00356. If this status code is returned, the client UAP can sometimes reissue the service request successfully after waiting for a while.

When a chained RPC is used

If CBLDCRPC('CALL ') which is not a transaction is called from the UAP using a chained RPC which is processed as a transaction to the same server UAP, CBLDCRPC('CALL ') returns with an error, giving the status code 00367.

When the online tester is used

If the online tester is in use and CBLDCRPC('CALL ') is called from a UAP in test mode to a UAP in nontest mode or vice versa, CBLDCRPC('CALL ') returns with an error, giving the status code 00366.

When the security facility is used

If the desired service is protected with the security facility and the client UAP which called CBLDCRPC('CALL ') does not have the access permission for the SPP, CBLDCRPC('CALL ') returns with an error, giving the status code 00370.

The following explains the timing when an error is returned to the client UAP if the SPP to which the service request is addressed terminates abnormally.

• Synchronous response-type RPC or chained RPC (when 0 or 4 is specified for data-name-C)
  If an SPP which executes a service terminates abnormally before completion of the processing, CBLDCRPC('CALL ') returns with an error, giving the status code 00307. If an infinite period of time is specified in the watch_time operand in the user service definition of the client UAP, the function returns with an error, giving the status code 00314.
  
• Asynchronous response-type RPC (when 2 is specified for data-name-C)
  If an SPP which executes a service terminates abnormally before completion of the processing, CBLDCRPC('POLLANYR') returns with an error, giving the status code 00307. If an infinite period of time is specified in the watch_time operand in the user service definition of the client UAP, the function returns with an error, giving the status code 00314.
  
• Nonresponse-type RPC (when 1 is specified for data-name-C)
  The client UAP cannot detect abnormal termination of server UAP.
  

When CBLDCRPC('CALL ') results in error due to time monitoring of the client UAP

In the following cases, CBLDCRPC('CALL ') returns with an error, giving the status code 00307, after the time specified in the watch_time operand in the user service definition of the client UAP has elapsed:

• The entire OpenTP1 at the node containing the SPP terminates abnormally.
• An error occurs before the server UAP receives service request data or before the client UAP receives the result after the server UAP processing is completed.

Even if the OpenTP1 to which the service request is issued is not active because it is being started or is engaged in system switching, you can have the OpenTP1 re-execute the requested search and service request transmission without treating CBLDCRPC('CALL ') processing as an error.

To re-execute the requested search and service request transmission, specify Y in the rpc_retry operand in the system common definition. You use the rpc_retry_count and rpc_retry_interval operands to specify the re-executions count and re-execution interval, respectively, for a requested search and service request transmission. If this count value exceeds the re-executions count value specified in the system common definition, CBLDCRPC('CALL ') returns with an error and sets one of the following status code values:

00301

00306

00310

00314

00315

00320

To specify a schedule priority for a service request, call CBLDCRPC('SETSVPRI') immediately before CBLDCRPC('CALL '). If no schedule priority is specified, the priority of the service request is determined according to the default interpretation of the schedule service.

These status codes are returned if the user server corresponding to the service group name is not found.

• 00310
  Indicates the user server is not found after searching all nodes specified for all_node in the system common definition.
  
• 00306
  Indicates a communication error occurred on one or more nodes specified for all_node during the search. This return value may indicate the corresponding OpenTP1 system is not found.
  

You can use the status code 00378 instead of 00307 or 00314 to check whether the SPP that was asked to offer its service abnormally terminated before processing was completed. For this purpose, assign 00000001 to the rpc_extend_function operand in the user service definition. With this specification, the status code 00378 will return if the above error occurs. If nothing or 00000000 is assigned to the rpc_extend_function operand, the status code 00307 or 00314 will be returned, instead of 00378.

The relationship between status codes of CBLDCRPC('CALL ') and synchronization point processing (commitment and rollback) is explained below. The description applies to the service request which is a transaction, rather than the service request which is not a transaction (including the case when 32 is added to the value of data-name-C indicating the RPC mode).

When commitment is performed even though CBLDCRPC('CALL ') returns with an error

The status code 00307 may be returned due to abnormal termination of the service program which the service request is addressed, a node error, or network error. However, when the client UAP is not a transaction, the service program to which the service request is addressed may terminate normally and database may be updated.

Status codes which require rollback processing

If CBLDCRPC('CALL ') called from a transaction returns with an error, some status codes always require rollback processing for the transaction (the server UAP enters rollback_only state). In this case, rollback processing is always performed even if either of the COBOL-UAP creation programs for commitment and rollback is used. The following status codes of CBLDCRPC('CALL ') always require rollback processing for the transaction:

00311

00317

00319

00326

1. Define the service group name and service name at server UAP environment setup. These names are set in CBLDCRPC('CALL '). If a service is requested while invalid service group name or service name is set in CBLDCRPC('CALL '), the function returns with an error, giving the status code 00310 or 00311. If the service program does not return response, CBLDCRPC('CALL ') does not return with an error, giving the status code 00310.
2. The process of the server UAP is different from that of the client UAP. Therefore, the following matters are different from ordinary procedure calls:
   
   • Attributes which are given to the process of the client UAP by the OS (environment variables, schedule priority (nice value), etc.) are not passed on to the server UAP.
   • Environment settings of the OpenTP1 specified at the node of the client UAP (existence of specification of transaction attribute, time limit of transaction branch, schedule priority, etc.) are not passed on to the OpenTP1 of the server UAP.
3. Do not specify the same buffer area for the input parameter and the response from the service program.
4. If 1 is specified for data-name-C, the following status codes will not return:
   
   • Errors which never occur
     00309
     00319
     
   • Errors which cannot be detected even though they could occur
     00311
     00312
     00313
     00316
     00318
     00320
     00370
     
   In addition, OpenTP1 does not output a message when an error occurs. If errors must be detected, consider specifying 0 to data-name-C (synchronous-response-type RPC).
   
5. When a service group is requested by CBLDCRPC('CALL ') from a transaction, an SPP is occupied until the transaction terminates. When the same service is requested more than once by CBLDCRPC('CALL ') from the same transaction, perform the following:
   
   • Re-estimate the values specified for the balance_count operand and parallel_count operand in the user service definition according to the number of usages.
   • Request a service by using chained RPCs so that the number of processes will not increase.
   If the values specified for the balance_count operand and parallel_count operand are incorrect, the transaction will shut down abnormally and a deadlock may occur.
   
6. When an asynchronous response-type RPC is used, the server UAP may be occupied until CBLDCRPC('POLLANYR') receives all asynchronous responses or CBLDCRPC('DISCARDF') rejects the receiving of asynchronous responses. This may occur regardless of whether it is a transaction or not. Increase the number of resident processes according to how many times an asynchronous response-type RPC is used.
   An asynchronous response-type RPC requires many resources in addition to occupying the server UAP. To prevent responses from degrading performance of UAP processing and activation of unnecessary SPPs, ensure that responses are received or the receiving of responses is rejected after CBLDCRPC('CALL ') of an asynchronous response-type RPC is used.
   
7. To receive a response after using the service request in asynchronous-response-type RPC for more than one time continuously, specify a different response storage area as shown below for each service request when requesting an asynchronous-response-type RPC service. If the same area is specified, the response that comes in later will be overwritten and an accurate response cannot be received.
   

   01 unique-name-3-1. 02 data-name-I1 PIC S9(9) COMP. 02 data-name-J1 PIC X(n). 01 unique-name-3-2. 02 data-name-I2 PIC S9(9) COMP. 02 data-name-J2 PIC X(n). 01 unique-name-3-3. 02 data-name-I3 PIC S9(9) COMP. 02 data-name-J3 PIC X(n).

8. The server UAP (SPP) that requested a service using an asynchronous response-type RPC sends a response soon after the service function is executed, regardless of whether the process that executed the asynchronous response-type RPC issued the CBLDCRPC('POLLANYR'). If the same asynchronous response-type RPC is executed numerous times simultaneously without the CBLDCRPC('POLLANYR') being issued, the response sent by the SPP may stay in the TCP/IP buffer and the SPP may fail to send a response. If the SPP fails to send a response, no response can be received from the SPP even if the source of the asynchronous response-type RPC issues the CBLDCRPC('POLLANYR').
9. If a large number of asynchronous response-type RPCs or non-response type RPCs having the transaction attribute are executed, messages about transactions sent by the SPP can no longer be received. In this case, the transactions may roll back.

Specifying a service group name with domain qualification enables requesting an OpenTP1 service in the DNS domain. Specify the service group name suffixed by an at mark (@) and the DNS domain name for domain qualification.

Notes on requesting a service with domain qualification

1. To request a service with domain qualification, add (256 + 32) to the value of data-name-C of CBLDCRPC('CALL ') indicating the RPC mode. If the service group name with domain qualification is specified without addition, CBLDCRPC('CALL ') returns with an error, giving the status code 00310.
2. If an RPC with domain qualification is used, a transaction cannot be extended even if the process which called CBLDCRPC('CALL ') is a transaction. Therefore, to request a service with domain qualification from a transaction, add (256 + 32) to the value of data-name-C of CBLDCRPC('CALL ') indicating the RPC mode in order not to have the transaction extended. When the local domain is specified for the domain name, the transaction also cannot be extended.
3. When an RPC with domain qualification is used, a service request can be addressed only to a server that receives requests from a queue, rather than a server that receives requests from a socket.
4. A service request with domain qualification is sent to the domain-alternate schedule service which is activated on the host registered with the namdomainsetup command. Obtain the port number of the domain-alternate schedule service from /etc/services. If an error occurs while transferring the service request and multiple host names are registered with the namdomainsetup command, the service request is transferred to other hosts sequentially. Even if the RPC with domain qualification terminates normally, an error may occur during transfer to the domain-alternate schedule service.

Preparation for requesting a service with domain qualification

Perform the following environment setup for an RPC with domain qualification:

1. Register the name of the host on which the domain-alternate schedule service is activated by using the namdomainsetup command.
2. Define as follows the port number of the domain-alternate schedule service in /etc/services of the host on which the OpenTP1 which requests a service with domain qualification is activated:
   

   OpenTP1scd port-number/tcp

3. Specify the well-known port of the domain-alternate schedule service for the scd_port operand in the schedule service definition for the OpenTP1 which activates the domain-alternate schedule service.

Client UAP which executes the service ADD

01 unique-name-1. 02 data-name-A PIC X(8) VALUE 'CALL '. 02 STATUS-CODE PIC X(5) VALUE SPACES. 02 FILLER PIC X(3). 02 FLAGS PIC S9(9) COMP VALUE ZERO. 02 DESCRIPTOR PIC S9(9) COMP VALUE ZERO. 02 SERVICE-NAME PIC X(32) VALUE SPACES. 02 GROUP-NAME PIC X(32) VALUE SPACES. 01 unique-name-2. 02 NAME-LENG PIC S9(9) COMP. 02 NAME PIC X(32) VALUE SPACES. 01 unique-name-3. 02 RESULT-LENG PIC S9(9) COMP. 02 RESULT PIC X(20). * MOVE 'ADDRESS-BOOK' TO GROUP-NAME. MOVE 'ADD' TO SERVICE-NAME. MOVE 'SATO' TO NAME. MOVE 4 TO NAME-LENG. MOVE 20 TO RESULT-LENG. CALL 'CBLDCRPC' USING unique-name-1 unique-name-2 unique-name-3. IF STATUS-CODE NOT = '00000' THEN DISPLAY 'FAILED' END-IF. STOP RUN.

Server UAP which executes the service ADD

PROGRAM-ID. ADD. DATA DIVISION. LINKAGE SECTION. 01 unique-name-1. 02 ADD-NAME PIC X(20). 01 unique-name-2. 02 NAME-LENG PIC S9(9) COMP. 01 unique-name-3. 02 RESULT PIC X(20). 01 unique-name-4. 02 RESULT-LENG PIC S9(9) COMP. : : PROCEDURE DIVISION USING unique-name-1 unique-name-2 unique-name-3 unique-name-4. : * Processes the contents of the received unique-name-1 : MOVE 'ADD-COMPLETE' TO RESULT. MOVE 12 TO RESULT-LENG. EXIT PROGRAM.

Assume that you want to perform a transactional RPC on an OpenTP1 system other than the domain specified in the all_node clause of the system common definition. In this case, you must ensure that the node identifiers (node_id clause of the system common definition) of all OpenTP1 systems in the local domain and remote domain are unique. In addition, all the OpenTP1 systems must be version 03-02 or later. If these conditions are not met, the transaction may not recover properly.