Receive - Receiving data from a UTM service

A program uses the Receive (CMRCV) call to receive information from a UTM service.

The program must repeat the Receive-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 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 call, the program run waits in the Receive until information is available for this conversation. Only then does the program run return from the Receive 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 call, appropriate timers should be set in the UTM partner application.

• The Receive 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 call, the program run does not wait until information for this conversation arrives. The program run returns from the Receive call immediately. If there is already information available, it is transferred to the program.

  UPIC local on Unix, Linux and Windows systems:Local connection via UPIC local does not support the non-blocking Receive call.

You can set the receive_type characteristic with the Set_Receive_Type call before the Receive call. After a conversation has been initialized, the blocking receive is set by default.

Syntax

CMRCV (conversation_ID, buffer, requested_length, data_received, received_length, status_received, control_information_received, return_code)

Parameters

--> conversation_ID	Identifier of the conversation.
<-- 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 the program has received data. If the result (return_code) is neither CM_OK nor CM_DEALLOCATED_NORMAL, the value of data_received is undefined. 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. Permission to send may have been 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 calls until the message (segment) is received in its entirety, i.e. until data_received has the value CM_COMPLETE_DATA_RECEIVED.
<-- 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

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.

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

• 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 - Receiving data 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:

• 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

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

• a service restart with KDCDISP was rejected as 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 state “Reset”.

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. If the error recurs, the page pool of the UTM application should be enlarged (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_OPERATION_INCOMPLETE

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

CM_UNSUCCESSFUL

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

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 transfered 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 sevice 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_TPN_NOT_AVAILABLE_RETRY/NO_RETRY
  CM_RESOURCE_FAILURE_RETRY/NO_RETRY
  CM_SECURITY_USER_UNKNOWN
  CM_SECURITY_STA_OFF
  CM_SECURITY_USER_IS_WORKING
  CM_SECURITY_OLD_PSWORD_WRONG
  CM_SECURITY_NEW_PSWORD_WRONG
  CM_SECURITY_NO_CARD_READER
  CM_SECURITY_CARD_INFO_WRONG
  CM_SECURITY_NO_RESOURCES
  CM_SECURITY_NO_KERBEROS_SUPPORT
  CM_SECURITY_TAC_KEY_MISSING
  CM_SECURITY_PWD_EXPIRED_NO_RETRY
  CM_SECURITY_COMPLEXITY_ERROR
  CM_SECURITY_PASSWORD_TOO_SHORT
  CM_SECURITY_UPD_PSWORD_WRONG
  CM_SECURITY_TA_RECOVERY
  CM_SECURITY_PROTOCOL_CHANGED
  CM_SECURITY_SHUT_WARN
  CM_SECURITY_ENC_LEVEL_TOO_HIGH
  CM_SECURITY_PWD_EXPIRED_RETRY
  CM_SECURITY_PWD_EXPIRED_RETRY
  CM_SECURITY_USER_GLOBALLY_UNKNOWN
  CM_SECURITY_USER_SIGNED_ON_OTHER_NODE
  CM_SECURITY_TRANSIENT_ERROR

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

Notes

• With a Receive call, a program can only receive the amount of data specified in the requested_length parameter. It is therefore possible that a message (segment) is only partially received with the Receive call. The data_received parameter indicates as shown below whether a complete message (segment) available for the program was received:

  • 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 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 call, the program run returns from the Receive call at the latest once the wait time has expired, and the Receive 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 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 and 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 the UTM partner application transfers a format identifier (structure information concerning the transferred file), this will be received by UPIC (no error occurs in the UTM service), but it cannot be passed on to the program. Data together with format IDs can only be read with Receive_Mapped_Data.

Behavior in the event of errors

CM_RESOURCE_FAILURE_RETRY

Re-establish conversation.

CM_RESOURCE_FAILURE_NO_RETRY

Notify the service department and produce 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_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 initiation of the conversation specifying the old password and the 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

CM_ENTRY Receive ( unsigned char                   CM_PTR  conversation_ID,
                   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  control_information_received,
                   CM_RETURN_CODE                  CM_PTR  return_code )