Receive (CPI-C)

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 pour l’interface utilisateur uniquement.

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 devant contenir les données reçues par le programme local.

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

  • Le paramètre data_received est défini sur 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 Parameters.

    received_length
    Paramètre retourné. Indique le nombre d’octets de données reçus par le programme local 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 de l’état de la conversation. Les valeurs possibles sont les suivantes. 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 Parameters.

    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 Parameters.

    return_code
    Code retourné à partir de cet appel. Les valeurs sont répertoriées à la suite de la section Parameters.

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épendantes de son format logique. Le programme local a reçu des données jusqu’à ce que requested_length ou la fin des données soient atteintes.

La fin des données est indiquée par une modification apportée à un autre État de conversation, en fonction des paramètres return_code, status_receivedet data_received , ou d’une condition d’erreur. Si le type de réception conversations a la valeur CM_RECEIVE_IMMEDIATE, les données reçues peuvent être inférieures à requested_length si une quantité plus faible 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 pour 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 Fill 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.)

Une fois cette valeur reçue, le programme local réémet 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, les informations d’État peuvent être disponibles par le biais du paramètre status_received .

Valeurs retournées dans le paramètre status_received

CM_NO_STATUS_RECEIVED
Aucune modification de l’état de la conversation n’a été reçue sur cet appel.

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

Une fois cette valeur reçue, le programme local utilise normalement send_data pour commencer à envoyer des données.

CM_CONFIRM_DEALLOC_RECEIVED
Indique que le programme partenaire a émis une désallocation avec la confirmation demandée. Pour le programme local, la conversation est maintenant en état CONFIRM_DEALLOCATE.

Une fois cette valeur reçue, le programme local émet normalement l’appel confirmé .

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

Une fois cette valeur reçue, 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 de réception et qu’une demande de confirmation a été reçue par le programme local. Pour le programme local, la conversation est maintenant en état CONFIRM_SEND.

Normalement, le programme répond en émettant l’appel confirmé . En cas de réussite de l’exécution de l’appel confirmé , la conversation passe à l’état d’envoi 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 l’état de la conversation en réception.

CM_REQ_TO_SEND_NOT_RECEIVED
Le programme partenaire n’a pas émis l’appel de Request_To_Send . Cette valeur n’est pas pertinente si le paramètre return_code a la valeur 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 est non bloquant uniquement) et est toujours en cours. Le programme peut émettre 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ée, l’application doit attendre une notification par un Windows® message 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 dans le programme partenaire.

CM_DEALLOCATED_NORMAL
Code de retour principal ; la conversation a été désallouée normalement. Le programme partenaire a émis une désallocation avec le type de désallocation 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 éléments 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 limites (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 éléments 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 d’envoi, le type de réception est défini sur CM_RECEIVE_AND_WAIT, et le programme n’a pas fini d’envoyer 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é consignée dans le journal des erreurs des produits.

    CM_CONVERSATION_TYPE_MISMATCH
    Code de retour principal ; l’unité logique de 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 LU 6,2 non-CPI-C. Le programme partenaire requiert 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 d’utilisateur ou le mot de passe spécifié dans la demande d’allocation n’a pas été accepté par l’unité logique du 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 ; le 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 ; le 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 ; le 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 ; dans l’état d’envoi ou dans l’État SEND_PENDING avec la direction d’erreur définie 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 éléments 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 la direction d’erreur définie 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 éléments suivants s’est produit :

  • La conversation a été interrompue prématurément en raison d’une condition permanente. N’effectuez pas de nouvelle tentative tant que l’erreur n’a pas été corrigée.

  • Le programme partenaire n’a pas désalloué 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 que la défaillance d’un modem. Réessayez la conversation.

    CM_DEALLOCATED_ABEND
    Code de retour principal ; la conversation a été désallouée pour l’une des raisons suivantes :

  • Le programme distant a émis la désallocation avec le type parameterset à CM_DEALLOCATE_ABEND, ou le lu distant l’a fait en raison d’une condition de fin anormale du programme distant. Si la conversation pour le programme distant était en état de réception lors de l’émission de l’appel, les informations envoyées par le programme local et qui n’ont pas encore été reçues par le programme distant sont purgées.

  • Le TP distant s’est arrêté normalement mais n’a pas désalloué la conversation avant de se terminer. Les services de nœud au niveau de l’unité logique distante désalloué la conversation pour le compte du TP distant.

    CM_DEALLOCATED_ABEND_SVC
    Code de retour principal ; la conversation a été désallouée pour l’une des raisons suivantes :

  • Le programme partenaire a émis la désallocation avec le paramètre de type défini sur ABEND_SVC.

  • Le programme partenaire n’a pas désalloué la conversation avant de se terminer.

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

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

    CM_SVC_ERROR_PURGING
    Code de retour principal ; dans l’état d’envoi, le programme partenaire ou le LU partenaire a émis Send_Error avec le paramètre de type défini sur SVC. Les données envoyées au programme partenaire ont peut-être été purgées.

    CM_SVC_ERROR_NO_TRUNC
    Code de retour principal ; dans l’état d’envoi, le programme partenaire ou le LU partenaire a émis Send_Error avec le paramètre de type défini sur SVC. Les données envoyées au programme partenaire ont peut-être été purgées.

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

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

    Modifications d’État

    La conversation peut être dans 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 d’une réception alors que la conversation est à l’état d’envoi ou de SEND_PENDING entraîne l’envoi par l’unité logique locale des informations de sa mémoire tampon d’envoi et d’un indicateur d’envoi au programme partenaire. Selon data_received et status_received la conversation peut changer pour recevoir l’état du programme local.

    Le nouvel état de conversation est déterminé par :

  • État dans lequel la conversation se trouve 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 ait terminé de recevoir une unité de données complète. Le programme local devra peut-être émettre plusieurs fois des réceptions pour recevoir une unité de données complète. Le paramètre data_received indique si la réception des données est terminée.

    Les données reçues peuvent être :

    • Un enregistrement de données transmis dans une conversation mappée.

    • Un enregistrement logique transmis dans une conversation de base avec la caractéristique remplir les conversations a la valeur CM_FILL_LL.

    • Mémoire tampon de données reçue 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é de données complète a été reçue, le programme local peut la 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éémettre la réception 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 modifications d’État qui peuvent se produire lorsque la réception est émise avec la conversation dans l’état de réception 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 a la valeur CM_UNSUCCESSFUL, ce qui signifie que la receive_type est définie sur CM_RECEIVE_IMMEDIATE et qu’aucune donnée n’est disponible, il n’y a aucune modification d’État.

Le tableau suivant récapitule les modifications d’État qui peuvent se produire lorsque la réception est émise avec la conversation dans l’état d’envoi 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 SEND_PENDING
CM_NO_DATA_RECEIVED CM_SEND_RECEIVED Aucun changement

Le tableau suivant récapitule les modifications 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ésument les modifications d’État qui peuvent se produire lorsque la réception est émise dans n’importe quel état autorisé.

Dans cette section