Receive_Mapped_Data - Receiving data and format identifier from a UTM service

A program uses the Receive_Mapped_Data (CMRCVM) call to receive information from a UTM service. The information received can be either data, a format identifier and/or permission to send.

The program must repeat the Receive_Mapped_Data-call until the return value of return_code is unequal CM_OK or status_received=CM_SEND_RECEIVED.

The call can be executed with or without blocking.

• The Receive_Mapped_Data call is “blocking” when the receive_type characteristic has the value CM_RECEIVE_AND_WAIT.
  If no information (data or permission to send) is present at the time of the Receive_Mapped_Data call, the program run waits in Receive_Mapped_Data until information is available for this conversation. Only then does the program run return from the Receive_Mapped_Data call and bring back the information. If there is information available at the time of the call, the program receives it without waiting.

  To limit the wait time for a blocking Receive_Mapped_Data call, appropriate timers should be set in the UTM partner application.

• The Receive_Mapped_Data call is “non-blocking” when the receive_type characteristic has the value CM_RECEIVE_IMMEDIATE.
  If no information is present at the time of the Receive_Mapped_Data call, the program run does not wait until information for this conversation arrives. The program run returns from the Receive_Mapped_Data call immediately. If there is already information available, it is transferred to the program.

You can set the receive_type characteristic with the Set_Receive_Type call before the Receive_Mapped_Data call.

Syntax

CMRCVM (conversation_ID, map_name, map_name_length, buffer, requested_length, data_received, received_length, status_received, control_information_received, return_code)

Parameters

--> conversation_ID	Identifier of the conversation.
<-- map_name	Format identifier sent to the CPI-C program by the UTM partner application together with the data. The format identifier specifies the structure information for the received data.
<-- map_name_length	Length of the format identifier in map_name.
<-- buffer	Buffer in which the data is received. If the return value of data_received is CM_NO_DATA_RECEIVED, the contents of buffer are undefined.
--> requested_length	Maximum length of data that can be received.
<-- data_received	Specifies whether data was received in the conversation. data_received can have one of the following values: CM_NO_DATA_RECEIVED No data was available for the program. Permission to send may have been received. CM_COMPLETE_DATA_RECEIVED A complete message (segment) available for the program was received. CM_INCOMPLETE_DATA_RECEIVED A message (segment) was not transferred in full to the program. If data_received has this value, the program must issue repeated Receive or Receive_Mapped_Data calls until the message (segment) is received in its entirety, i.e. until data_received has the value CM_COMPLETE_DATA_RECEIVED. The value of data_received is undefined if the result of the call is not CM_OK or CM_DEALLOCATED_NORMAL.
<-- received_length	Length of the data received. If the program has not received data (data_received=CM_NO_DATA_RECEIVED) or if the result is not CM_OK or CM_DEALLOCATE_NORMAL, the value of received_length is undefined.
<-- status_received	Specifies whether the program received permission to send. status_received can have one of the following values: CM_NO_STATUS_RECEIVED Permission to send was not received. CM_SEND_RECEIVED The UTM service has passed permission to send to the program. The program must then issue a Send_Data call. Unless the return code is CM_OK, the value of status_received is undefined.
<-- control_information_received	This is only supported syntactically and always has the value CM_REQ_TO_SEND_NOT_RECEIVED. If the return code is not CM_OK or CM_DEALLOCATE_NORMAL, the value of control_information_received is undefined.
<-- return_code	Result of the function call.

Result ( return_code )

CM_OK

The call is OK. The program has one of the following states after function call:

“Receive”, if the value of status_received is CM_NO_STATUS_RECEIVED.

“Send”,   if the value of status_received is CM_SEND_RECEIVED.

CM_SECURITY_NOT_VALID

Possible causes:

• an invalid UTM user ID in the Set_Conversation_Security_User_ID call

• an invalid password in the Set_Conversation_Security_Password call

• the UTM application was configured without user IDs (USER statements).

• the user cannot sign on to the UTM application due to a resource bottleneck.

If the UPIC application communicates with an openUTM application that returns a detailed result of the authorization check, the UPIC library supplies a secondary return code that describes the cause in detail. The results received by the program are listed under secondary_return_code, see "Receive_Mapped_Data - Receiving data and format identifier from a UTM service".

The secondary return codes can also be queried using the Extract_Secondary_Return_Code call, see "Extract_Secondary_Return_Code - Querying secondary return codes".

CM_TPN_NOT_RECOGNIZED

Possible causes:

• a service restart with KDCDISP was rejected as no UTM user ID configured with RESTART=YES was specified.

• an invalid transaction code (TAC) in the upicfile or in the Set_TP_Name call, e.g.:

  • the TAC is not configured

  • you are not authorized to call this TAC

  • the TAC is permitted only as a follow-up TAC

  • the TAC is not a dialog TAC

  • The TAC is configured with encryption but user data was sent without encryption, or encryption is not supported for the connection, or the
    encrypted data does not have the required encryption level.

• Service restart using KDCDISP was rejected because no UTM user ID configured with RESTART=YES was specified.

CM_TP_NOT_AVAILABLE_NO_RETRY

A service restart with KDCDISP is not possible as the UTM application has been re-configured.

CM_TP_NOT_AVAILABLE_RETRY

A service restart was rejected as the UTM application has been terminated.

CM_DEALLOCATED_ABEND

Possible causes:

• abnormal termination of the UTM service

• termination of the UTM application

• connection shutdown by UTM administration

• connection shutdown by the transport system

• connection shutdown by UTM because the maximum permitted number of users (MAX statement, CONN-USERS=) has been exceeded. This may also occur if an administrator user was transferred in the Set_Conversation_Security_User_ID call but the user ID implicitly assigned to the connection by UTM configuration or the (connection) user ID explicitly assigned using the statement LTERM..., USER= is not an administrator user (CONN-USERS applies only for users without administration authorization).

The program enters the “Reset” state.

CM_DEALLOCATED_NORMAL

A PEND-FI call was executed in the UTM service. The program enters the “Reset” state.

CM_OPERATION_INCOMPLETE

The Receive_Mapped_Data call was interrupted by the expiry of the timer that was set with Set_Receive_Timer. No data was received.

CM_UNSUCCESSFUL

The receive_type characteristic has the value CM_RECEIVE_IMMEDIATE and there is currently no data available for the conversation.

CM_RESOURCE_FAILURE_RETRY

A temporary resource bottleneck led to termination of the conversation. It may not be possible to buffer any further data in the UTM page pool.

Remedy: enlarge the UTM page pool (MAX statement, PGPOOL=).

CM_RESOURCE_FAILURE_NO_RETRY

An error occurred which led to premature termination of the conversation (e.g. protocol error or premature loss of network connection).

CM_PROGRAM_STATE_CHECK

The call is not permitted in the current state. The contents of all other variables are undefined.

CM_PROGRAM_PARAMETER_CHECK

The conversation_ID is invalid or the value in requested_length is greater than 32767 or less than 0. The contents of all other variables are undefined.

CM_PRODUCT_SPECIFIC_ERROR

A Receive call was issued instead of a Send_Data call (only directly after an Allocate call).

CM_MAP_ROUTINE_ERROR

In the UTM partner application no format identifiers are supported in the UPIC protocol.

Secondary return code ( secondary_return_code )

CM_SECURITY_USER_UNKNOWN

The specified user ID is not configured.

CM_SECURITY_STA_OFF

The specified user ID is locked.

CM_SECURITY_USER_IS_WORKING

Another user is already signed on with this user ID.

CM_SECURITY_OLD_PSWORD_WRONG

The old password entered is incorrect.

CM_SECURITY_NEW_PSWORD_WRONG

The new password information cannot be used. Possible cause: minimum period of validity not yet expired.

CM_SECURITY_NO_CARD_READER

The user is configured with a magnetic stripe card and cannot sign on via UPIC.

CM_SECURITY_CARD_INFO_WRONG

The user is configured with a chipcard and cannot sign on via UPIC.

CM_SECURITY_NO_RESOURCES

Sign-on is not possible at the moment. Possible cause:

• a resource bottleneck, or

• the maximum number of simultaneous users signed on has been reached (see KDCDEF statement MAX CONN-USERS=), or

• an inverse KDCDEF is running.

Try again later.

CM_SECURITY_NO_KERBEROS_SUPPORT

The user is configured with a Kerberos principal and cannot sign on via UPIC.

CM_SECURITY_TAC_KEY_MISSING

The current LTERM is not authorized to resume the service.

CM_SECURITY_PWD_EXPIRED_NO_RETRY

The validity period of the user password has expired.

CM_SECURITY_COMPLEXITY_ERROR

The new password is not sufficiently complex.

CM_SECURITY_PASSWORD_TOO_SHORT

The new password is too short.

CM_SECURITY_UPD_PSWORD_WRONG

The password transferred by KDCUPD does not satisfy the complexity or minimum length requirement defined in application configuration.

CM_SECURITY_TA_RECOVERY

A transaction restart is required for the specified user ID.

CM_SECURITY_PROTOCOL_CHANGED

The open service cannot be resumed from this LTERM partner.

CM_SECURITY_SHUT_WARN

The administrator has issued a SHUT WARN. Normal users may no longer sign on to the UTM application, only the administrator may still sign on.

CM_SECURITY_ENC_LEVEL_TOO_HIGH

The encryption mechanism required to resume the open service is not available on the connection.

CM_SECURITY_PWD_EXPIRED_RETRY

The validity period of the user password has expired.

The following secondary return codes only occur in the context of UTM cluster applications:

CM_SECURITY_USER_GLOBALLY_UNKNOWN

The specified user ID is not recognized in the cluster user file.

CM_SECURITY_USER_SIGNED_ON_OTHER_NODE

A user has already signed on to another node application with this user ID.

CM_SECURITY_TRANSIENT_ERROR

A temporary error occurred during signon. The cluster user file could not be accessed in the time configured in the node application.

Try signing on again later.

State change

• If the return code is CM_OK, the program has one of the following states after function call:

  “Receive”	if the value of status_received is CM_NO_STATUS_RECEIVED.
  “Send”	if the value of status_received is CM_SEND_RECEIVED.

• With the following return codes, the program enters the “Reset” state:
  CM_DEALLOCATED_ABEND
  CM_DEALLOCATED_NORMAL
  CM_SECURITY_NOT_VALID
  CM_TPN_NOT_RECOGNIZED
  CM_TP_NOT_AVAILABLE_RETRY/NO_RETRY
  CM_RESOURCE_FAILURE_RETRY/NO_RETRY

• In all other error conditions, the program does not change its state.

Notes

• With a Receive_Mapped_Data call, a program can only receive the amount of data specified in the requested_length parameter. It is therefore possible that the program has not read the complete message (segment) sent by the partner. The data_received parameter indicates as shown below whether there is still more message (segment) data to be read.

  • If the program has already received the complete message (segment), the data_received parameter has the value CM_COMPLETE_DATA_RECEIVED.

  • If the program has not yet received all data of the message (segment), the data_received parameter has the value CM_INCOMPLETE_DATA_RECEIVED. The program must then continue to call Receive_Mapped_Data or Receive until data_received has the value CM_COMPLETE_DATA_RECEIVED

• If a maximum wait time was set with the Set_Receive_Timer call before a blocking Receive_Mapped_Data call, the program run returns from the Receive_Mapped_Data call at the latest once the wait time has expired, and the Receive_Mapped_Data call then returns the result (return_code) CM_OPERATION_INCOMPLETE.

• A program can use a single call to receive both data and permission to send. The return_code, data_received, and status_received parameters supply details on the kind of information received by a program.

• If the program issues the Receive_Mapped_Data call in the “Send” state, permission to send is passed to the UTM service. The send direction of the conversation is thus changed.

• A Receive call with requested_length = 0 has no special meaning.
  If data is available, it is received in the length 0 with data_received = CM_INCOMPLETE_DATA_RECEIVED.
  If no data is available, permission to send can be received. This means that either data or permission to send can be received, but not both.

• If a message segment is received with Receive_Mapped_Data calls (data_received has the value CM_INCOMPLETE_DATA_RECEIVED except in the last Receive_Mapped_Data call), the map_name and map_name_length parameters are only supplied with values the first time Receive_Mapped_Data is called. However, they are not overwritten in the subsequent Receive_Mapped_Data calls.

• If the UTM partner application transfers an empty format identifier (i.e. 8 blanks), map_name is set to 8 blanks and map_name_length to -1.

Behavior in the event of errors

CM_RESOURCE_FAILURE_RETRY

Re-establish conversation. If the error recurs, the page pool of the UTM application may be too small and should be enlarged (MAX statement, PGPOOL=).

CM_RESOURCE_FAILURE_NO_RETRY

Notify the service department and produce a diagnostic report.
A fault in the transport system can also cause this return code.

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

Modify program.

CM_MAP_ROUTINE_ERROR

Modify program.

CM_OPERATION_INCOMPLETE

The conversation and the communication connection must be explicitly shut down with the Disable_UTM_UPIC call.
Any other call can lead to unpredictable results.

CM_SECURITY_USER_UNKNOWN

The UTM user ID is not configured. Use a user ID that is configured or create or dynamically configure the user ID you want.

CM_SECURITY_STA_OFF

Configure the user ID with STATUS=ON or unlock it using administration facilities.

CM_SECURITY_USER_IS_WORKING

Use another UTM user ID or terminate the service of the user already signed on.

CM_SECURITY_OLD_PSWORD_WRONG

Enter the password correctly.

CM_SECURITY_NEW_PSWORD_WRONG

Use the old password until its validity expires.

CM_SECURITY_NO_CARD_READER

The user is configured with a magnetic stripe card and cannot sign on via UPIC.

CM_SECURITY_CARD_INFO_WRONG

The user is configured with a chipcard.

CM_SECURITY_NO_RESOURCES

Try again later.

CM_SECURITY_NO_KERBEROS_SUPPORT

The user is configured with a Kerberos principal and cannot sign on via UPIC.

CM_SECURITY_TAC_KEY_MISSING

Configuration or modify program.

CM_SECURITY_PWD_EXPIRED_NO_RETRY

The validity period of the password has expired. The password must be changed using administration facilities before the user can sign on again.

CM_SECURITY_COMPLEXITY_ERROR

Select a new password that satisfies the requirements of the configured complexity level, see KDCDEF statement USER PROTECT-PW=.

CM_SECURITY_PASSWORD_TOO_SHORT

Select a longer password or change configuration, see KDCDEF statement USER PROTECT-PW= length, ... (value for the minimum length).

CM_SECURITY_UPD_PSWORD_WRONG

The password is not sufficiently complex or is too short, see KDCDEF statement USER PROTECT-PW=. The password must be changed using administration facilities before the user can sign on again.

CM_SECURITY_TA_RECOVERY

A transaction restart is required for the specified user ID.

CM_SECURITY_PROTOCOL_CHANGED

The user has an open service that cannot be resumed from a UPIC client.

CM_SECURITY_SHUT_WARN

The UTM application is terminated; only users with administration authorization may sign on. Wait until the application has been restarted.

CM_SECURITY_ENC_LEVEL_TOO_HIGH

The encryption mechanism required to resume the open service is not available on the connection.

CM_SECURITY_PWD_EXPIRED_RETRY

Repeat establishment of the conversation using the old password and a new password.

The following secondary return codes only occur in the context of UTM cluster applications:

CM_SECURITY_USER_GLOBALLY_UNKNOWN

The specified user ID is not recognized in the cluster user file.

CM_SECURITY_USER_SIGNED_ON_OTHER_NODE

A user has already signed on to another node application with this user ID.

CM_SECURITY_TRANSIENT_ERROR

A temporary error occurred during signon. The cluster user file could not be accessed in the time configured in the node application.

Try signing on again later.

Function declaration: Receive_Mapped_Data

CM_ENTRY Receive_Mapped_Data (unsigned char CM_PTR  conversation_ID,
            unsigned char                   CM_PTR  map_name,
            CM_INT32                        CM_PTR  map_name_length,
            unsigned char                   CM_PTR  buffer,
            CM_INT32                        CM_PTR  requested_length,
            CM_DATA_RECEIVED_TYPE           CM_PTR  data_received,
            CM_INT32                        CM_PTR  received_length,
            CM_STATUS_RECEIVED              CM_PTR  status_received,
            CM_CONTROL_INFORMATION_RECEIVED CM_PTR  request_to_send_received,
            CM_RETURN_CODE                  CM_PTR  return_code )