Unité GEM : Fonction shel_write
Déclaration function shel_write( sh_wdoex, sh_wisgr,
sh_wisover : Integer;
sh_wpcmd, sh_wptail : String ) : Integer;
Notes du webmaster
J'ai reformulé et rééécrit complètement la doc de cette fonction y compris comparé aux doc web de MiNT et Compendium afibn de rendre le document plus logique.
Description Informe AES qu'une autre application doit être démarrée. En mode TOS, cet appel ne prend effet qu'à la fin du programme en cours.Cet appel est utile, par exemple, si un package de programme plus volumineux se compose de plusieurs programmes qui doivent être lancés l'un après l'autre pour des raisons d'espace mémoire.
Paramètres
- sh_wdoex Voir le tableau ci-dessous pour les détails
- sh_wisgr
- 0: pas d'application graphique (curseur, pas de souris)
- 1: Application graphique (souris, pas de curseur)
- sh_wisover réservé, dépend de conditions...
- sh_wpcmd Nom de fichier du programme à démarrer
- sh_wptail Ligne de commande du programme
Le répertoire par défaut sera choisi comme répertoire contenant le programme à lancer (Exception : mode étendu avec le bit 10 défini - voir ci-dessous).
À partir de la version 4.0 d'AES, cette fonction a été considérablement étendue, de sorte qu'il est désormais possible d'effectuer des tâches telles que l'arrêt du système, la modification de la résolution de l'écran, la diffusion AES et un certain nombre d'autres fonctions.
IMPORTANT: Dans les versions AES 4.0 et supérieures, appl_getinfo peut être utilisé pour déterminer la valeur légale la plus élevée pour le mode ainsi que la fonctionnalité des bits de mode étendu. De plus, seul l'Octet de poids faible du paramètre sh_wdoex sert dans le mode d'utilisation de cette fonction (valeurs comprises en 0 et 255), l'octet de poids fort servant en fonction des valeurs de ce poids faible de sh_wdoex.
Sous MultiTOS, les processus sont lancés simultanément avec leur parent. Un code de sortie est renvoyé dans un message CH_EXIT lorsque le processus enfant se termine. Voir evnt_mesag
Le paramètre sh_wisover permet de spécifier si les paramètres via ARGV doivent être transmis au programme lancé. Les conditions suivantes s'appliquent :
- sh_wisover = 0 : Ne pas utiliser la procédure ARGV
- sh_wisover = 1 : Utiliser la procédure ARGV
Sous MagiC, en revanche, il est possible de spécifier si un programme doit être démarré en mode monomode (ou en parallèle). Les conditions suivantes s'appliquent :
- sh_wisover = 100 : Exécuter le programme en parallèle
La nouvelle application hérite de tous les chemins et fichiers standard de l'application actuelle. Un code d'erreur est renvoyé uniquement en cas de manque de mémoire lors de l'installation ; aucune notification à la fin de la nouvelle application (death-of-child) n'existe (*).
- sh_wisover = 101 : Exécuter le programme en mode monomode
Ce mode correspond à sh_wisover avec la valeur 1, sauf qu'avant l'appel du programme, toutes les applications, à l'exception de celles d'ID 0 et 1 (SCRENMGR), sont gelées. Ces applications seront dégelées à la fin du programme, à condition qu'aucun nouvel appel à la fonction shel_write d'un caractère monomode ne soit effectué. La recette exacte pour le mode unique est la suivante :
- Assurez-vous que je suis l'application n° 0 (c.-à-d. ap_id == 0).
- Définissez les chemins et le lecteur du nouveau programme.
- shel_write (TRUE, sh_wisgr, 101, sh_wpcmd, sh_wptail).
- Tous les paramètres importants du fichier temporaire ou du tampon shell sont exécutés.
- Exécute appl_exit, v_clsvwk, Pterm0.
Il est également important de noter qu'à partir de MagiC 2, en mode unique, les chemins actuels de l'appelant sont transmis au parent et, par conséquent, au nouveau programme. Les chemins de l'appelant sont ensuite détruits, bien que cela ne soit pas critique, car le programme appelle généralement Pterm après shel_write. (*)..
Remarque : À partir de MagiC 3, les spécialités suivantes sont disponibles :
- Si une chaîne de caractères commençant par 255 et se terminant par "\0" est passée dans sh_wptail, la longueur réelle de la ligne de commande est déterminée par l'AES et transmise intégralement au DOS. Le DOS construit alors un paramètre ARGV dans l'environnement. Si la ligne de commande est inférieure à 127 octets, elle est transmise via la page de base et avec shel_read ; sinon, elle ne contient que l'octet de valeur 127.
- Si une chaîne de caractères commençant par 254 est passée dans sh_wptail, l'AES attend ensuite une chaîne de caractères « ARGV=quelque chose » suivie d'une liste de paramètres séparés par « \0 » et terminés par « \0\0 ». Cette chaîne est transmise intégralement au DOS, qui construit alors un paramètre ARGV. Si la ligne de commande est plus courte que 127 octets, elle est transmise via la page de base et avec shel_read, où les octets NULL sont remplacés par des espaces, sinon elle se compose uniquement de l'octet avec la valeur 127.
Modes (sh_wdoex) octet de poids faible
| Octet de poids faible de sh_wdoex | Signification |
|---|
| 0 (SWM_LAUNCH) | A partir d'AES 4.0 (sinon ce modene fait ... rien!) : lance le programme TOS, GEM ou Accessoire indiqué par les paramètres sh_wpcmd et sh_wptail.
sh_wptail pointe vers un tampon contenant la commande sh_wptail à transmettre au processus. Si sh_wisover est défini sur CL_NORMAL (0), sh_wptail est transmis normalement ; sinon, si sh_wisover est défini sur CL_PARSE (1), l'AES analyse tail et définit une chaîne d'environnement ARGV.
Ce mode utilise les modes étendues.
|
| 1 (SWM_LAUNCHNOW) | Lance une application GEM ou TOS en fonction de la valeur de sh_wisgr.
Si sh_wisgr est défini sur TOSAPP (0), l'application sera lancée comme une application TOS ; sinon, si sh_wisgr est défini sur GEMAPP (1), l'application sera lancée comme une application GEM. Pour la signification des autres paramètres, voir le mode SWM_LAUNCH (0). Les bits étendus de mode ne sont pris en charge que par les versions AES 4.0 et supérieures.
Les applications parentes qui lancent des applications enfants via ce mode sont suspendues sous MultiTOS.
Dans les versions AES 4.0 et supérieures, il est conseillé d'utiliser appl_getinfo pour déterminer le résultat exact de cet appel.
Ce mode utilise les modes étendues.
|
| 3 (SWM_LAUNCHNOW) | A partir d'AES 4.0. Lance un accessoire de bureau GEM. Pour la signification des autres paramètres, voir le mode SWM_LAUNCH (0).
Ce mode utilise les modes étendues.
|
| Dans les versions AES plus récentes, les modes supplémentaires suivants sont disponibles :
|
| 4 (SWM_SHUTDOWN) | A partir d'AES 4.0. Définition du mode d'arrêt
Cette commande place le système en mode normal ou en mode d'arrêt, selon le paramètre sh_wisover. Les conditions suivantes s'appliquent :
| sh_wisover | Signification |
|---|
-1 | L'AES appelle un petit programme pour sélectionner les options d'arrêt.
Depuis MyAES 0.96 |
0 (SD_ABORT) | Terminer la séquence d'arrêt
Un arrêt démarré ne peut être terminé que par le processus qui a également démarré cette séquence. |
1 (SD_PARTIAL) | Arrêt partiel
À l'exception de l'appelant, l'AES vérifie la compréhension du message AP_TERM pour toutes les applications ; si tel est le cas, l'AES envoie les messages AP_TERM ou AC_CLOSE aux programmes ou accessoires. L'appelant ne reçoit aucun de ces messages. |
2 (SD_COMPLETE) | Arrêt complet
À l'exception de l'appelant, l'AES vérifie la compréhension du message AP_TERM pour toutes les applications et accessoires ; si tel est le cas, l'AES envoie les messages AP_TERM ou AC_CLOSE aux programmes ou accessoires. Les accessoires reçoivent le message AP_TERM même après la réception du message AC_CLOSE. L'appelant ne reçoit aucun de ces messages. |
3 | Redémarrage à froid
Depuis MyAES 0.96. |
Dans N.AES, il existe un appel étendu :
shel_write(4, shutart, 0, @ignorant, NULL);
ignorant est ici un entier dont l'adresse est passée en quatrième paramètre de l'appel shel_write. En cas d'erreur, la valeur de retour de la fonction shel_write est 0 comme précédemment, mais en plus, ignorant contiendra l'APID (ID d'application) de l'application qui n'a pas compris AP_TERM, ou -1 si un arrêt est déjà en cours, ou -2 si des paramètres non valides ont été passés.
|
| 5 (SWM_REZCHANGE) | A partir d'AES 4.0. Changement de résolution
L'application invite l'AES à modifier la résolution. Si l'AES accepte la modification, il tente d'arrêter le système (Shutdown). Les applications actives peuvent alors soit s'arrêter, soit signaler à l'AES, via un message AP_TFAIL, qu'elles ne sont pas en mesure de le faire. Les paramètres sh_wisgr et sh_wisover sont interdépendants. Les règles suivantes s'appliquent :
| sh_wisover | Signification |
|---|
0 | Le paramètre sh_wisgr est l'ID du périphérique physique sur lequel l'appel "Open workstation" de l'interface VDI est exécuté. Le numéro du périphérique physique actuel peut être obtenu avec Getrez + 2, comme d'habitude ; Les valeurs suivantes sont disponibles :
- 2 = ST-Bas (320 * 200)
- 3 = ST-Moyen (640 * 200)
- 4 = ST-Haut (640 * 400)
- 6 = TT-Moyen (640 * 480)
- 8 = TT-Haut (1280 * 960)
- 9 = TT-Bas (320 * 480)
| 1. | Le paramètre sh_wisgr correspond à l'int16_t du mode vidéo du Falcon030
| >2. | Réservé pour des utilisations ultérieures.
|
Dans N.AES, il existe un appel étendu :
shel_write(5, vmode, falconflag, @ignorant, NULL);
Comme un changement de résolution déclenche toujours un arrêt complet en interne, il se peut que, là encore, toutes les applications ne comprennent pas AP_TERM, ce qui entraîne un échec prématuré du changement de résolution. Similairement à l'extension Mode 4 mentionnée ci-dessus, ici aussi l'ID d'application d'un non-comprenant sera conservé dans l'ignorance, ou un -1 si un arrêt est déjà en cours d'exécution, ou -2 si un paramètre défectueux (par exemple une résolution non valide) a été passé.
|
| 6 Inconnue |
|
| 7 (SWM_BROADCAST) | A partir d'AES 4.0. Diffusion AES
L'application souhaite envoyer un message à toutes les autres applications présentes sur le système. Seuls l'AES, le gestionnaire d'écran et l'expéditeur du message sont exclus de la réception.
Le paramètre sh_wpcmd est un pointeur vers un tampon de messages de 16 octets contenant les données à envoyer.
|
| 8 (SWM_ENVIRON) | A partir d'AES 4.0. Manipuler l'environnement AES.
Si sh_wisgr vaut ENVIRON_SIZE (0), la taille actuelle de la chaîne d'environnement est renvoyée.
Si sh_wisgr vaut ENVIRON_CHANGE (1), sh_wpcmd doit pointer vers une variable d'environnement à modifier. Si sh_wpcmd pointe vers "TOSEXT=TOS.TTP", cette chaîne sera ajoutée. De même, "TOSEXT=" supprimera cette variable d'environnement.
Si sh_wisgr vaut ENVIRON_COPY (2), AES copiera jusqu'à wiscr octets de la chaîne d'environnement actuelle dans un pointeur de tampon pointé par sh_wpcmd. La fonction renverra le nombre d'octets non copiés.
|
| 9 (SWM_NEWMSG) | A partir d'AES 4.0. Afficher les messages pris en charge
L'application indique à l'AES quels (nouveaux) messages sont compris. Cela se produit via les bits définis du paramètre sh_wisgr.
- Bit 0 : AP_TERM
- Bit 1 : NM_INHIBIT_HIDE (à partir de XaAES 2005-01-16)
Empêche le masquage de l'application. Utile pour certains utilitaires de bureau comme la barre des tâches.
Les autres bits (2 à 15) ne sont pas définis actuellement.
|
| 10 (SWM_AESMSG) | A partir d'AES 4.0. Envoyer un message à l'AES. sh_wpcmd pointe vers un tampon de 8 mots (16 octets) contenant le message à envoyer. Aucun autre paramètre n'est requis.
Geneva
Un programme peut faire défiler une boîte de dialogue fenêtrée en envoyant un message WM_ARROWED à Geneva. Exemple :
var
msg[8] : array[8] of Integer;
window_handle : Integer;
begin
msg[0] := WM_ARROWED;
msg[3] := window_handle;
msg[4] := WA_UPPAGE;
shel_write( SWM_AESMSG, 0, 0,
(int8_t *)msg, 0L );
end.
N.AES
N.AES peut être interrompu et revenir à un shell texte.
{
Déclencher un arrêt du système après
un arrêt « normal » réussi :
}
CONST
AP_AESTERM = 52;
procedure TerminateNAES;
var
int msg[8];
begin
msg[0] = AP_AESTERM;
shel_write(SWM_AESMSG, 0, 0, (char *)msg, NULL);
end;
|
| 20 | A partir d'AES ???. Créer un nouveau thread
Les conditions suivantes s'appliquent :
| Paramètre | Signification |
|---|
| sh_wisgr |
- 0 = Lancer le programme dans la fenêtre VT52 de l'application, si elle est ouverte
- 1 = Ne pas ouvrir de nouvelle fenêtre
- 2 = Ouvrir une nouvelle fenêtre VT52
|
| sh_wisover | 0
|
| sh_wpcmd | Pointeur vers la structure THREADINFO
|
| sh_wptail | Paramètre de type (void *) pour la fonction Thread |
En cas d'appel réussi, l'ID d'application du nouveau thread est renvoyé (*).
|
| 21 | A partir d'AES ???. Terminer un thread
Cet opcode permet à un thread de se terminer. Pour cela, définissez les paramètres sh_wisgr, sh_wisover et sh_wptail sur 0 ou NULL ; sh_wpcmd permet de spécifier un code d'erreur à renvoyer.
Normalement, l'exécution de cette fonction n'est pas nécessaire, car le thread se termine automatiquement à la fin de sa procédure (c'est-à-dire avec la commande CPU RTS). Important : Si le thread a effectué un appel Pexec, le processus en cours doit d'abord être terminé avec Pterm avant que le thread puisse se terminer (*).
|
| 22 | A partir d'AES ???. Terminer un thread
Avec cet opcode, un thread peut également être terminé par le programme principal. Pour cela, on passe l'identifiant d'application du thread dans le paramètre sh_wisover et on définit les paramètres restants à 0 ou NULL.
Normalement, cette fonction n'est pas nécessaire, car la fin du programme principal entraîne également la fin de tous les threads associés. La fonction a été exécutée avec succès lorsque la valeur 1 est renvoyée. Il est à noter, cependant, que si le thread a exécuté une commande Pexec entre-temps, seul ce programme sera terminé par Pterm (EBREAK) ; le thread lui-même n'est terminé que lorsque l'appelant a reçu une commande THR_EXIT (*).
|
| 224 | A partir de Geneva 004. Exécuter une application
Exécuter une application en laissant Geneva déterminer le type ; identique au mode 0, à la différence que le bit XSHD_FLAGS de sw_doex peut également être défini (voir ci-dessous).
|
| 225 | A partir de Geneva 004. Exécuter une application
Ceci est identique au mode 1, sauf que le bit XSHD_FLAGS de sw_doex peut également être défini.
|
| 227 | A partir de Geneva 004. Exécuter un accessoire de bureau.
Ceci est identique au mode 3, à la différence que le bit XSHD_FLAGS de sw_doex peut également être défini.
Lorsque XSHD_FLAGS (1<<15) est ajouté à sw_doex, cela signifie que le dernier mot long du SHWRCMD passé dans le paramètre sh_wpcmd contient les indicateurs du programme Geneva à utiliser lors de l'exécution de l'application. Il est fortement recommandé qu'un programme utilisant XSHD_FLAGS recherche les indicateurs actuels de l'application et ne modifie que ceux qui doivent être modifiés, plutôt que de définir la plupart des indicateurs à zéro ou une autre valeur aléatoire. Voir la section x_appl_flags pour un exemple.
|
Modes étendus
L'Octet de poids fort (train de 8 bits) de sh_wdoex est utilisé pour les modes étendus. Ce mode étendu n'est disponible que pour certaines valeurs de de base de sh_wdoex (Octet de poids faible).
| Nom - Masque de sh_wdoex | Signification |
|---|
| SW_PSETLIMIT 0x0100 (bit 8) | Initialisation des valeurs de Psetlimit |
| SW_PRENICE 0x0200 (bit 9) | Initial des valeurs de Prenice |
| SW_DEFDIR 0x0400 (bit 10) | Répertoire par défaut valide |
| SW_ENVIRON 0x0800 (bit 11) | chaîne d'Environnement validé |
| 0x1000 (bit 12) | Id utilisateur valide |
| 0x2000 (bit 13) | Id groupe valide |
| 0x4000 (bit 14) | Réservé |
| 0x8000 (bit 15) | Réservé (Voir drapeaux XSHD_FLAGS ci-dessous) |
Si l'octet supérieur de sh_wdoex est vide, le mode étendu n'est pas activé et sh_wpcmd spécifie le nom du fichier (pour rechercher le fichier avec shel_find()) ou la spécification complète du fichier. Sinon, si des bits étendus sont définis, sh_wpcmd pointe vers une structure _shelwPtr. _shelw.newcmd pointe vers le nom de fichier formaté comme indiqué ci-dessus.
- Si le bit 8 (SW_PSETLIMIT) du mode est défini, _shelw.psetlimit contient la taille mémoire maximale disponible pour le processus.
- Si le bit 9 (SW_PRENICE) du mode est défini, _shelw.prenice contient la priorité du processus à lancer.
- Si le bit 10 (SW_DEFDIR) du mode est défini, _shelw.defdir pointe vers une chaîne de caractères contenant le répertoire par défaut de lancement de l'application.
- Si le bit 11 (SW_ENVIRON) du mode est défini, _shelw.env pointe vers une chaîne d'environnement valide pour le processus.
-
- Si le bit 12 du mode est défini, _shelw.uid indique un nouvel id d'utilisateur.
-
- Si le bit 13 du mode est défini, _shelw.uid indique un nouvel id de groupe.
-
Remarques : Les bits 8 à 11 sont ignorés jusqu'à MagiC 3 ; le bit 8 est cependant pris en charge à partir de MagiC 4. La configuration du répertoire par défaut est beaucoup plus simple sous MagiC, car le nouveau programme hérite de tous les chemins d'accès sur tous les lecteurs du programme appelant. Geneva ne peut définir que le bit 8. Dans MagiC 6, les champs d'identifiant utilisateur et d'identifiant de groupe ont une signification différente.
Résultat Les modes SWM_LAUNCH (0), SWM_LAUNCHNOW (1) et SWM_LAUNCHACC (3) renvoient l'identifiant AES du processus démarré. Si la valeur 0 est renvoyée, le processus n'a pas été lancé.
Références croisées shel_read
|