Allocate (CPI-C)
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.