(a) In a multi-thread environment

PROCEDURE DIVISION

 
CALL 'CBLDCRPS' USING identifier-1 identifier-2 identifier-3
 

DATA DIVISION

 
01 identifier-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(32).
   02 data-name-G PIC 9(9)  COMP.
01 identifier-2.
   02 data-name-H PIC S9(9) COMP.
   02 data-name-I PIC X(n).
01 identifier-3.
   02 data-name-J PIC S9(9) COMP.
   02 data-name-K PIC X(n).
 

(b) In a single-thread environment

PROCEDURE DIVISION

 
CALL 'CBLDCRPC' USING identifier-1 identifier-2 identifier-3
 

DATA DIVISION

 
01 identifier-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(32).
01 identifier-2.
   02 data-name-H PIC S9(9) COMP.
   02 data-name-I PIC X(n).
01 identifier-3.
   02 data-name-J PIC S9(9) COMP.
   02 data-name-K PIC X(n).
 

Requests an SPP service by calling the service program that matches the service group name and the service name and receiving its response.

OpenTP1 must be active for the node corresponding to the server UAP for which the service is requested. If OpenTP1 is inactive due to a startup procedure, for example, the CBLDCRPS('CALL ') program returns an error with status code 02406, 02415, or 02420. The program returns an error with status code 02412 when it is executed but the target service group is shut down. The program returns an error with status code 02413, 02412, or 02410 when it is executed but the target service group is terminating or has been terminated due to a dcsvstop command, for example. Which status code returns depends on the timing when the CBLDCRPS('CALL ') program was executed.

A socket-receiving type server concurrently controls messages by specifying max_socket_msg and max_socket_msglen in the user service definition. This may prevent receiving service requests. In this case, CBLDCRPS('CALL ') returns an error with status code 02456. When this value returns, wait a while, then reexecute the CUP. You may succeed in the service request.

For the normal communication mode, specify the host name and port number of the XDM/DCCM3 logical terminal in DCCLTSERVICEGROUPLIST in the client environment definition, and then execute CBLDCRPS('CALL ').

(a) Values passed to server UAP

The CUP allocates an area (data-name-K) for responding to the service program. It also specifies the following values for CBLDCRPS('CALL ').

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

These values are same as those specified for CBLDCRPS('CALL ') in the CUP and are passed (and unchanged) to the service program. When you call services of a service program that returns no response, the response length, if specified, is ignored. The maximum values for the input parameter length and response length are defined with DCRPC_MAX_MESSAGE_SIZE^# in the dcvrpc.h header file.

# If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

(b) Values returned from server UAP

You can reference the following values after termination of the service program.

• Service program response (data-name-K)
• Service program response length (data-name-J)

Data-name-J shows the length of a response actually returned from the service program.

After CBLDCRPS('CALL ') returns, a synchronous-response type RPC (data-name-C set to 0) can reference data-name-K and data-name-J. A no-response type RPC (data-name-C set to 1) cannot reference these values. When CBLDCRPS('CALL ') returns an error, data-name-K and data-name-J cannot be referenced.

When the returned response exceeds the response area (data-name-K) allocated by the CUP, the program returns an error with status code 02409.

• data-name-A
  Set VALUE'CALL ' as a request code for the remote service request.
  
• data-name-C
  Specify the RPC type as follows.
  0: Synchronous-response type RPC
  1: No-response type RPC
  4: Chained RPC
  When you specify 0 or 4 for data-name-C, CBLDCRPS('CALL ') does not return until a response returns or a response wait timeout error occurs based on the DCWATCHTIM value in the client environment definition. When the service-requested SPP aborts, the program immediately returns an error. The returned status code depends on the response wait time specified with DCWATCHTIM as follows.
  DCWATCHTIM = 1-65535:02407
  DCWATCHTIM = 0 (infinite wait): 02414
  You cannot specify a response wait time for each service-requested service program or for each service request.
  When you specify 1 for data-name-C, the system assumes that the requested service does not return a response. Therefore, CBLDCRPS('CALL ') immediately returns without waiting for the service to terminate. When data-name-C = 1, you cannot reference the response (data-name-K) and the response length (data-name-J). The CUP cannot determine if the service program was executed.
  You can change an RPC issued from the transaction to a service request that is not a transaction. To do this, specify 32 for the parameter that indicates the RPC type. The service request for the corresponding CBLDCRPS('CALL ') program will be a non-transaction service request.
  32: Synchronous-response type RPC
  33: No-response type RPC
  36: Chained RPC
  If you specify 4 either not in a transaction or when the permanent connection is not being established, the program returns an error with status code 02401.
  
• data-name-E
  Set a service group name using up to 31 ASCII characters ending with a blank.
  
• data-name-F
  Set a service name using up to 31 ASCII characters ending with a blank.
  
• data-name-G
  Specify the client ID received with CBLDCCLS('CLTIN ') or CBLDCCLS('EXCLTIN ').
  
• data-name-H
  Set the input parameter length (data-name-I length) except the length of data-name-H itself. Available values range from 1 to DCRPC_MAX_MESSAGE_SIZE^#.
  

  # If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

• data-name-I
  Set an input parameter.
  
• data-name-J
  Set the response storage area length (data-name-K length) except the length of data-name-J itself. Available values range from 1 to DCRPC_MAX_MESSAGE_SIZE^#.
  

  # If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

• data-name-K
  Specify the area for storing the response. This area must be larger than the length specified for data-name-J.
  

• data-name-B
  5-digit status code.
  
• data-name-D
  Area used for OpenTP1.
  
• data-name-J
  Response length (data-name-K length). This value is not returned when DCRPC_NOREPLY is specified in data-name-C.
  
• data-name-K
  Response. This value is not returned when DCRPC_NOREPLY is specified in data-name-C.
  

Status code	Meaning
00000	Normal termination
02401	Invalid value for the data name. The request code (data-name-A) may be invalid.
02402	CBLDCRPS('OPEN ') has not been executed.
02403	One of the following errors occurs. Initialization failed. No user authentication is performed. The client environment definition is specified invalidly.
02404	Insufficient memory
02406	Network error
02407	Timeout occurred during execution of CBLDCRPS('CALL '). Alternatively, the SPP requested to provide a service terminated abnormally before completing the processing.
02408	The input parameter length exceeds the maximum value.
02409	The returned response length exceeds the area provided by the CUP.
02410	The service group name specified for data-name-F is undefined.
02411	The service name specified for data-name-E is undefined.
02412	The service group that contains the service specified with data-name-E is shut down.
02413	The specified service is being terminated.
02414	The SPP requested to provide a service was not started, or terminated abnormally before completing the processing. This value is returned when 0 is specified for DCWATCHTIM in the client environment definition (infinite response wait is specified).
02415	OpenTP1 is inactive for the node corresponding to the specified service.
02416	The specified service caused a system error.
02417	The specified service caused insufficient memory.
02418	System error
02419	The response length returned from the service program to OpenTP1 is outside the range from 1 to DCRPC_MAX_MESSAGE_SIZE#.
02420	OpenTP1 is starting up on the service-requested node.
02423	Insufficient memory
02424	System error
02425	The specified service caused a system error.
02426	The returned response exceeds the area provided by the CUP.
02427	Two or more SPPs use different transaction attributes when the inter-node load balancing facility is used. This status code returns only when a service is requested for SPP that uses the inter-node load balancing facility.
02442	A permanent connection was released.
02456	A service request was issued to the socket-receiving type server, which could not receive the request.
02466	A service request was issued to an SPP for which test_mode=no was specified in the user service definition in an environment where DCUTOKEY was specified in the client environment definition. Alternatively, a function was called in an environment where the following conditions were satisfied: DCUTOKEY was specified in the client environment definition. A permanent connection with the CUP executing process was being established. The service request was issued outside the transaction. A service request was issued to an SPP for which a value other than test_mode=no was specified in the user service definition.
02467	After a chained RPC has been used for transaction processing, CBLDCRPS('CALL ') that sets 32 as data name C issues a service request.
02470	The service-requested SPP is protected by the security facility. The UAP that called CBLDCRPS('CALL ') has no access right to the server UAP.
02472	Transaction branches cannot be started because the number of transaction branches that can be started concurrently has been exceeded, or because the maximum number of child transaction branches that can be started from one transaction branch has been exceeded. Alternatively, 32 is not set at data name C in a service request qualified by a domain in a transaction.
02478	The SPP requested to provide a service terminated abnormally before completing the processing. This value is returned when 00000001 is specified for DCEXTENDFUNCTION in the client environment definition. If 00000000 is specified or the specification is omitted, 02407 or 02414 returns as the status code.
02479	Since the version of service-requested TP1/Server Base is old (before 03-03), the data compression cannot be used. This status code is returned when the service is requested within the range of the transaction.
02544	The client ID specified for data-name-G differs from the one received with CBLDCCLS('CLTIN ') or CBLDCCLS('EXCLTIN ').
02547	The specified port number is in use. Alternatively, port numbers that can be assigned automatically by the operating system are insufficient.

# If you specify 2 or a larger value for DCCLTRPCMAXMSGSIZE in the client environment definition, the value you specify is used rather than the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

• Do not specify the same buffer for input parameters and a service program response.
• When data-name-C = 1, the following status codes do not return.
  

  Errors that do not occur

  02409

  02419

  Errors that cannot be detected if occurred

  02411

  02412

  02413

  02416

  02417

  02420

• Status code 02407 may return due to the following conditions.
  
  • Too small a value is specified as the maximum response wait time in the client environment definition.
  • The service-requested SPP issued a service program, which terminated abnormally.
  • An error occurred on the node that contains the service-requested SPP.
  • The service-requested SSP abnormally terminated before processing of it finishes.
  • A network error occurred.
  Any of these situations may commit the transaction initiated from the service-requested SPP and update the database. Check to see if the database is updated.
  
• After the CUP executes CBLDCTRS('BEGIN '), executing CBLDCRPS('CALL ') may return the following status codes. If so, execute a program that requests rollback as needed.
  02407
  02411
  02417
  02419
  02423
  02424
  02425
  02426