The interface functions can be used on all platforms in the programming languages C, C++ and COBOL, and are provided in libraries.
The following description of the CPI-C calls has therefore been kept as language-independent as possible, even though it uses the notation of the C interface. In section“COBOL interface” you will find a description of the special features of the COBOL interface which you must take into account when creating CPI-C programs in COBOL.
The precise function declaration is given separately for each call.
Program calls
A client communicates with a UTM server application by calling functions. These calls are used to establish the conversation characteristics and to exchange data and control information. The CPI-C calls supported by UPIC can be categorized into two groups:
Starter-set calls
Starter-set calls enable simple communication with a UTM server. They are used for simple data exchange processes, e.g. for accepting the initialized values of conversation characteristics.Advanced-function calls
Advanced-function calls allow more specialized functions to be executed. For example, the conversation characteristics can be modified using Set calls.
Starter-set functions
Function | Description |
Initialize_Conversation | Initializes conversation characteristic |
Allocate | Starts a conversation |
Deallocate | Ends a conversation abnormally |
Send_Data | Sends data |
Receive | Receives data |
Table 7: Starter-set functions
It is assumed that the CPI-C program (client) is always the active part. For this reason the CPI-C function Accept_Conversation is not supported.
On systems which support multithreading (e.g. Windows, Solaris 5.7), several conversations with different UTM servers can be active at the same time in a CPI-C program. Each conversation, including the associated Enable_UTM_UPIC and Disable_UTM_UPIC calls, must be executed in a separate thread.
On all other systems, only one conversation at a time can be active in a CPI-C program.
Advanced-function calls
Function | Description |
Convert_Incoming | Converts received data to the local code |
Convert_Outgoing | Converts the data to be sent from the local code to the code of the communication partner |
Deferred_Deallocate | Terminates the conversation as soon as the current transaction has been terminated successfully |
Extract_Conversation_State | Inquires about the conversation state |
Extract_Secondary_Information | Inquires about further information |
Extract_Partner_LU_Name | Inquires about the value of the conversation characteristics partner_LU_name up to a maximum length of 32 bytes |
Extract_Partner_LU_Name_Ex | Inquires about the value of the conversation characteristics partner_LU_name in full length |
Prepare_To_Receive | Sends the data buffered in the send buffer to the communication partner immediately and switches to the “Receive” state |
Receive_Mapped_Data 1 | Receives the data together with the structure information (format identifier) |
Send_Mapped_Data 1 | Sends the data together with the structure information (format identifier) |
Set_Conversation_Security_Password | Sets the password for a UTM user ID |
Set_Conversation_Security_Type | Activates or deactivates the security function |
Set_Conversation_Security_User_ID | Sets the UTM user ID |
Set_Partner_LU_name | Sets the value for the conversation characteristics partner_LU_name |
Set_Deallocate_Type | Sets values for the conversation characteristic deallocate_type |
Set_Receive_Type | Sets values for the conversation characteristic receive_type |
Set_Sync_Level | Sets values for the conversation characteristic sync_level |
Set_TP_Name | Sets the name for a partner program (transaction code) |
Table 8: Advanced Functions
1Not a component of X/Open CPI-C version 2
Additional UPIC functions
Function | Description |
Enable_UTM_UPIC | Signs on to the UPIC carrier system |
Extract_Client_Context | Outputs the client context |
Extract_Conversation_Encryption_Level | Inquires about encryption level |
Extract_Convertion | Queries the ASCII-EBCDIC conversion |
Extract_Cursor_Offset | Inquires about cursor position offset |
Extract_Max_Partner_Index | Queries the maximum index of the partner applications |
Extract_Secondary_Return_Code | Queries secondary return codes |
Extract_Shutdown_State | Queries the shutdown state of the server |
Extract_Shutdown_Time | Queries the shutdown time of the server |
Extract_Transaction_State | Queries the service and transaction state of the server |
Disable_UTM_UPIC | Signs off from the UPIC carrier system |
Set_Allocate_Timer | Setting timer for the Allocate call |
Set_Client_Context | Sets the client context |
Set_Convertion | Sets the ASCII-EBCDIC conversion |
Set_Conversation_Encryption_Level | Sets encryption level |
Set_Conversation_Security_New_Password | Sets a new password for a UTM user ID |
Set_Function_Key | Sets the value of the function key to be transferred |
Set_Partner_Index | Sets the index of the partner application |
Set_Receive_Timer | Sets the timeout timer for the blocking receive of data |
Set_Partner_Host_Name | Sets the host name of the partner application |
Set_Partner_IP_Address | Sets the IP address of the partner application |
Set_Partner_Port | Sets the TCP/IP port of the partner application |
Set_Partner_Tsel | Sets the TSEL of the partner application |
Set_Partner_Tsel_Format | Sets the TSEL format of the partner application |
Specify_Local_Tsel | Sets the TSEL of the local application |
Specify_Local_Tsel_Format | Sets the TSEL format of the local application |
Specify_Local_Port | Sets the TCP/IP port of the local application |
Specify_Secondary_Return_Code | Sets the properties of the secondary return code |
Table 9: Additional UPIC Functions