Set_Function_Key - Setting a UTM function key

The Set_Function_Key (CMSFK) call sets the value for the function_key characteristic. function_key specifies a function key of the UTM partner application.

The value of function_key is transferred to the UTM application together with the data of the next Send_Data or Send_Mapped_Data call, and the function assigned to this function key in the UTM application is executed. The CPI-C program has in effect “pressed the function key”.

The Set_Function_Key call is only permitted in the “Send” or “Receive” states.

Set_Function_Key is not part of the CPI-C Specification, but is an additional function of the UPIC carrier system.

Syntax

CMSFK (conversation_ID, function_key, return_code)

Parameters

--> conversation_ID	Identifier of the conversation
--> function_key	“Function key” that the local CPI-C program wants to “press” in the remote UTM application. The function keys must be specified in the format CM_FKEY_fkey, where fkey is the number of the K or F key to be “pressed”. Example: if function key F10 of the UTM partner application is to be “pressed”, you must specify for function_key the value CM_FKEY_F10. openUTM on Unix, Linux and Windows systems support the function keys F1 through F20. openUTM on BS2000 systems supports the function keys K1 through K14 and F1 through F24. The value CM_UNMARKED specifies that no function key is set.
<-- return_code	Result of the function call.

Result (return_code)

CM_OK

The call is OK.

CM_PROGRAM_STATE_CHECK

The conversation is not in the “Send” or “Receive” state.

CM_PROGRAM_PARAMETER_CHECK

The conversation_ID or function_key is invalid.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

CM_MAP_ROUTINE_ERROR

In the UTM partner application, function keys are not supported in the UPIC protocol.

State change

If there are no errors, this function returns the result CM_OK. This call does not change the state of the program.

Notes

• With openUTM on Unix, Linux and Windows systems, function keys are only effective in format mode, i.e. when the Send_Mapped_Data and Receive_Mapped_Data calls are used to exchange data.

• The function key specified in Set_Function_Key is only transferred to the UTM partner application together with the data of the subsequent Send_Data or Send_Mapped_Data call.
  As soon as the value of function_key is sent to UTM, function_key is reset to CM_UNMARKED (no function key) in the local CPI-C program.

• If the UTM partner application receives a function key from a UPIC client, only the RET parameter of the SFUNC control statement which describes the function key is interpreted. RET contains the return code which appears in the KCRCCC field of the communication area after the MGET call of the UTM service. If the RET parameter is not generated for the function key, UTM always supplies the return code 19Z with the MGET call (function key not generated or special function invalid).

Behavior in the event of errors

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

The operating system cannot provide sufficient memory for the internal buffers. Check whether the memory requirements of your program are too high and if necessary reboot your system.

Function declaration: Set_Function_Key

CM_ENTRY Set_Function_Key ( unsigned char CM_PTR  conversation_ID,
                           CM_INT32       CM_PTR  function_key,
                           CM_RETURN_CODE CM_PTR  return_code)