Receive (CPI-C)

La llamada Receive (nombre de función cmrcv) recibe los datos disponibles actualmente del programa asociado. Para Microsoft Windows, ejecute un subproceso en segundo plano para todas las comunicaciones CPI-C y conserve el subproceso en primer plano solo para la interfaz de usuario.

Sintaxis

  
CM_ENTRY Receive(   
unsigned char FAR *conversation_ID,    
unsigned char FAR *buffer,             
CM_INT32 FAR *requested_length,        
CM_INT32 FAR *data_received,           
CM_INT32 FAR *received_length,         
CM_INT32 FAR *status_received,         
CM_INT32 FAR *request_to_send_received,    
CM_INT32 FAR *return_code              
);  

Parámetros

conversation_ID
Parámetro proporcionado. Especifica el identificador de la conversación. El valor de este parámetro lo devolvió Initialize_Conversation o Accept_Conversation.

buffer
Parámetro devuelto. Especifica la dirección del búfer que va a contener los datos recibidos por el programa local.

El búfer contiene datos si se cumplen las condiciones siguientes:

• El parámetro data_received se establece en un valor distinto de CM_NO_DATA_RECEIVED.

• El parámetro return_code se establece en CM_OK o en CM_DEALLOCATED_NORMAL.

  requested_length
  Parámetro proporcionado. Indica el número máximo de bytes de datos que va a recibir el programa local. El intervalo va de 0 a 32767.

  data_received
  Parámetro devuelto. Indica si el programa recibió datos. Los valores posibles se enumeran siguiendo la sección Parámetros.

  received_length
  Parámetro devuelto. Indica el número de bytes de datos que recibió el programa local en esta llamada receive . Si return_code o data_received indica que el programa no recibió datos, este número no es relevante.

  status_received
  Parámetro devuelto. Indica los cambios en el estado de la conversación. A continuación se muestran los valores posibles. Estos códigos no son relevantes a menos que return_code esté establecido en CM_OK. Los valores posibles se enumeran siguiendo la sección Parámetros.

  request_to_send_received
  Parámetro devuelto. Especifica el indicador de solicitud a envío recibido. Los valores se enumeran siguiendo la sección Parámetros.

  return_code
  Código devuelto de esta llamada. Los valores se enumeran siguiendo la sección Parámetros.

Valores devueltos en el parámetro data_received

Estos códigos no son relevantes a menos que return_code esté establecido en CM_OK o CM_DEALLOCATED_NORMAL.

CM_DATA_RECEIVED
Se puede devolver para una conversación básica si la característica de relleno de conversaciones está establecida en CM_FILL_BUFFER, lo que indica que el programa recibe datos independientemente de su formato lógico. El programa local recibió datos hasta que se alcanzó requested_length o el final de los datos.

El final de los datos se indica mediante un cambio en otro estado de conversación, en función de los parámetros return_code, status_received y data_received , o bien una condición de error. Si el tipo de recepción de conversaciones se establece en CM_RECEIVE_IMMEDIATE, los datos recibidos pueden ser menores que requested_length si ha llegado una cantidad menor de datos del programa de asociados.

CM_COMPLETE_DATA_RECEIVED
En una conversación asignada, indica que el programa local ha recibido un registro de datos completo o la última parte de un registro de datos.

En una conversación básica con la característica de relleno establecida en CM_FILL_LL, este valor indica que el programa local ha recibido un registro lógico completo o el final de un registro lógico.

CM_INCOMPLETE_DATA_RECEIVED
En una conversación asignada, indica que el programa local ha recibido un registro de datos incompleto. El parámetro requested_length especificó un valor menor que la longitud del registro de datos (o menos que el resto del registro de datos si no es el primer objeto Receive para leer el registro). La cantidad de datos recibidos es igual al parámetro requested_length .

En una conversación básica con la característica de relleno establecida en CM_FILL_LL, este valor indica que el programa local ha recibido un registro lógico incompleto. La cantidad de datos recibidos es igual al parámetro requested_length . (Si los datos recibidos se truncaron, la longitud de los datos será menor que requested_length).

Al recibir este valor, el programa local normalmente vuelve a emitir Recibir para recibir la siguiente parte del registro.

CM_NO_DATA_RECEIVED
El programa no recibió datos.

Tenga en cuenta que si el parámetro return_code está establecido en CM_OK, la información de estado puede estar disponible a través del parámetro status_received .

Valores devueltos en el parámetro status_received

CM_NO_STATUS_RECEIVED
No se recibió ningún cambio de estado de conversación en esta llamada.

CM_SEND_RECEIVED
Indica, para el programa asociado, que la conversación ha entrado en estado RECEIVE. En el caso del programa local, la conversación está ahora en estado SEND si no se recibió ningún dato en esta llamada o SEND_PENDING estado si se recibieron datos en esta llamada.

Al recibir este valor, el programa local normalmente usa Send_Data para empezar a enviar datos.

CM_CONFIRM_DEALLOC_RECEIVED
Indica que el programa asociado emitió Deallocate con la confirmación solicitada. En el caso del programa local, la conversación está ahora en CONFIRM_DEALLOCATE estado.

Al recibir este valor, el programa local normalmente emite la llamada Confirmada .

CM_CONFIRM_RECEIVED
Indica que el programa asociado emitió la llamada Confirm . Para el programa local, la conversación está en estado CONFIRM.

Al recibir este valor, el programa local normalmente emite la llamada Confirmada .

CM_CONFIRM_SEND_RECEIVED
Indica, para el programa asociado, que la conversación ha entrado en el estado RECEIVE y el programa local ha recibido una solicitud de confirmación. En el caso del programa local, la conversación está ahora en CONFIRM_SEND estado.

Normalmente, el programa responde mediante la emisión de la llamada Confirmada . Tras la ejecución correcta de la llamada Confirmada , la conversación cambia al estado SEND para el programa local.

Valores devueltos en el parámetro request_to_send_received

CM_REQ_TO_SEND_RECEIVED
El programa asociado emitió la llamada Request_To_Send , que solicita al programa local que cambie la conversación al estado RECEIVE.

CM_REQ_TO_SEND_NOT_RECEIVED
El programa asociado no emitió la llamada Request_To_Send . Este valor no es relevante si el parámetro return_code está establecido en CM_PROGRAM_PARAMETER_CHECK o CM_PROGRAM_STATE_CHECK.

Valores devueltos en el parámetro return_code

CM_OK
Código de retorno principal; la llamada se ejecutó correctamente.

CM_OPERATION_NOT_ACCEPTED
Código de retorno principal; Una operación anterior en esta conversación está incompleta.

CM_OPERATION_INCOMPLETE
Código de retorno principal; la operación no se ha completado (el modo de procesamiento es solo de bloqueo) y todavía está en curso. El programa puede emitir Wait_For_Conversation para esperar la finalización de la operación, o Cancel_Conversation para cancelar la operación y la conversación. Si se ha llamado a Specify_Windows_Handle , la aplicación debe esperar la notificación por un mensaje de Windows® y no llamar a Wait_For_Conversation.

CM_UNSUCCESSFUL
Código de retorno principal; el tipo de recepción se establece en CM_RECEIVE_IMMEDIATE y no hay datos disponibles inmediatamente en el programa asociado.

CM_DEALLOCATED_NORMAL
Código de retorno principal; la conversación se ha desasignado normalmente. El programa asociado emitido Desasignar con el tipo de desasignación de conversaciones establecido en CM_DEALLOCATE_FLUSH o CM_DEALLOCATE_SYNC_LEVEL con el nivel de sincronización de la conversación especificada como CM_NONE.

CM_PROGRAM_PARAMETER_CHECK
Código de retorno principal; se produjo una de las siguientes acciones:

• El valor especificado por conversation_ID no es válido.

• El valor especificado por requested_length está fuera del intervalo (mayor que 32767).

  Si el programa recibe este código de retorno, los demás parámetros devueltos no son válidos.

  CM_PROGRAM_STATE_CHECK
  Código de retorno principal; se produjo una de las siguientes acciones:

• El tipo de recepción se establece en CM_RECEIVE_AND_WAIT y el estado de la conversación no es RECEIVE, SEND o SEND_PENDING.

• El tipo de recepción se establece en CM_RECEIVE_IMMEDIATE y el estado de la conversación no es RECEIVE.

• En una conversación básica, la conversación está en estado SEND, el tipo de recepción se establece en CM_RECEIVE_AND_WAIT y el programa no terminó de enviar un registro lógico.

  Si el programa recibe este código de retorno, los demás parámetros devueltos no son válidos.

  CM_PRODUCT_SPECIFIC_ERROR
  Código de retorno principal; se produjo un error específico del producto y se ha registrado en el registro de errores de productos.

  CM_CONVERSATION_TYPE_MISMATCH
  Código de retorno principal; la unidad lógica de asociado (LU) o el programa no admiten el tipo de conversación (básico o asignado) especificado en la solicitud de asignación.

  CM_PIP_NOT_SPECIFIED_CORRECTLY
  Código de retorno principal; la solicitud de asignación fue rechazada por un programa de transacciones (TP) que no es CPI-C LU 6.2. El programa de partners requiere una o varias variables de datos PIP, que no son compatibles con CPI-C.

  CM_SECURITY_NOT_VALID
  Código de retorno principal; el identificador de usuario o la contraseña especificados en la solicitud de asignación no fue aceptado por la LU del asociado.

  CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
  Código de retorno principal; el programa asociado no admite el nivel de sincronización especificado en la solicitud de asignación.

  CM_TPN_NOT_RECOGNIZED
  Código de retorno principal; la LU del asociado no reconoce el nombre del programa especificado en la solicitud de asignación.

  CM_TP_NOT_AVAILABLE_NO_RETRY
  Código de retorno principal; la LU del asociado no puede iniciar el programa especificado en la solicitud de asignación debido a una condición permanente. El motivo del error se puede registrar en el nodo remoto. No vuelva a intentar la asignación hasta que se haya corregido el error.

  CM_TP_NOT_AVAILABLE_RETRY
  Código de retorno principal; la LU del asociado no puede iniciar el programa especificado en la solicitud de asignación debido a una condición temporal. El motivo del error se puede registrar en el nodo remoto. Vuelva a intentar la asignación.

  CM_PROGRAM_ERROR_NO_TRUNC
  Código de retorno principal; mientras que en estado SEND o en SEND_PENDING estado con la dirección de error establecida en CM_SEND_ERROR, el programa asociado emitió Send_Error. Los datos no se han truncado.

  CM_PROGRAM_ERROR_PURGING
  Código de retorno principal; se produjo una de las siguientes acciones:

• Mientras está en estado RECEIVE o CONFIRM, el programa asociado emitió Send_Error. Los datos enviados pero aún no recibidos se purgan.

• Mientras está en SEND_PENDING estado con la dirección de error establecida en CM_RECEIVE_ERROR, el programa asociado emitió Send_Error. Los datos no se purgaron.

  CM_RESOURCE_FAILURE_NO_RETRY
  Código de retorno principal; se produjo una de las siguientes acciones:

• La conversación se terminó prematuramente debido a una condición permanente. No vuelva a intentarlo hasta que se corrija el error.

• El programa asociado no desasignó la conversación antes de terminar con normalidad.

  CM_RESOURCE_FAILURE_RETRY
  Código de retorno principal; la conversación se finalizó prematuramente debido a una condición temporal, como el error del módem. Vuelva a intentar la conversación.

  CM_DEALLOCATED_ABEND
  Código de retorno principal; la conversación se ha desasignado por uno de los siguientes motivos:

• El programa remoto emitió Deallocate con el conjunto de parámetros de tipo en CM_DEALLOCATE_ABEND, o la LU remota lo hizo debido a una condición de finalización anómala del programa remoto. Si la conversación del programa remoto estaba en estado RECEIVE cuando se emitió la llamada, se purga la información enviada por el programa local y aún no recibida por el programa remoto.

• El TP remoto finalizó normalmente, pero no desasignó la conversación antes de finalizar. Los servicios de nodo en la LU remota desasignaron la conversación en nombre del TP remoto.

  CM_DEALLOCATED_ABEND_SVC
  Código de retorno principal; la conversación se ha desasignado por uno de los siguientes motivos:

• El programa asociado emitió Deallocate con el parámetro type establecido en ABEND_SVC.

• El programa asociado no desasignó la conversación antes de finalizar.

  Si la conversación está en estado RECEIVE para el programa asociado cuando el programa local emite esta llamada, se purgan los datos enviados por el programa local y aún no recibidos por el programa asociado.

  CM_DEALLOCATED_ABEND_TIMER
  Código de retorno principal; la conversación se ha desasignado porque el programa asociado emitió Deallocate con el parámetro de tipo establecido en ABEND_TIMER. Si la conversación está en estado RECEIVE para el programa asociado cuando el programa local emite esta llamada, se purgan los datos enviados por el programa local y aún no recibidos por el programa asociado.

  CM_SVC_ERROR_PURGING
  Código de retorno principal; mientras que en estado SEND, el programa de asociado o lu del asociado emitió Send_Error con el parámetro de tipo establecido en SVC. Es posible que se hayan purgado los datos enviados al programa asociado.

  CM_SVC_ERROR_NO_TRUNC
  Código de retorno principal; mientras que en estado SEND, el programa de asociado o lu del asociado emitió Send_Error con el parámetro de tipo establecido en SVC. Es posible que se hayan purgado los datos enviados al programa asociado.

  CM_PROGRAM_ERROR_TRUNC
  Código de retorno principal; en estado SEND, antes de finalizar el envío de un registro lógico completo, el programa asociado emitió Send_Error. Es posible que el programa local haya recibido la primera parte del registro lógico a través de una llamada de recepción .

  CM_SVC_ERROR_TRUNC
  Código de retorno principal; mientras que en el estado RECEIVE o CONFIRM, el programa asociado o lu de asociado emitió Send_Error con el parámetro type establecido en SVC antes de que termine de enviar un registro lógico completo. Es posible que el programa local haya recibido la primera parte del registro lógico.

  Cambios de estado

  La conversación puede estar en estado RECEIVE, SEND o SEND_PENDING.

  Si receive_type se establece en CM_RECEIVE_IMMEDIATE, la conversación debe estar en estado RECEIVE.

  La emisión de recepción mientras la conversación está en estado SEND o SEND_PENDING hace que la LU local envíe la información en su búfer de envío y un indicador de envío al programa asociado. En función de data_received y status_received la conversación puede cambiar al estado RECEIVE del programa local.

  El nuevo estado de conversación viene determinado por:

• Estado en el que se encuentra la conversación cuando el programa emite la llamada.

• Parámetro return_code .

• Parámetros data_received y status_received.

  Si no hay datos disponibles actualmente y el tipo de recepción (establecido por Set_Receive_Type) se establece en CM_RECEIVE_AND_WAIT, el programa local espera a que lleguen los datos. Si el tipo de recepción se establece en CM_RECEIVE_IMMEDIATE, el programa local no espera.

  El proceso para recibir datos es el siguiente:

• El programa local emite una llamada Receive hasta que termine de recibir una unidad completa de datos. Es posible que el programa local tenga que emitir Receive varias veces para recibir una unidad completa de datos. El parámetro data_received indica si finaliza la recepción de datos.

  Los datos recibidos pueden ser:

  • Un registro de datos transmitido en una conversación asignada.

  • Un registro lógico transmitido en una conversación básica con las conversaciones rellenan la característica establecida en CM_FILL_LL.

  • Búfer de datos recibidos independientemente de su formato de registro lógico en una conversación básica con la característica de relleno establecida en CM_FILL_BUFFER.

    Cuando se ha recibido una unidad completa de datos, el programa local puede manipularlo.

• El programa local determina la siguiente acción que se realizará en función de la información de control recibida a través de status_received. Es posible que el programa local tenga que volver a emitir Receive para recibir la información de control.

  El tipo de conversación se establece mediante Set_Conversation_Type. La característica de relleno se establece mediante Set_Fill.

  En la tabla siguiente se resumen los cambios de estado que pueden producirse cuando se emite Receive con la conversación en estado RECEIVE y return_code es CM_OK.

data_received	status_received	Nuevo estado
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	Sin cambios
CM_COMPLETE_DATA_ RECIBIDO	CM_NO_STATUS_RECEIVED	Sin cambios
CM_INCOMPLETE_DATA_ RECIBIDO	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	ENVIAR

Si return_code se establece en CM_UNSUCCESSFUL, lo que significa que el receive_type se establece en CM_RECEIVE_IMMEDIATE y no hay datos disponibles, no hay ningún cambio de estado.

En la tabla siguiente se resumen los cambios de estado que pueden producirse cuando Receive se emite con la conversación en estado SEND y return_code es CM_OK.

data_received	status_received	Nuevo estado
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ RECIBIDO	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ RECIBIDO	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	Sin cambios

En la tabla siguiente se resumen los cambios de estado que pueden producirse cuando se emite Receive con la conversación en estado SEND_PENDING y return_code se CM_OK.

data_received	status_received	Nuevo estado
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ RECIBIDO	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ RECIBIDO	CM_SEND_RECEIVED	Sin cambios
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	ENVIAR

En los temas siguientes se resumen los cambios de estado que pueden producirse cuando receive se emite en cualquier estado permitido.

En esta sección

• Confirmación

• Desasignación normal

• ABEND

• Errores