Receive (CPI-C)

Article
07/21/2023

L’appel de réception (nom de fonction cmrcv) reçoit toutes les données actuellement disponibles à partir du programme partenaire. Pour Microsoft Windows, exécutez un thread d’arrière-plan pour toutes les communications CPI-C et conservez le thread de premier plan uniquement pour l’interface utilisateur.

Syntaxe

  
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              
);

Paramètres

conversation_ID
Paramètre fourni. Spécifie l’identificateur de la conversation. La valeur de ce paramètre a été retournée par Initialize_Conversation ou Accept_Conversation.

buffer
Paramètre retourné. Spécifie l’adresse de la mémoire tampon à contenir les données reçues par le programme local.

La mémoire tampon contient des données si les conditions suivantes sont remplies :

Le paramètre data_received a une valeur autre que CM_NO_DATA_RECEIVED.
Le paramètre return_code est défini sur CM_OK ou sur CM_DEALLOCATED_NORMAL.

requested_length
Paramètre fourni. Indique le nombre maximal d’octets de données que le programme local doit recevoir. La plage est comprise entre 0 et 32767.

data_received
Paramètre retourné. Indique si le programme a reçu des données. Les valeurs possibles sont répertoriées à la suite de la section Paramètres.

received_length
Paramètre retourné. Indique le nombre d’octets de données que le programme local a reçus lors de cet appel de réception . Si return_code ou data_received indique que le programme n’a reçu aucune donnée, ce nombre n’est pas pertinent.

status_received
Paramètre retourné. Indique les modifications apportées au status de la conversation. Voici les valeurs possibles. Ces codes ne sont pas pertinents, sauf si return_code est défini sur CM_OK. Les valeurs possibles sont répertoriées à la suite de la section Paramètres.

request_to_send_received
Paramètre retourné. Spécifie l’indicateur request-to-send-received. Les valeurs sont répertoriées à la suite de la section Paramètres.

return_code
Code retourné par cet appel. Les valeurs sont répertoriées à la suite de la section Paramètres.

Valeurs retournées dans le paramètre data_received

Ces codes ne sont pas pertinents, sauf si return_code est défini sur CM_OK ou CM_DEALLOCATED_NORMAL.

CM_DATA_RECEIVED
Peut être retourné pour une conversation de base si la caractéristique de remplissage des conversations est définie sur CM_FILL_BUFFER, ce qui indique que le programme reçoit des données indépendamment de son format logique. Le programme local a reçu des données jusqu’à ce que requested_length ou la fin des données soit atteinte.

La fin des données est indiquée par un changement d’état de conversation, basé sur les paramètres return_code, status_received et data_received , ou par une condition d’erreur. Si le type de réception des conversations est défini sur CM_RECEIVE_IMMEDIATE, les données reçues peuvent être inférieures à requested_length si une plus petite quantité de données est arrivée du programme partenaire.

CM_COMPLETE_DATA_RECEIVED
Dans une conversation mappée, indique que le programme local a reçu un enregistrement de données complet ou la dernière partie d’un enregistrement de données.

Dans une conversation de base avec la caractéristique de remplissage définie sur CM_FILL_LL, cette valeur indique que le programme local a reçu un enregistrement logique complet ou la fin d’un enregistrement logique.

CM_INCOMPLETE_DATA_RECEIVED
Dans une conversation mappée, indique que le programme local a reçu un enregistrement de données incomplet. Le paramètre requested_length a spécifié une valeur inférieure à la longueur de l’enregistrement de données (ou inférieure au reste de l’enregistrement de données s’il ne s’agit pas de la première réception à lire l’enregistrement). La quantité de données reçues est égale au paramètre requested_length .

Dans une conversation de base avec la caractéristique de remplissage définie sur CM_FILL_LL, cette valeur indique que le programme local a reçu un enregistrement logique incomplet. La quantité de données reçues est égale au paramètre requested_length . (Si les données reçues ont été tronquées, la longueur des données sera inférieure à requested_length.)

Lors de la réception de cette valeur, le programme local réédite normalement Receive pour recevoir la partie suivante de l’enregistrement.

CM_NO_DATA_RECEIVED
Le programme n’a pas reçu de données.

Notez que si le paramètre return_code est défini sur CM_OK, status informations peuvent être disponibles via le paramètre status_received.

Valeurs retournées dans le paramètre status_received

CM_NO_STATUS_RECEIVED
Aucune conversation status modification n’a été reçue lors de cet appel.

CM_SEND_RECEIVED
Indique, pour le programme partenaire, que la conversation est entrée dans l’état RECEIVE. Pour le programme local, la conversation est désormais à l’état SEND si aucune donnée n’a été reçue lors de cet appel, ou SEND_PENDING’état si des données ont été reçues lors de cet appel.

Lors de la réception de cette valeur, le programme local utilise normalement Send_Data pour commencer à envoyer des données.

CM_CONFIRM_DEALLOC_RECEIVED
Indique que le programme partenaire a émis deallocate avec confirmation demandée. Pour le programme local, la conversation est maintenant dans CONFIRM_DEALLOCATE état.

Lors de la réception de cette valeur, le programme local émet normalement l’appel Confirmé .

CM_CONFIRM_RECEIVED
Indique que le programme partenaire a émis l’appel Confirmer . Pour le programme local, la conversation est à l’état CONFIRM.

Lors de la réception de cette valeur, le programme local émet normalement l’appel Confirmé .

CM_CONFIRM_SEND_RECEIVED
Indique, pour le programme partenaire, que la conversation est entrée dans l’état RECEIVE et qu’une demande de confirmation a été reçue par le programme local. Pour le programme local, la conversation est maintenant dans CONFIRM_SEND état.

Le programme répond normalement en émettant l’appel Confirmé . En cas d’exécution réussie de l’appel Confirmé , la conversation passe à l’état SEND pour le programme local.

Valeurs retournées dans le paramètre request_to_send_received

CM_REQ_TO_SEND_RECEIVED
Le programme partenaire a émis l’appel Request_To_Send , qui demande au programme local de modifier la conversation à l’état RECEIVE.

CM_REQ_TO_SEND_NOT_RECEIVED
Le programme partenaire n’a pas lancé l’appel Request_To_Send . Cette valeur n’est pas pertinente si le paramètre return_code est défini sur CM_PROGRAM_PARAMETER_CHECK ou CM_PROGRAM_STATE_CHECK.

Valeurs retournées dans le paramètre return_code

CM_OK
Code de retour principal ; l’appel a été exécuté avec succès.

CM_OPERATION_NOT_ACCEPTED
Code de retour principal ; une opération précédente sur cette conversation est incomplète.

CM_OPERATION_INCOMPLETE
Code de retour principal ; l’opération n’est pas terminée (le mode de traitement n’est pas bloquant uniquement) et est toujours en cours. Le programme peut émettre des Wait_For_Conversation pour attendre la fin de l’opération, ou Cancel_Conversation pour annuler l’opération et la conversation. Si Specify_Windows_Handle a été appelé, l’application doit attendre la notification d’un message Windows® et ne pas appeler Wait_For_Conversation.

CM_UNSUCCESSFUL
Code de retour principal ; le type de réception est défini sur CM_RECEIVE_IMMEDIATE et aucune donnée n’est immédiatement disponible à partir du programme partenaire.

CM_DEALLOCATED_NORMAL
Code de retour principal ; la conversation a été libérée normalement. Le programme partenaire a émis La fonctionnalité Désallouer les conversations avec le type de libération des conversations défini sur CM_DEALLOCATE_FLUSH ou CM_DEALLOCATE_SYNC_LEVEL avec le niveau de synchronisation de la conversation spécifié comme CM_NONE.

CM_PROGRAM_PARAMETER_CHECK
Code de retour principal ; l’un des événements suivants s’est produit :

La valeur spécifiée par conversation_ID n’est pas valide.
La valeur spécifiée par requested_length est hors plage (supérieure à 32767).

Si le programme reçoit ce code de retour, les autres paramètres retournés ne sont pas valides.

CM_PROGRAM_STATE_CHECK
Code de retour principal ; l’un des événements suivants s’est produit :
Le type de réception est défini sur CM_RECEIVE_AND_WAIT et l’état de la conversation n’est pas RECEIVE, SEND ou SEND_PENDING.
Le type de réception est défini sur CM_RECEIVE_IMMEDIATE et l’état de la conversation n’est pas RECEIVE.
Dans une conversation de base, la conversation est à l’état SEND, le type de réception est défini sur CM_RECEIVE_AND_WAIT et le programme n’a pas terminé l’envoi d’un enregistrement logique.

Si le programme reçoit ce code de retour, les autres paramètres retournés ne sont pas valides.

CM_PRODUCT_SPECIFIC_ERROR
Code de retour principal ; une erreur spécifique au produit s’est produite et a été enregistrée dans le journal des erreurs des produits.

CM_CONVERSATION_TYPE_MISMATCH
Code de retour principal ; l’unité logique partenaire (LU) ou le programme ne prend pas en charge le type de conversation (de base ou mappé) spécifié dans la demande d’allocation.

CM_PIP_NOT_SPECIFIED_CORRECTLY
Code de retour principal ; la demande d’allocation a été rejetée par un programme de transaction (TP) non CPI-C LU 6.2. Le programme partenaire nécessite une ou plusieurs variables de données PIP, qui ne sont pas prises en charge par CPI-C.

CM_SECURITY_NOT_VALID
Code de retour principal ; l’identificateur utilisateur ou le mot de passe spécifié dans la demande d’allocation n’a pas été accepté par l’unité lu partenaire.

CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
Code de retour principal ; le programme partenaire ne prend pas en charge le niveau de synchronisation spécifié dans la demande d’allocation.

CM_TPN_NOT_RECOGNIZED
Code de retour principal ; l’unité lu partenaire ne reconnaît pas le nom du programme spécifié dans la demande d’allocation.

CM_TP_NOT_AVAILABLE_NO_RETRY
Code de retour principal ; l’unité lu partenaire ne peut pas démarrer le programme spécifié dans la demande d’allocation en raison d’une condition permanente. La raison de l’erreur peut être consignée sur le nœud distant. Ne réessayez pas l’allocation tant que l’erreur n’a pas été corrigée.

CM_TP_NOT_AVAILABLE_RETRY
Code de retour principal ; l’unité lu partenaire ne peut pas démarrer le programme spécifié dans la demande d’allocation en raison d’une condition temporaire. La raison de l’erreur peut être consignée sur le nœud distant. Réessayez l’allocation.

CM_PROGRAM_ERROR_NO_TRUNC
Code de retour principal ; à l’état SEND ou à l’état SEND_PENDING avec le sens d’erreur défini sur CM_SEND_ERROR, le programme partenaire a émis Send_Error. Les données n’ont pas été tronquées.

CM_PROGRAM_ERROR_PURGING
Code de retour principal ; l’un des événements suivants s’est produit :
Dans l’état RECEIVE ou CONFIRM, le programme partenaire a émis Send_Error. Les données envoyées mais pas encore reçues sont purgées.
Dans SEND_PENDING état avec le sens de l’erreur défini sur CM_RECEIVE_ERROR, le programme partenaire a émis Send_Error. Les données n’ont pas été purgées.

CM_RESOURCE_FAILURE_NO_RETRY
Code de retour principal ; l’un des événements suivants s’est produit :
La conversation a été interrompue prématurément en raison d’une condition permanente. Ne réessayez pas tant que l’erreur n’a pas été corrigée.
Le programme partenaire n’a pas libéré la conversation avant de se terminer normalement.

CM_RESOURCE_FAILURE_RETRY
Code de retour principal ; la conversation a été interrompue prématurément en raison d’une condition temporaire, telle qu’une défaillance du modem. Réessayez la conversation.

CM_DEALLOCATED_ABEND
Code de retour principal ; la conversation a été libérée pour l’une des raisons suivantes :
Le programme distant a émis La libération avec l’ensemble de paramètres de type à CM_DEALLOCATE_ABEND, ou l’unité lu distante l’a fait en raison d’une condition de fin anormale du programme distant. Si la conversation pour le programme distant était à l’état RECEIVE lors de l’émission de l’appel, les informations envoyées par le programme local et non encore reçues par le programme distant sont purgées.
Le TP distant s’est terminé normalement, mais n’a pas libéré la conversation avant de se terminer. Les services de nœud au niveau de l’unité lu distante ont libéré la conversation au nom du TP distant.

CM_DEALLOCATED_ABEND_SVC
Code de retour principal ; la conversation a été libérée pour l’une des raisons suivantes :
Le programme partenaire a émis La libération avec le paramètre de type défini sur ABEND_SVC.
Le programme partenaire n’a pas libéré la conversation avant de se terminer.

Si la conversation est à l’état RECEIVE pour le programme partenaire lorsque cet appel est émis par le programme local, les données envoyées par le programme local et non encore reçues par le programme partenaire sont purgées.

CM_DEALLOCATED_ABEND_TIMER
Code de retour principal ; la conversation a été libérée, car le programme partenaire a émis Deallocate avec le paramètre de type défini sur ABEND_TIMER. Si la conversation est à l’état RECEIVE pour le programme partenaire lorsque cet appel est émis par le programme local, les données envoyées par le programme local et non encore reçues par le programme partenaire sont purgées.

CM_SVC_ERROR_PURGING
Code de retour principal ; dans l’état SEND, le programme partenaire ou l’unité lu partenaire a émis Send_Error avec le paramètre de type défini sur SVC. Les données envoyées au programme partenaire peuvent avoir été purgées.

CM_SVC_ERROR_NO_TRUNC
Code de retour principal ; dans l’état SEND, le programme partenaire ou l’unité lu partenaire a émis Send_Error avec le paramètre de type défini sur SVC. Les données envoyées au programme partenaire peuvent avoir été purgées.

CM_PROGRAM_ERROR_TRUNC
Code de retour principal ; dans l’état SEND, avant de terminer l’envoi d’un enregistrement logique complet, le programme partenaire a émis Send_Error. Le programme local peut avoir reçu la première partie de l’enregistrement logique par le biais d’un appel de réception .

CM_SVC_ERROR_TRUNC
Code de retour principal ; dans l’état RECEIVE ou CONFIRM, le programme partenaire ou l’unité lu partenaire a émis Send_Error avec le paramètre de type défini sur SVC avant de terminer l’envoi d’un enregistrement logique complet. Le programme local a peut-être reçu la première partie de l’enregistrement logique.

Changements d’état

La conversation peut être à l’état RECEIVE, SEND ou SEND_PENDING.

Si receive_type est défini sur CM_RECEIVE_IMMEDIATE, la conversation doit être à l’état RECEIVE.

L’émission de la réception lorsque la conversation est à l’état SEND ou SEND_PENDING entraîne l’envoi des informations dans sa mémoire tampon d’envoi et un indicateur d’envoi au programme partenaire. En fonction de data_received et status_received la conversation peut passer à l’état RECEIVE pour le programme local.

Le nouvel état de la conversation est déterminé par :
État dans lequel se trouve la conversation lorsque le programme émet l’appel.
Paramètre return_code .
Paramètres data_received et status_received.

Si aucune donnée n’est actuellement disponible et que le type de réception (défini par Set_Receive_Type) est défini sur CM_RECEIVE_AND_WAIT, le programme local attend que les données arrivent. Si le type de réception est défini sur CM_RECEIVE_IMMEDIATE, le programme local n’attend pas.

Le processus de réception des données est le suivant :
Le programme local émet un appel de réception jusqu’à ce qu’il termine la réception d’une unité complète de données. Le programme local peut avoir besoin d’émettre la réception plusieurs fois pour recevoir une unité complète de données. Le paramètre data_received indique si la réception des données est terminée.

Les données reçues peuvent être les suivantes :
- Un enregistrement de données transmis dans une conversation mappée.
- Un enregistrement logique transmis dans une conversation de base avec les caractéristiques de remplissage des conversations définies sur CM_FILL_LL.
- Mémoire tampon de données reçues indépendamment de son format d’enregistrement logique dans une conversation de base avec la caractéristique de remplissage définie sur CM_FILL_BUFFER.
  
  Lorsqu’une unité complète de données a été reçue, le programme local peut les manipuler.
Le programme local détermine l’action suivante à entreprendre en fonction des informations de contrôle reçues via status_received. Le programme local devra peut-être rééditer Receive pour recevoir les informations de contrôle.

Le type de conversation est défini par Set_Conversation_Type. La caractéristique de remplissage est définie par Set_Fill.

Le tableau suivant récapitule les changements d’état qui peuvent se produire lorsque Réception est émis avec la conversation à l’état RECEIVE et que return_code est CM_OK.

data_received	status_received	Nouvel état
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	Aucun changement
CM_COMPLETE_DATA_ REÇU	CM_NO_STATUS_RECEIVED	Aucun changement
CM_INCOMPLETE_DATA_ REÇU	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

Si return_code est défini sur CM_UNSUCCESSFUL, ce qui signifie que le receive_type est défini sur CM_RECEIVE_IMMEDIATE et qu’aucune donnée n’est disponible, il n’y a aucun changement d’état.

Le tableau suivant récapitule les changements d’état qui peuvent se produire lorsque Réception est émis avec la conversation à l’état SEND et return_code est CM_OK.

data_received	status_received	Nouvel état
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ REÇU	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ REÇU	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	Aucun changement

Le tableau suivant récapitule les changements d’état qui peuvent se produire lorsque la réception est émise avec la conversation dans SEND_PENDING état et que return_code est CM_OK.

data_received	status_received	Nouvel état
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
CM_COMPLETE_DATA_ REÇU	CM_NO_STATUS_RECEIVED	RECEIVE
CM_INCOMPLETE_DATA_ REÇU	CM_SEND_RECEIVED	Aucun changement
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

Les rubriques suivantes récapitulent les changements d’état qui peuvent se produire lorsque la réception est émise dans n’importe quel état autorisé.