OpenTP1 Version 7 Programming Reference COBOL Language
CBLDCRPC('CALL ') - Request a remote service
Format
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). |
Description
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 areas whose values are set in the UAP
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.
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.
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.
Data areas to which values are returned from server UAP
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.
Status codes
The following status codes are returned from OpenTP1, not from the service program.
Status code | Explanation |
---|---|
00000 | Normal termination. In the case of asynchronous response-type RPC, the descriptor was set in data-name-D. |
00301 | The value specified for the data-name is invalid. This error also occurs if the request code (data-name-A) is invalid. |
00302 | CBLDCRPC('OPEN ') was not called. |
00304 | A memory shortage occurred. Or, a service request was not accepted because a space shortage occurred in the message storage buffer pool (message_store_buflen operand) of the SPP to which the service was requested. If necessary, revise the message_store_buflen operand in the user service default definition or in the user service definition of the SPP to which the service was requested. |
00306 | A communication failure occurred. Check if a network failure has occurred. |
00307 | The response wait time in CBLDCRPC('CALL ') has elapsed. If necessary, revise the response wait time specified in CBLDCRPC('CALL ') (watch_time operand and arguments in CBLDCRPC('SETWATCH')). |
The SPP to which the service was requested terminated abnormally during execution of a service program. Check the cause of abnormal termination of the SPP to which the service was requested. |
|
00308 | The input parameter length specified in data-name-G exceeded the maximum. If necessary, revise the data-name-G setting. |
00309 | The length of the response (data-name-D of the service program) set in the service program of the SPP to which the service was requested exceeded the response length (data-name-I of the service program) in CBLDCRPC('CALL '). If necessary, revise the response length (data-name-D of the service program) set in the service program of the SPP to which the service was requested. |
00310 | The service group name set in data-name-F is invalid, or the SPP to which the service was requested with the service group set in data-name-F was not running. If necessary, revise the data-name-F setting, or start the SPP to which the service was requested with the service group set in data-name-F. |
00311 | The service name set in data-name-E is invalid, or the service name set in data-name-E by the SPP to which the service was requested has not been specified in the service operand in the user service definition file. If necessary, revise the data-name-E setting, or specify the service name set in data-name-E also in the service operand for the SPP to which the service was requested. |
00312 | The SPP to which the service was requested with the service group set in data-name-F is under server shutdown or service shutdown status. Check the cause of the shutdown, and then release the SPP from shutdown status. |
00313 | The SPP to which the service was requested is under termination processing. |
00314 | The SPP to which the service was requested with the service group set in data-name-F is not running, or a communication failure might have occurred during the service request send processing. Start the SPP to which the service was requested with the service group set in data-name-F. If the SPP is already running, check to see if a network failure has occurred. |
While 0 was specified for the service request response time (watch_time operand and an argument in CBLDCRPC('SETWATCH')), the SPP to which the service was requested terminated abnormally during execution of a service program. Check the cause of abnormal termination of the SPP to which the service was requested. |
|
00315 | OpenTP1 for the SPP to which the service was requested is not running. OpenTP1 might be under termination processing or a communication failure might have occurred during the service request send processing. Start OpenTP1 for the SPP to which the service was requested, or check for a network failure. |
00316 | A system error (internal conflict) occurred in the SPP to which the service was requested. |
00317 | A memory shortage occurred in the SPP to which the service was requested. |
00318 | A system error (internal conflict) occurred in the UAP that requested the service. |
00319 | The response length (data-name-D of the service program) set by a service program of the SPP to which the service was requested is outside the range from 1 to the value defined in DCRPC_MAX_MESSAGE_SIZE.# If necessary, revise the response length (data-name-D of the service program) in the service program of the SPP to which the service was requested. |
00320 | OpenTP1 for the SPP to which the service was requested is under start processing. |
00323 | A memory shortage occurred in the UAP that is requesting the service or the SPP to which the service was requested. When this value is returned, the transaction branch rolls back. Check if unneeded memory is allocated by the UAP that is requesting the service or the SPP to which the service was requested. |
00324 | A system error (internal conflict) occurred in the UAP that requested the service. When this value is returned, the transaction branch rolls back. |
00325 | A system error (internal conflict) occurred in the SPP to which the service was requested. When this value is returned, the transaction branch rolls back. |
00326 | The response length (data-name-D of the service program) set in the service program of the SPP to which the service was requested exceeded the response length (data-name-I of the service program) in CBLDCRPC('CALL '). When this value is returned, the transaction branch rolls back. If necessary, revise the response length (data-name-D of the service program) set in the service program of the SPP to which the service was requested. |
00327 | When the inter-node load-balancing facility and the extended internode load-balancing facility are used, the transaction attributes (atomic_update operand) do not match among the SPPs with the same service group name to which the service was requested. Another possibility is that the inter-node load-balancing facility and the extended internode load-balancing facility cannot be used because the version of OpenTP1 at the node to which loads are to be distributed is earlier than that of the OpenTP1 for the UAP that is requesting the service. This value is returned only when the service request is issued to an SPP that uses the inter-node load-balancing facility and the extended internode load-balancing facility. If necessary, revise the transaction attribute (atomic_update operand) of the SPP that uses the inter-node load-balancing facility and the extended internode load-balancing facility, or revise if necessary the version of OpenTP1. |
The dcsvgdef definition command was used to issue a service request to a user server with the non-transaction attribute (atomic_update is N in the user service definition or jnl_fileless_option is Y in the system common definition). However, 32 was not added to data-name-C for CBLDCRPC('CALL '). | |
00328 | The domain name of the service group name with the domain qualification in data-name-F is invalid. If necessary, revise the domain name. |
00329 | A service was requested with a domain qualification in data-name-F, but the port number of the domain representative schedule service was not found. If necessary, revise the domain_masters_port operand setting in the system common definition and the port number setting for the domain representative schedule service in /etc/services. |
00356 | The SPP to which the service was requested (the server that receives requests from socket) cannot receive the service request. If necessary, revise the max_socket_msg and max_socket_msglen operands in the user service definition or the user service default definition for the SPP to which the service was requested. |
00366 | When the online tester was being used, a service request was issued from a UAP in the test mode to an SPP in the nontest mode or from a UAP in the nontest mode to an SPP in the test mode. If necessary, revise the UAP's test mode setting. |
00367 | CBLDCRPC('CALL ') with nontransaction setting specified for data-name-C was called to request a service after a chained RPC with the transaction attribute was executed. |
00370 | The SPP to which the service was requested is protected by the security facility. The UAP that requested the service by executing CBLDCRPC('CALL ') does not have permission to access the SPP to which the service was requested. If necessary, revise the access permissions for the SPP to which the service was requested. |
00372 | The transaction branch cannot be started because it exceeds the maximum number of transaction branches that can be activated concurrently in the OpenTP1 for the SPP to which the service was requested. If necessary, revise the setting in the trn_tran_process_count operand in the transaction service definition. |
The transaction branch cannot be started because it exceeds the maximum number of child transaction branches that can be activated from one transaction branch by the UAP that is requesting the service. If necessary, revise the setting in the trn_max_subordinate_count operand in the transaction service definition. |
|
32 is not added to the value specified for data-name-C when a service with domain qualification specified in a transaction is requested. | |
Transaction branching cannot start because the SPP to which the service was requested encountered a resource manager (RM) error. Eliminate the cause of the resource manager (RM) error and then re-execute the function. |
|
In the System Environment window of TP1/LiNK, the Transaction Facility item is not set to Yes. If necessary, revise the Transaction Facility setting in the System Environment window of TP1/LiNK. |
|
00378 | The SPP that received the service request terminated abnormally during execution of the service program. If necessary, revise the service program processing of the SPP that received the service request. This status code is returned only when "00000001" is specified in the pc_extend_function operand in the user service definition of the UAP that requested the service. When "00000000" is specified in the rpc_extend_function operand or when this operand is omitted, status code 00307 or 00314 is returned, instead of 00378. |
(1) Data areas of CBLDCRPC('CALL ')
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 ').
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.
Values returned from server UAP
When the service program terminates and response is returned, the following values can be referenced:
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:
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.
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.
(2) Error cases of CBLDCRPC('CALL ')
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:
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:
If the above error return occurs, take actions to reach consistency among:
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.
(3) Timing when CBLDCRPC('CALL ') results in error
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.
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:
(4) Specification for reexecuting the service request if CBLDCRPC('CALL ') results in error
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
(5) When a priority is given to a service request
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.
(6) Difference between status codes 00310 and 00306
These status codes are returned if the user server corresponding to the service group name is not found.
(7) Specification for the return of status code 00378
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.
(8) Relationship between status codes and synchronization point processing
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
(9) Notes on requesting a service
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). |
(10) When a service is requested with domain qualification
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
Preparation for requesting a service with domain qualification
Perform the following environment setup for an RPC with domain qualification:
OpenTP1scd port-number/tcp
Example
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. |
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. |
Note
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.
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.