Enable_UTM_UPIC - Signing on to the UPIC carrier system

This call must be issued before other CPI-C calls are used. The Enable_UTM_UPIC (CMENAB) call enables a program to sign on to the UPIC carrier system using its own name. The name serves to establish the connection between the CPI-C program and the UTM application (see also section “Initialize_Conversation - Initializing the conversation characteristics”).

In the upicfile, you can define a default name for the CPI-C application (LN.DEFAULT entry; see "Side information for the local application"). If the CPI-C program is to connect to the UPIC carrier system with this default name, it can specify an “empty local name” in the local_name field. UPIC then searches in the upicfile for the LN.DEFAULT entry and uses the corresponding local application name to establish the connection to the UTM application. Several CPI-C program runs can connect with the default name simultaneously and also establish conversations to the same UTM service.

After the Enable_UTM_UPIC call has been executed successfully, the program is provided with an intact runtime environment. After this call is issued, changes in the upicfile do not come into effect for the program until the next Enable_UTM_UPIC call.

This function is not included in the CPI-C interface, but is one of the additional UPIC functions.

Syntax

CMENAB (local_name, local_name_length, return_code)

Parameters

--> local_name	Name of the program. The following specifications are possible (see also section “Side information for the local application”): with UPIC remote: Local application name defined in the upicfile. Name under which the program is known in CMX. Any name, whose properties can still be modified using the following Specify calls. Empty local application name. The program then signs on to UPIC under the DEFAULT name of the CPI-C application, provided that an LN.DEFAULT entry exists in the upicfile at the time of the call. with UPIC local on Unix, Linux and Windows systems: PTERM name by which the client is known in the configuration of the UTM application. Local application name defined in the upicfile. If an LTERM pool for the partner type UPIC-L (TPOOL with PTYPE=UPIC-L) exists in the UTM partner application, you can specify any name of up to 8 characters for local_name. Empty local application name. The prerequisite is that an LN.DEFAULT entry exists in the upicfile at the time of the call. You can transfer an empty local application name by: transferring 8 blanks in local_name and setting local_name_length=8 setting local_name_length=0. If you transfer an empty application local name, UPIC takes the application name of the LN.DEFAULT entry to establish the connection to the UTM partner application.
--> local_name_length	Length of local_name Minimum: 0, maximum: 8 If a local application name from the upicfile is entered in local_name, then local_name_length=8 must be specified. If you specify local_name_length=0, the contents of the local_name field will be ignored, that is local_name will be treated as an “empty local name”. An LN.DEFAULT entry must exist in the upicfile.
<-- return_code	Result of the function call

Result ( return_code )

CM_OK

The call is OK.

CM_PROGRAM_STATE_CHECK

The program is already signed on to UPIC.

CM_PROGRAM_PARAMETER_CHECK

Possible causes:

• the value of local_name_length is less than 1 or greater than 8

• there is not enough internal memory available, or

• an attempt to access the upicfile has failed

CM_PRODUCT_SPECIFIC_ERROR

Possible causes:

• The UPIC instance could not be found

• With UPIC local on Unix, Linux and Windows systems only: the environment variable UTMPATH is not set

State change

If the return code is CM_OK, the program enters the “Reset” state. In all other cases, the program does not change its state.

Notes

• Several CPI-C program runs with the same name can connect to the UPIC carrier system simultaneously.

• A CPI-C program which has been started more than once can also connect to the same UTM application more than once with the same name (e.g. the application name assigned to the DEFAULT name). For this purpose, the UTM application must be configured as follows:

  • There must be no LTERM partner explicitly generated for this openUTM-Client, i.e. no PTERM with its name and PTYPE=UPIC-R must exist for this system in the configuration of the UTM application.

  • An LTERM pool (TPOOL) with CONNECT-MODE=MULTI is generated for the system on which the client is running. The CPI-C program can then connect to the UTM application under the same name as often as there are LTERM partners available in the LTERM pool (the number is set by UTM administration).

• with UPIC local on Unix, Linux and Windows systems only: To enable the CPI-C program to connect to the local UTM application, the environment variable UTMPATH must be set.In rare cases it can occur with local communication that the function terminates with CM_PROGRAM_STATE_CHECK, even though shortly beforehand Disable_UTM_UPIC was called and CM_OK returned. The cause is an incomplete disconnect within the UTM application.

Behavior in the event of errors

CM_PRODUCT_SPECIFIC_ERROR

• The operating system cannot provide sufficient memory for internal buffers. Check whether the memory requirement of your program is too high; if necessary, reboot your system.

• With UPIC local Unix, Linux and Windows systems only: Set the UTMPATH environment variable and restart the program.

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

• Modify program.

• Increase the virtual memory if necessary.

Function declaration: Enable_UTM_UPIC

CM_ENTRY Enable_UTM_UPIC ( unsigned char CM_PTR  local_name,
                          CM_INT32       CM_PTR  local_name_length,
                          CM_RETURN_CODE CM_PTR  return_code)