Allocate (CPI-C)

  • Article

L’appel Allocate (nom de fonction cmallc) est émis par le programme appelant pour allouer une conversation avec le programme partenaire, en utilisant les caractéristiques de conversation actuelles. CPI-C peut également allouer une session entre l’unité logique locale (LU) et l’unité logique partenaire si elle n’existe pas déjà.

Syntaxe

  
CM_ENTRY Allocate(   
  unsigned char FAR *conversation_ID,    
    CM_INT32 FAR *return_code              
);

Paramètres

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

return_code
Code retourné par cet appel. Les codes de retour valides sont répertoriés plus loin dans cette rubrique.

Codes de retour

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

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

CM_OPERATION_INCOMPLETE
Code de retour principal ; une opération non bloquante a été démarrée sur la conversation, mais n’est pas terminée. 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.

CM_PARAMETER_ERROR
Code de retour principal ; l’une des opérations suivantes s’est produite :

  • Le nom de mode dérivé des informations latérales ou défini par Set_Mode_Name n’est pas valide.

  • Le nom du mode est utilisé par les programmes transactionnels de service SNA ; le programme d’appel n’a pas le pouvoir d’utiliser ce nom de mode. Par exemple, SNASVCMG.

  • Le programme partenaire dérivé des informations latérales est un TP de service SNA ; le programme local n’a pas le privilège requis pour allouer une conversation à un tp du service SNA.

  • Le programme partenaire est un tp de service, qui participe à des conversations de base, mais la conversation est définie sur CM_MAPPED_CONVERSATION.

  • Le nom de l’unité logique partenaire dérivé des informations latérales ou défini par Set_Partner_LU_Name n’est pas valide.

    CM_PROGRAM_PARAMETER_CHECK
    Code de retour principal ; la valeur spécifiée par conversation_ID n’est pas valide ou l’adresse d’une variable n’est pas valide.

    CM_PROGRAM_STATE_CHECK
    Code de retour principal ; la conversation n’est pas à l’état INITIALIZE.

    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_UNSUCCESSFUL
    Code de retour principal ; la caractéristique de contrôle de retour des conversations est définie sur CM_IMMEDIATE et l’unité logique locale n’avait pas de session de contention-gagnant disponible.

    Les codes de retour suivants peuvent être générés si le type de contrôle de retour des conversations est défini sur CM_WHEN_SESSION_ALLOCATED.

    CM_ALLOCATE_FAILURE_NO_RETRY
    Code de retour principal ; la conversation ne peut pas être allouée en raison d’une condition permanente, telle qu’une erreur de configuration ou une erreur de protocole de session. Pour déterminer l’erreur, l’administrateur système doit examiner le fichier journal des erreurs. Ne réessayez pas l’allocation tant que l’erreur n’a pas été corrigée.

    CM_ALLOCATE_FAILURE_RETRY
    Code de retour principal ; La conversation n’a pas pu être allouée en raison d’une condition temporaire, telle qu’un échec de liaison. La raison de l’échec est consignée dans le journal des erreurs système. Réessayez l’allocation.

    Changements d’état

    La conversation doit être à l’état INITIALIZE lors de l’émission de l’allocation .

    Les changements d’état, résumés dans le tableau suivant, sont basés sur la valeur du paramètre return_code .

return_code Nouvel état
CM_OK SEND
CM_ALLOCATE_FAILURE_NO_RETRY RESET
CM_ALLOCATE_FAILURE_RETRY RESET
Tous les autres Aucun changement

Remarques

Le type de conversation alloué est basé sur la caractéristique de type de conversation : mappée ou de base.

Lorsque la conversation a été allouée par cet appel, les caractéristiques de conversation suivantes ne peuvent pas être modifiées :

  • Type de conversation

  • Nom du mode

  • Nom de la lu partenaire

  • Nom du programme partenaire

  • Contrôle de retour

  • Niveau de synchronisation

  • Sécurité des conversations

  • Identificateur de l’utilisateur

  • Mot de passe

    Pour envoyer immédiatement la demande d’allocation, le programme d’appel peut émettre Vidage ou confirmation immédiatement après l’allocation. Sinon, la demande d’allocation s’accumule avec d’autres données dans la mémoire tampon d’envoi des unités logiques locales jusqu’à ce que la mémoire tampon soit saturée.

    En émettant Confirmer après l’allocation, le programme d’appel peut déterminer immédiatement si l’allocation a réussi (si le niveau de synchronisation de conversation est défini sur CM_CONFIRM).

    Si l’unité logique partenaire rejette la demande d’allocation générée par Allocate, l’erreur est retournée au programme d’appel lors d’un appel suivant.