HomeAESResource libraryExtended graphics library

8.18 Shell library

This library contains functions to read information from the program environment (such as the GEM desktop and similar applications), or to write them; in addition they can take on the launch of other GEM programs. The following routines are available for this:

shel_envrn Obtains value of environment variable
shel_find Searches for a file
shel_get Reads from the environment buffer
shel_help Outputs Help-texts
shel_put Writes to the environment buffer
shel_rdef Inquires the default program
shel_read Reads command line parameters
shel_wdef Sets the default program
shel_write Launches application

Note: Here special merit has been earned by shel_write, which as of AES Version 4.0 (or MagiC 3) has made many other useful things available, such as Shutdown of the system, resolution changes, AES broadcasting etc.

See also: About the AES   Style guidelines

8.18.1 shel_envrn

Name: »Shell environment« - Obtains value of environmental variables.
Opcode: 125
Syntax: int16_t shel_envrn ( int8_t **sh_epvalue, int8_t *sh_eparm );
Description: The call shel_envrn searches the current environment string to find the value of a specific environmental variable of the AES. The following apply:
Parameter Meaning
   
sh_epvalue Name of the environmental variable
sh_eparm After the call contains the value of the corresponding variable


Example: If the current environment is, say: 'PATH=C:\;D:\;E:\' then calling shel_envrn with sh_eparm pointing to the string 'PATH=' would set the pointer pointed to by sh_epvalue to the start of the string 'C:\;D:\;E:\'. Note that the character string pointed to by sh_eparm should include the name of the variable and the 'equals' sign.

Note: To change the AES environment, one should hook into the exec_os vector, which is also used to launch GEM. In the called routine, the basepage pointer lies on the stack (as in a program). In this basepage one can then simply enter a pointer to the new environment.

But a word of warning: In AES versions lower than 1.4, only the first 50 bytes will be adopted; also these only accept semicolons as separators between multiple 'PATH=' arguments, while later versions accept commas as well.

Another tip: If the pointer returned for 'PATH=' points to a NULLbyte, one should increase it by the value 1 to get the correct result.
Return value: The function always returns a value of 1.
Availability: All AES versions.
Group: Shell library
See also: Binding

8.18.1.1 Bindings for shel_envrn

C: int16_t shel_envrn ( int8_t **sh_epvalue, int8_t *sh_eparm );
Binding:
int16_t shel_envrn (int8_t **sh_epvalue, int8_t *sh_eparm)
{
   addr_in[0] = sh_epvalue;
   addr_in[1] = sh_eparm;

   return ( crys_if(125) );
}
GEM-Arrays:

Address Element Contents
control control[0] 125 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] sh_epvalue
addr_in addr_in[1] sh_eparm
int_out int_out[0] Return value

8.18.2 shel_find

Name: »Shell find« - Find a file.
Opcode: 124
Syntax: int16_t shel_find ( int8_t *sh_fpbuff );
Description: The call shel_find searches for a file in certain directories. The parameter sh_fpbuff contains the name of the file searched for. On returning from the call, the full access path to the file will be stored in this buffer, which should be at least 128 characters long.

Note: The file will be searched for in the following directories:
  • In the current directory
  • In the root directory
  • In all directories specified in the environmental variable 'PATH' of the AES
  • In the path of the calling application (as of TOS version 1.04)


The function is also used by rsrc_load to localize the resource file.
Return value: A value of 0 signals that the specified file was not found.
Availability: All AES versions.
Group: Shell library
See also: Binding   shel_envrn

8.18.2.1 Bindings for shel_find

C: int16_t shel_find ( int8_t *sh_fpbuff );
Binding:
int16_t shel_find (int8_t *sh_fpbuff)
{
   addr_in[0] = sh_fpbuff;
   return ( crys_if(124) );
}
GEM-Arrays:

Address Element Contents
control control[0] 124 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] sh_fpbuff
int_out int_out[0] Return value

8.18.3 shel_get

Name: »Shell get« - Read from the GEM environment buffer.
Opcode: 122
Syntax: int16_t shel_get ( int8_t *sh_gaddr, uint16_t sh_glen );
Description: The call shel_get serves for reading characters from the internal environment storage buffer of the AES. The following apply:
Parameter Meaning
   
sh_gaddr Address of the destination memory store
sh_glen Number of bytes to be read, or the value -1 to obtain the length of the memory store


Note: The desktop uses this buffer to store the DESKTOP.INF or NEWDESK.INF file. Although the format of these files is not officially documented, a current description can be found in newdesk.hyp.

Under MagiC, at the start of the AES all data are copied into the buffer that lies after the line '#_CTR' in MAGX.INF. Since MagiC 3, the permissible length of the buffer lies between 4192 and 65534 bytes. The presence of the additional features can be ascertained with a call of appl_getinfo (opcode 6).
Return value: An error has arisen only if the value 0 is returned.
Availability: All AES versions.
Group: Shell library
See also: Binding   shel_put

8.18.3.1 Bindings for shel_get

C: int16_t shel_get ( int8_t *sh_gaddr, uint16_t sh_glen );
Binding:
int16_t shel_get (int8_t *sh_gaddr, uint16_t sh_glen)
{
   int_in[0]  = sh_glen;
   addr_in[0] = sh_gaddr;

   return ( crys_if(122) );
}
GEM-Arrays:

Address Element Contents
control control[0] 122 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] sh_glen
addr_in addr_in[0] sh_gaddr
int_out int_out[0] Return value

8.18.4 shel_help

Name: »Shell help« - Output of Help-texts.
Opcode: 128
Syntax: int16_t shel_help ( int16_t sh_hmode, int8_t *sh_hfile, int8_t *sh_hkey);
Description: The call shel_help serves for outputting Help-texts (online help) via a help server.
Parameter Meaning
sh_hmode At present always pass SHP_HELP(=0)
sh_hfile Name of the help file

If this is passed including an extension, the corresponding server according to the extension will be searched for in the list of help servers

If the passed file has no extension, then that of the first help server defined in the CNF file will be appended automatically
sh_hkey Key-word for which a Help-text is to be output, or NULL


At a call of shel_help with a file having an extension, N.AES checks whether a help server for this extension has been defined (with 'helpserver'). If a suitable server is found, a check is made whether this is active already (as a desk accessory or application launched in parallel). If that is the case, then the server is sent the message VA_START with the arguments specified in sh_hfile and sh_hkey as a command line.

If the server is not active, then it will be launched automatically if a path was specified for it in its definition with 'helpserver'. As a command line the arguments specified in sh_hfile and sh_hkey will be passed.
Return value: An error has arisen only if the value 0 is returned.
Availability: The presence of this function can be ascertained with a call of appl_getinfo (opcode 65).

Besides N.AES, there is a TSR which makes this function available on other systems as well.
Group: Shell library
See also: Binding

8.18.4.1 Bindings for shel_help

C: int16_t shel_help ( int16_t sh_hmode, int8_t *sh_hfile, int8_t *sh_hkey);
Binding:
int16_t shel_help ( int16_t sh_hmode, int8_t *sh_hfile,
                    int8_t *sh_hkey)
{
   int_in[0] = sh_hmode;
   addr_in[0] = sh_hfile;
   addr_in[1] = sh_hkey;

   crys_if(128);

   return = int_out[0];
}
GEM-Arrays:

Address Element Contents
control control[0] 128 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] sh_hmode
addr_in addr_in[0] sh_hfile
addr_in+4 addr_in[1] sh_hkey
int_out int_out[0] Return value

8.18.5 shel_put

Name: »Shell put« - Writes to the GEM environment buffer.
Opcode: 123
Syntax: int16_t shel_put ( int8_t *sh_paddr, uint16_t sh_plen );
Description: The call shel_put copies information to the environment shell buffer of the AES. The following apply:

Parameter Meaning
sh_paddr Address of source buffer (in user memory)
sh_plen Number of characters to be written


Note: The desktop uses this buffer to store the DESKTOP.INF or NEWDESK.INF file. Although the format of these files is not officially documented, a current description can be found in newdesk.hyp.

The permissible length of the buffer lies since MagiC 3 between 4192 and 65534 bytes, while in very old TOS versions it was restricted to 1024 bytes.

Prior to AES version 4.0 this function would only copy as many bytes as would fit into the current buffer. As of version 4.0, the AES will dynamically allocate more memory as needed (up to 32767 bytes) for the shell buffer.
Return value: An error has arisen only if the value 0 is returned.
Availability: All AES versions.
Group: Shell library
See also: Binding   shel_get   shel_envrn   shel_find

8.18.5.1 Bindings for shel_put

C: int16_t shel_put ( int8_t *sh_paddr, uint16_t sh_plen );
Binding:
int16_t shel_put (int8_t *sh_paddr, uint16_t sh_plen)
{
   int_in[0]  = sh_plen;
   addr_in[0] = sh_paddr;

   return ( crys_if(123) );
}
GEM-Arrays:

Address Element Contents
control control[0] 123 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] sh_plen
addr_in addr_in[0] sh_paddr
int_out int_out[0] Return value

8.18.6 shel_rdef

Name: »Shell read default« - Inquire the default program.
Opcode: 126
Syntax: int16_t shel_rdef ( int8_t *lpcmd, int8_t *lpdir );
Description: The call shel_rdef permits inquiring the program to be launched at the termination of the current one (the desktop, as a rule). The following apply:
Parameter Meaning
lpcmd Pointer to a string of sufficient size to hold the name of the application
lpdir Pointer to a string of sufficient size to hold the path of the application
Return value: This is not known at present.
Availability: Under PC-GEM, the function is available as of version 2.0; otherwise in KAOS 1.4.2 and MagiC. The presence of this function can be ascertained with appl_getinfo (opcode 5).
Group: Shell library
See also: Binding   shel_wdef   MagiC

8.18.6.1 Bindings for shel_rdef

C: int16_t shel_rdef ( int8_t *lpcmd, int8_t *lpdir );
Binding:
int16_t shel_rdef (int8_t *lpcmd, int8_t *lpdir)
{
   addr_in[0] = lpcmd;
   addr_in[1] = lpdir;

   return ( crys_if(126) );
}
GEM-Arrays:

Address Element Contents
control control[0] 126 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] lpcmd
addr_in+4 addr_in[1] lpdir
int_out int_out[0] Return value

8.18.7 shel_read

Name: »Shell read« - Read command line parameters of the application.
Opcode: 120
Syntax: int16_t shel_read ( int8_t *sh_rpcmd, int8_t *sh_rptail );
Description: The call shel_read obtains the name and the command line tail with which an application was launched. The following apply:
Parameter Meaning
   
sh_rpcmd Complete pathname with program name
sh_rptail Command line (according to Pexec, so NULL-terminated and with length specified in first byte)


Note: The function only works correctly if the application was launched with shel_write. In case of doubt, therefore, one should fall back to the values from the basepage.
Return value: An error has arisen only if the value 0 is returned.
Availability: All AES versions.
Group: Shell library
See also: Binding   shel_write   Pexec

8.18.7.1 Bindings for shel_read

C: int16_t shel_read ( int8_t *sh_rpcmd, int8_t *sh_rptail );
Binding:
int16_t shel_read (int8_t *sh_rpcmd, int8_t *sh_rptail)
{
   addr_in[0] = sh_rpcmd;
   addr_in[1] = sh_rptail;

   return ( crys_if(120) );
}
GEM-Arrays:

Address Element Contents
control control[0] 120 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] sh_rpcmd
addr_in+4 addr_in[1] sh_rptail
int_out int_out[0] Return value

8.18.8 shel_wdef

Name: »Shell write default« - Set the default program.
Opcode: 127
Syntax: int16_t shel_wdef( int8_t *lpcmd, int8_t *lpdir );
Description: The call shel_wdef allows setting the application that is to be regarded as the default program (normally the desktop).

Note for MagiC: If the parameters lpcmd and lpdir are empty strings, then MAGXDESK will be reinstalled. An alternative desktop simply makes a shel_write call at launch, and then terminates itself with Pterm0; it receives from MagiC a command line (SHELTAIL), which can be obtained with shel_read. If the shell returns a negative error-code, then MAGXDESK will be activated.

Note for N.AES: If the parameters lpcmd and/or lpdir are empty strings or NULL, then the 'shell' application specified in N_AES.CNF will be launched.
Return value: This is not known at present.
Availability: Under PC-GEM, the function is available as of version 2.0; otherwise in KAOS 1.4.2 and MagiC. The presence of this function can be ascertained with appl_getinfo (opcode 5).
Group: Shell library
See also: Binding   shel_rdef   MagiC

8.18.8.1 Bindings for shel_wdef

C: int16_t shel_wdef( int8_t *lpcmd, int8_t *lpdir );
Binding:
int16_t shel_wdef(int8_t *lpcmd, int8_t *lpdir)
{
   addr_in[0] = lpcmd;
   addr_in[1] = lpdir;

   return ( crys_if(127) );
}
GEM-Arrays:

Address Element Contents
control control[0] 127 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] lpcmd
addr_in+4 addr_in[1] lpdir
int_out int_out[0] Return value

8.18.9 shel_write

Name: »Shell write« - Launch another application.
Opcode: 121
Syntax: int16_t shel_write ( int16_t sh_wdoex, int16_t sh_wisgr, int16_t sh_wiscr, int8_t *sh_wpcmd, int8_t *sh_wptail );
Description: The call shel_write permits launching another program. As of AES version 4.0 this function was expanded greatly, so now one can also perform tasks such as the Shutdown of the system, changing screen resolution, AES broadcasting and a number of other functions.

The parameter sh_wdoex determines the action to be performed, the remaining parameters depend in essence on sh_wdoex. The following apply:
sh_wdoex Meaning
   
0 Launch application
The value of the parameter sh_wisgr (launch in graphic mode, yes/no) is set automatically by the AES, by comparing the file extension with the contents of AES environmental variables GEMEXT, TOSEXT and ACCEXT
1 Launch application im GEM/TOS mode
The parameter sh_wisgr sets the mode in which the program is to be launched; the following apply:
sh_wisgr = 0: Launch as TOS program
sh_wisgr = 1: Launch as GEM program
2 Reserved
3 Start accessory
A program is to be launched as a desk accessory


In the parameters sh_wpcmd and sh_wptail one should pass the filename of the program to be launched and a pointer to the command line tail respectively. The default directory will be chosen as the directory that contains the program to be launched (Exception: extended mode with bit 10 set - see below).

The function returns the AES ID of the launched process. A value of 0 in this connection denotes that an error has occurred. With the parameter sh_wiscr one can specify whether parameters via ARGV should be passed to the launched program. The following apply:

sh_wiscr = 0: Do not use ARGV procedure
sh_wiscr = 1: Use ARGV procedure

Under MagiC, on the other hand, one can specify whether a program is to be started in single-mode (or in parallel). The following apply:

sh_wiscr = 100: Execute program in parallel
The new application inherits all standard paths and files from the current application. An error-code is returned only in case of memory shortage during the installation; a notification at the termination of the new application (death-of-child) does not exist (*).

sh_wiscr = 101: Execute program in single-mode
This mode corresponds to sh_wiscr with the value 1, except that before the program is called all applications apart from those with ID 0 and ID 1 (SCRENMGR) are frozen. Those applications will be thawed out again at the termination of the program, as long as that does not make a new shel_write call of a single-mode character. The exact recipe for the single-mode is:
  • Ensure that I am application #0 (i.e. ap_id == 0)
  • Set paths and drive for the new program
  • shel_write (TRUE, sh_wisgr, 101, sh_wpcmd, sh_wptail)
  • All important settings to temporary file or shell-buffer
  • appl_exit, v_clsvwk, Pterm0 execute


One should also note that as of MagiC 2, in single-mode the current paths of the caller are passed to the parent and with that to the new program. The caller's paths are destroyed subsequently, though this is not critical as the program will normally follow shel_write with a Pterm call (*).

In extended mode one can further specify the launching of programs via the special bits of the parameter sh_wdoex. The low byte stays untouched here, and for the high byte the following apply:

sh_wdoex bit Meaning
8 Value of Psetlimit
9 Value of Prenice
10 Default directory
11 Environment string
12 Reserved
13 Reserved
14 Reserved
15 Reserved


In this extended mode, the parameter sh_wpcmd is taken as a pointer to a set of 32-bit (LONG) values. Each of the above-named bits is assigned a LONG value which is valid when the corresponding bit is set. The set of 32-bit values is allocated as follows:
Element Meaning
   
[0] Pointer to the name of the program
[1] Value of Psetlimit (bit 8)
[2] Value of Prenice (bit 9)
[3] Pointer to the default directory; a NULL-pointer in this connection means that the directory in which the program to be launched lies is selected as the default directory (bit 10)
[4] Pointer to the environment of the application (bit 11)


Note: The elements [1], [2] and [3] are ignored up to MagiC 3; element [1] however is supported from MagiC 4 onwards. The default directory is set much simpler under MagiC, as the new program inherits all paths on all drives from the calling program. Geneva can only set bit 8.

In newer AES versions the following additional modes are available:
sh_wdoex Meaning
4 Set Shutdown mode
This command puts the system into the normal or Shutdown mode, depending on the parameter sh_wiscr. The following apply:
sh_wiscr Meaning
   
0 Terminate Shutdown sequence
A started Shutdown can only be terminated by that process that also started this sequence
1 Partial Shutdown
With the exception of the caller, all applications are checked by the AES on whether they understand the message AP_TERM; if this is the case, then the AES sends the messages AP_TERM or AC_CLOSE to the programs or accessories. The caller receives none of these messages.
2 Complete Shutdown
With the exception of the caller, all applications and accessories are checked by the AES on whether they understand the message AP_TERM; if this is the case, then the AES sends the messages AP_TERM or AC_CLOSE to the programs or accessories. Accessories receive the AP_TERM message also after the receipt of the AC_CLOSE message. The caller receives none of these messages.


In N.AES there is an extended call:
shel_write(4, shutart, 0, &ignorant, NULL);

ignorant is here an integer whose address is passed as the fourth parameter of the shel_write call. In case of error the return value of the function shel_write is 0 as before, but in addition, ignorant will hold the apid (application ID) of the application that has not understood AP_TERM, or -1 if a Shutdown is already running, or -2 if invalid parameters were passed.
5 Resolution change
The application invites the AES to change the resolution. If the AES agrees to the change, it attempts to close down the system (Shutdown). Any active applications can now either terminate themselves, or tell the AES with an AP_TFAIL message that they are not in a position to do so. The parameters sh_wisgr and sh_wiscr are dependent on one another. The following apply:
sh_wiscr Meaning
   
0 The parameter sh_wisgr is the ID of the physical device on which the 'Open workstation' call of the VDI is executed. The current physical device number can be obtained with Getrez + 2 as usual; the following values are available:
2 = ST-Low (320*200)
3 = ST-Medium (640*200)
4 = ST-High (640*400)
6 = TT-Medium (640*480)
8 = TT-High (1280*960)
9 = TT-Low (320*480)
1 The parameter sh_wisgr is the int16_t for the video mode of the Falcon030
>2 Reserved for future purposes


In N.AES there is an extended call:
shel_write(5, vmode, falconflag, &ignorant, NULL);
As a resolution change always first starts a complete Shutdown internally, it could be that here too not all applications understand AP_TERM and so the resolution change fails prematurely. Similar to the Mode 4 extension mentioned above, here too the application ID of a non-understander will be held in ignorant, or a -1 if a Shutdown is running already, or -2 if a faulty parameter (e.g. an invalid resolution) was passed.
6 unknown
7 AES broadcasting
The application would like to send a message to all other applications present in the system. Excepted from receipt are only the AES, the screen-manager, as well as the sender of the message itself.

The parameter sh_wpcmd is a pointer to a 16-byte sized message buffer that contains the data to be sent.
8 Manipulation of the AES environment
This command permits the modification of the AES environment. The parameter sh_wisgr describes the desired action. The following apply:
sh_wisgr Meaning
   
0 Get size of environment buffer This is returned as the function result
1 Insertion/Removal of strings The parameter sh_wpcmd is a pointer to the environment string. The syntax for insertion or removal runs: 'NEW=STRING\0' or NEW=\0'.
2 Copy contents of the environment buffer
The parameter sh_wpcmd is a pointer to the receiving buffer, which has a size of sh_wiscr bytes. The function returns the number of bytes that could not be copied.
9 Show supported messages
The application tells the AES, which (new) messages are understood. This happens via the set bits of the parameter sh_wisgr.
Bit 0: AP_TERM
Bit 1: NM_INHIBIT_HIDE (as of XaAES 2005-01-16)
Prevents the application from being hidden. Useful for some 'desktop' utilities like Taskbar.


All other bits (2-15) are not defined at present.
10 Send message to the AES
The application wants to send a message to the AES. The parameter sh_wpcmd is a pointer to a 16-byte sized message buffer.
Geneva

A program can cause a windowed dialog to scroll by sending a WM_ARROWED message to Geneva. Example:

  int16_t msg[8];

  msg[0] = WM_ARROWED;
  msg[3] = window_handle;
  msg[4] = WA_UPPAGE;
  shel_write( SHW_SENDTOAES, 0, 0, (int8_t *)msg, 0L );
20 Create new thread
With this opcode the application can create a new thread. The following apply:
Parameter Meaning
   
sh_wisgr
0 = Launch program in VT52 window of the application, if one is open
1 = Don't open a new window
2 = Open a new VT52 window
sh_wiscr 0
sh_wpcmd Pointer to THREADINFO structure
sh_wptail Parameter of type (void *) for the Thread function


With a successful call the application ID of the new thread will be returned (*).
21 End thread
With this opcode a thread can end itself. For this one sets the parameters of sh_wisgr, sh_wiscr and sh_wptail to the values 0 or NULL; with sh_wpcmd one can specify an error-code to be returned.

Normally an execution of this function is not necessary, since the thread ends itself automatically at the end of its procedure (i.e. with the CPU command RTS). Important: If the thread has made a Pexec call, then the running process must first be terminated with Pterm, before the thread can end itself (*).
22 Terminate thread
With this opcode a thread can also be ended by the main program. For this one passes in the parameter sh_wiscr the application's ID of the thread, and sets the remaining parameters to the value 0 or NULL.

Normally this function is not necessary, as with the termination of the main program all associated threads are ended as well. The function was executed successfully when the value 1 is returned as a result. One should note, however, that if in the meantime the thread has performed a Pexec, only that program will be terminated with Pterm (EBREAK); the thread itself is only ended when the caller has received a THR_EXIT (*).
224 Run an application (Geneva as of Update 004)
Run an application, letting Geneva determine the type; this is identical to mode 0, except that the XSHD_FLAGS bit of sw_doex can also be set (see below)
225 Run an application (Geneva as of Update 004)
This is identical to mode 1, except that the XSHD_FLAGS bit of sw_doex can also be set.
227 Run a desk accessory. (Geneva as of Update 004)
This is identical to mode 3, except that the XSHD_FLAGS bit of sw_doex can also be set.

When XSHD_FLAGS (1<<15) is added to sw_doex, this means that the last LONGword of the SHWRCMD passed in the sh_wpcmd parameter contains the Geneva program flags to use when executing the application. It is strongly recommended that a program using XSHD_FLAGS inquire the current flags for the application and only change the ones it needs to change, rather than making most of the flags zero or some other random value. See the x_appl_flags section for an example.


Note: As of MagiC 3, the following specialities are available:
  • If a character string is passed in sh_wptail that starts with the value 255 and is terminated with '\0', the actual length of the command line is determined by the AES and passed at full length to the DOS. DOS constructs from this an ARGV parameter in the environment. If the command line is shorter than 127 bytes, it is passed via the basepage and with shel_read, else it consists only of the byte with the value 127.

  • If a character string is passed in sh_wptail that starts with the value 254, then the AES expects after this a character string 'ARGV=something' and a '\0'-separated and with '\0\0'-terminated list of parameters. This is passed completely to the DOS, which constructs an ARGV parameter from this. If the command line is shorter than 127 bytes, it is passed via the basepage and with shel_read, where the NULLbytes are replaced with spaces, else it consists only of the byte with the value 127.



The presence of the additional features can be inquired with appl_getinfo (opcode 10).

The shel_write opcodes marked with (*) are at present available only in MagiC.

Warning: If one launches a new AES process under Single- TOS with shel_write, then this will be launched only after the termination of the running process.
Return value: An error has arisen only if the value 0 is returned.
Availability: All AES versions.
Group: Shell library
See also: Binding   Shutdown mechanism   Threads in MagiC

8.18.9.1 Bindings for shel_write

C: int16_t shel_write ( int16_t sh_wdoex, int16_t sh_wisgr, int16_t sh_wiscr, int8_t *sh_wpcmd, int8_t *sh_wptail );
Binding:
int16_t shel_write (int16_t sh_wdoex, int16_t sh_wisgr,
                    int16_t sh_wiscr, int8_t *sh_wpcmd,
                    int8_t *sh_wptail)
{
   int_in[0]  = sh_wdoex;
   int_in[1]  = sh_wisgr;
   int_in[2]  = sh_wiscr;
   addr_in[0] = sh_wpcmd;
   addr_in[1] = sh_wptail;

   return ( crys_if(121) );
}
GEM-Arrays:

Address Element Contents
control control[0] 121 # Function opcode
control+2 control[1] 3 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] sh_wdoex
int_in+2 int_in[1] sh_wisgr
int_in+4 int_in[2] sh_wiscr
addr_in addr_in[0] sh_wpcmd
addr_in+4 addr_in[1] sh_wptail
int_out int_out[0] Return value

HomeAESResource libraryExtended graphics library