Shell Library

AES shell functions. More...

Macros
#define	shel_envrn(a, b)   mt_shel_envrn(a,b,aes_global)
#define	shel_find(a)   mt_shel_find(a,aes_global)
#define	shel_get(a, b)   mt_shel_get(a,b,aes_global)
#define	shel_help(a, b, c)   mt_shel_help(a,b,c,aes_global)
#define	shel_put(a, b)   mt_shel_put(a,b,aes_global)
#define	shel_rdef(a, b)   mt_shel_rdef(a,b,aes_global)
#define	shel_read(a, b)   mt_shel_read(a,b,aes_global)
#define	shel_wdef(a, b)   mt_shel_wdef(a,b,aes_global)
#define	shel_write(a, b, c, d, e)   mt_shel_write(a,b,c,d,e,aes_global)

Functions
short	mt_shel_envrn (char **result, const char *param, short *global_aes)
short	mt_shel_find (char *buf, short *global_aes)
short	mt_shel_get (char *Buf, short Len, short *global_aes)
short	mt_shel_help (short sh_hmode, const char *sh_hfile, const char *sh_hkey, short *global_aes)
short	mt_shel_put (const char *Buf, short Len, short *global_aes)
short	mt_shel_rdef (char *lpcmd, char *lpdir, short *global_aes)
short	mt_shel_read (char *Command, char *Tail, short *global_aes)
short	mt_shel_wdef (const char *lpcmd, const char *lpdir, short *global_aes)
short	mt_shel_write (short Exit, short Graphic, short Aes, void *Command, char *Tail, short *global_aes)

Detailed Description

AES shell functions.

The Shell Library contains several miscellaneous functions most often used by the GEM Desktop and other 'Desktop-like' applications. Other applications may, however, need specific functions of the Shell Library for various tasks.

Macro Definition Documentation

#define shel_envrn	(		a,
			b
	)		mt_shel_envrn(a,b,aes_global)

single-thread version of mt_shel_envrn()

#define shel_find

(

a

)

mt_shel_find(a,aes_global)

single-thread version of mt_shel_find()

#define shel_get	(		a,
			b
	)		mt_shel_get(a,b,aes_global)

single-thread version of mt_shel_get()

#define shel_help	(		a,
			b,
			c
	)		mt_shel_help(a,b,c,aes_global)

single-thread version of mt_shel_help()

#define shel_put	(		a,
			b
	)		mt_shel_put(a,b,aes_global)

single-thread version of mt_shel_put()

#define shel_rdef	(		a,
			b
	)		mt_shel_rdef(a,b,aes_global)

single-thread version of mt_shel_rdef()

#define shel_read	(		a,
			b
	)		mt_shel_read(a,b,aes_global)

single-thread version of mt_shel_read()

#define shel_wdef	(		a,
			b
	)		mt_shel_wdef(a,b,aes_global)

single-thread version of mt_shel_wdef()

#define shel_write	(		a,
			b,
			c,
			d,
			e
	)		mt_shel_write(a,b,c,d,e,aes_global)

single-thread version of mt_shel_write()

Function Documentation

short mt_shel_envrn	(	char **	result,
		const char *	param,
		short *	global_aes
	)

searches the current environment string for a specific variable.

Parameters

result	points to a character pointer which will be filled in with the address of the first character in the environment string following the string given by param. If the string given by param is not found, value will be filled in with NULL. For instance, suppose the current environment looked like this: PATH=C:\;D:\;E:\ A call made to mt_shel_envrn() with param pointing to the string 'PATH=' would set the pointer pointed to by value to the string 'C:\;D:\;E:\' above.
param	see above
global_aes	global AES array

Returns

currently always returns 1.

Since

All AES versions.

AES versions prior to 1.4 only accepted semi-colons as separators between multiple 'PATH=' arguments. Newer versions accept commas as well.

The character string pointed to by name should include the name of the variable and the equals sign.

short mt_shel_find	(	char *	buf,
		short *	global_aes
	)

searches for a file along the AES's current path, any paths specified by the 'PATH' environmental variable, and the calling application's path.

Parameters

buf	should point to a character buffer of at least 260 characters and contain the filename of the file to search for on entry. If the function was able to find the file, the buffer pointed to by buf will be filled in with the full pathname of the file upon return.
global_aes	global AES array

Returns

0 if the file was not found or non-zero otherwise.

Since

All AES versions.

See also

mt_shel_write()

short mt_shel_get	(	char *	Buf,
		short	Len,
		short *	global_aes
	)

copies the contents of the AES's shell buffer (normally the 'DESKTOP.INF' or 'NEWDESK.INF' file) into the specified buffer.

Parameters

Buf	points to a buffer at least...
Len	...bytes long into which the AES should copy the shell buffer into.
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions.

See also

mt_shel_put()

AES versions prior to version 1.4 had a shell buffer size of 1024 bytes. Versions 1.4 to 3.0 had a shell buffer size of 4192 bytes.

In AES versions 4.0 or greater the shell buffer is no longer of a fixed size. When mt_appl_getinfo() with parameter AES_INQUIRE indicates that this feature is supported, length can be specified as SHEL_BUFSIZE to return the size of the current shell buffer.

short mt_shel_help	(	short	sh_hmode,
		const char *	sh_hfile,
		const char *	sh_hkey,
		short *	global_aes
	)

Call the help server

Parameters

sh_hmode	shall be SHP_HELP (only value handled at the moment)
sh_hfile	Name of the help-file. if sh_hfile has an extension (for example 'test.hyp'), then on the basis of the extension ( .hyp in the example), the appropriate server in the list of the Helpserver is invoqued. if sh_hfile has no extension (for example 'test'), then the first server defined in the CNF file of the Helpservers is invoqued.
sh_hkey	Keyword, to which an assistance text is to be spent, or ZERO.
global_aes	global AES array

Returns

A return value of zero signals an error.

Since

The presence of this function can be determined by mt_appl_getinfo() (Opcode 65).

See also

When the suitable help-server is found, then it is examined whether this is already active (as Accessory or also as concurrently started application). If this is the case, then the VA_START message is sent with sh_hfile and sh_hkey as arguments for command line. Otherwise, the suitable server is started with sh_hfile and sh_hkey parameters.

short mt_shel_put	(	const char *	Buf,
		short	Len,
		short *	global_aes
	)

copies information into the AES's shell buffer.

Parameters

Buf	points to a user memory buffer from which...
Len	...bytes are to be copied into the shell buffer.
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions.

See also

mt_shel_get()

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.

The Desktop uses the information in the shell buffer for several purposes. Applications should not use the shell buffer for their own purposes.

short mt_shel_rdef	(	char *	lpcmd,
		char *	lpdir,
		short *	global_aes
	)

"Shell READ default" - default program query

Parameters

lpcmd	Pointer on a sufficiently dimensioned string for the name of the application.
lpdir	Pointer on a sufficiently dimensioned stringer for the path of the application
global_aes	global AES array

Returns

The return value is not at present well-known.

Since

The presence of this function can be determined by mt_appl_getinfo() with mode AES_PCGEM. Under PC-GEM, this function is available since release 2.0

See also

mt_shel_wdef()

The function makes it possible to inquire the program which is started after completion of the current (f.e. the Desktop).

short mt_shel_read	(	char *	Command,
		char *	Tail,
		short *	global_aes
	)

is used to determine the current application's parent and the command tail used to call it.

Parameters

Command	points to a buffer which upon exit will be filled in with the complete file specification of the application. the buffer should have at least 260 bytes.
Tail	will likewise be filled in with the initial command line. The first BYTE of the command line indicates the length of the string which actually begins at &Tail[1].
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions.

short mt_shel_wdef	(	const char *	lpcmd,
		const char *	lpdir,
		short *	global_aes
	)

"Shell write default" - default program set

Parameters

lpcmd
lpdir
global_aes	global AES array

Returns

The return value is not at present well-known.

Since

The presence of this function can be determined by mt_appl_getinfo() with mode AES_PCGEM. Under PC-GEM, this function is available since release 2.0

See also

mt_shel_rdef()

The function makes it possible to specify the application which is to be the default program (normally the Desktop).

short mt_shel_write	(	short	wodex,
		short	wisgr,
		short	wiscr,
		void *	cmd,
		char *	tail,
		short *	global_aes
	)

is a multi-purpose function which handles the manipulation and launching of processes.

Parameters

wodex	specifies the action to perform. See the table hereafter.
wisgr	its meaning depends on wodex. See the table hereafter.
wiscr	its meaning depends on wodex. See the table hereafter.
cmd	its meaning depends on wodex. See the table hereafter.
tail	its meaning depends on wodex. See the table hereafter.
global_aes	global AES array

Returns

The value returned differs depending on the mode wodex which was invoked. See above for details.

Name	Mode	Meaning
SWM_LAUNCH	0	Launch a GEM or TOS application or GEM desk accessory depending on the extension of the file. This mode is only available as of AES version 4.0. wisgr is not used. tail points to a buffer containing the command tail to pass to the process. wiscr may be : CL_NORMAL, tail is passed normally, CL_PARSE, the AES will parse tail and set up an ARGV environment string. This function returns the AES id of the started process. If 0 is returned then the process was not launched. Under MultiTOS, processes are launched concurrently with their parent. An exit code is returned in a CH_EXIT message when the child terminates. In AES versions 4.0 and above, mt_appl_getinfo() should be used to determine the exact result of this call.
SWM_LAUNCHNOW	1	Launch a GEM or TOS application based on the value of wisgr. wisgr may be: TOSAPP : the application will be launched as a TOS application GEMAPP, the application will be launched as a GEM application. wiscr may be (MagiC extension): SHW_IMMED (not supported by MagiC) SHW_CHAIN : This is the procedure under TOS. The program makes the call, and after terminating itself the AES launches the new program. SHW_CHAIN does not work with desk accessories, as these must never be permitted to terminate. The new program inherits the standard paths and files that the previous program had at the time of its launch. In general these are in turn the ones that the program had that earlier launched the "ancestor" of the application with SHW_PARALLEL. In the case of application #0 therefore the new program gets the standard paths of the AES. If DESKTOP.APP (shell of GEM 2.2) is installed as a shell, then Mag!X will insert the current path and drive before the filename. SHW_DOS (not supported by MagiC) SHW_PARALLEL : A new application will be created. It inherits all standard paths and files from the current application. The new application runs in parallel to the previous one. One will only get an error code if a memory shortage occured during set-up. There is no message at the termination of the new application (no "death-of-child"). SHW_SINGLE Works like SHW_CHAIN, with the exception that before calling the program all applications apart from application 0 and 1 (SCRENMGR) are frozen. The programs are unfrozen once more after the program terminates as long as it did not make a new mt_shel_write() call with SHW_SINGLE on its part. One should add that from Mag!X 2.00 onward when calling mt_shel_write() in SHW_SINGLE mode the current paths of the caller are passed to the parent and hence to the new program. Warning: The paths of the calling program are destroyed after this, though this is not critical as the call following mt_shel_write() is generally a Pterm. For the meaning of returned value, see mode SWM_LAUNCH. How do I launch a program in "single mode" under MagiC ? Ensure that I am application 0 (i.e. ap_id == 0). Set paths and drive for the new program. mt_shel_write(1, isgr, SHW_SINGLE, cmd, path); All important settings to temporary file or shell-buffer. mt_appl_exit()/v_clsvwk()/Pterm0. How do I launch a program in "chain mode" under MagiC ? If appropriate set paths and drive for the new program and make a call mt_shel_write(1, dummy, SHW_SINGLE, dummy2, dummy3); in order to set the paths for the new program (incompatible to TOS). shel_write(1, isgr, SHW_CHAIN, cmd, path); All important settings to temporary file or shell-buffer. mt_appl_exit()/v_clsvwk()/Pterm0. After the program terminates the shell will be reloaded automatically. When calling the shell one gets in the command line (-> mt_shel_read() ) the "magic" sequence SHELTAIL. Parent applications which launch children using this mode are suspended under MultiTOS. In AES versions 4.0 and above, mt_appl_getinfo() should be used to determine the exact result of this call.
SWM_LAUNCHACC	3	Launch a GEM desk accessory. For the meaning of other parameters and the meaning of the return value, see mode SWM_LAUNCH. This mode is only supported by AES versions of at least 4.0.
SWM_SHUTDOWN	4	Manipulate 'Shutdown' mode. Shutdown mode is usually used prior to a resolution change to cause system processes to terminate. wiscr and cmd are ignored by this call. wisgr determines the action this call takes as follows: SD_ABORT : Abort shutdown mode SD_PARTIAL : Partial shutdown mode SD_COMPLETE : Complete shutdown mode N.AES has the following extension: tail may point to a word value. If the function returns 0 then you can find in tail the following information: the AES application ID of a program wich does not understand AP_TERM. -1 to inform that Shutdown is started -2 if some of the parameters are wrong. During a shutdown, processes which have registered themselves as accepting AP_TERM messages will be sent them and all accessories will be sent AC_CLOSE messages. In addition, in complete shutdown mode, AP_TERM messages will also be sent to accessories. Shutdown mode may be aborted but only by the original caller. The status of the shutdown is sent to the calling processes by AES messages. This mode is only supported by AES versions greater than or equal to 4.0.
SWM_REZCHANGE	5	Change screen resolution if wiscr is 0 then wisgr is the VDI work station ID of the new resolution. if wiscr is 1 then wisgr is video mode to use for the FALCON030 machine. others value of wiscr are reserved. If AES accepts the resolution change request, then it will put the system in SHUT DOWN mode. An application can either shut down and exit or deny to shut down by sending a AP_TFAIL message to the AES. N.AES has the following extension: tail may point to a word value. If the function returns 0 then you can find in tail the following information: the AES application ID of a program wich does not understand AP_TERM. -1 to inform that Shutdown is started -2 if some of the parameters are wrong. This mode is only recognized as of AES version 4.0.
SWM_BROADCAST	7	Broadcast an AES message to all processes. cmd should point to an 8 WORD message buffer containing the message to send. All other parameters are ignored. This mode is only recognized as of AES version 4.0.
SWM_ENVIRON	8	Manipulate the AES environment. wisgr may be: ENVIRON_SIZE, the current size of the environment string is returned. ENVIRON_CHANGE, cmd should point to a environment variable to modify. If cmd points to "TOSEXT=TOS,TTP", that string will be added. Likewise, "TOSEXT=" will remove that environment variable. ENVIRON_COPY, the AES will copy as many as wiscr bytes of the current environment string into a buffer pointer to by cmd. The function will return the number of bytes not copied. This mode is only recognized as of AES version 4.0.
SWM_NEWMSG	9	Inform the AES of a new message the current application understands. wisgr is a bit mask which specifies which new messages the application understands. bit 0 (NM_APTERM) informs the AES that the application understands AP_TERM messages. bit 1 (NM_INHIBIT_HIDE) prevent the application to be hidden. Usefull for "desktop" utilities like taskbar. This mode is only recognized as of AES version 4.0.
SWM_AESMSG	10	Send a message to the AES. cmd points to an 8 WORD message buffer containing the message to send. No other parameters are needed. This mode is only recognized as of AES version 4.0.
SWM_THRCREATE	20	The application produces a new Thread wisgr can be: 0 = Start program in the VT52 window of the application, if one is opened. 1 = do not open a VT52 window 2 = open new VT52-Fenster wiscr shall be set to 0 cmd Pointer on THREADINFO structure. tail Parameter of the type (void *) for the Thread function (see THREADINFO::proc). The function returns either 0 (error) or the application ID of the new thread ( > 0). The launched thread executes the function THREADINFO::proc, and the parameter tail is passed on the stack. THREADINFO::proc may alter the CPU registers d0-d2/a0-a2.
SWM_THREXIT	21	This mode allows a thread to terminate itself. wisgr, wiscr and tail shall be set to 0 cmd shall be set to the error code which will be returned to the parent process Returns 0 if an error occured (the function does not return when succeed !). An error can occur if the callers is not a thread but something else the thread has made a Pexec() call in the meantime Normally implementing of this function is not necessary, since the thread is automatically terminated with the end of its procedure (i.e. with the CPU instruction RTS). If the thread has made a Pexec() call, then the running process must be first terminated with Pterm() before the thread can terminate itself.
SWM_THRKILL	22	This mode allows the main program to terminate a thread. wiscr contains the application ID of the thread wisgr, tail and cmd shall be set to 0 Normally this function is not necessary, since with main program terminates, then all associated Threads are terminated as well. Returns 0 (error) or 1 (OK). An error can occur if: the ap_id is invalid the thread has already terminated itself it's not a thread running under the ap_id, but something else the thread does not belong to the caller Even if the return value is 1, one should note that in cases where the thread has launched another program with Pexec() in the meantime, only this program will be terminated with Pterm(EBREAK). The thread will only be terminated when the caller has received THR_EXIT. Warning: One should note that the memory that the thread allocates belongs to the process, i.e. it is not released automatically when the thread terminates. The same applies for open files, which are closed only on program termination.

The parameter wodex have extended bits, only supported by AES versions of at least 4.0. When the lower eight bits of mode are SWM_LAUNCH, SWM_LAUNCHNOW, or SWM_LAUNCHACC, appropriate bits in the upper byte may be set to enter 'extended' mode. The bits in the upper byte are assigned as follows:

• SW_PSETLIMIT
• SW_PRENICE
• SW_DEFDIR
• SW_ENVIRON
• SW_UID (XaAES only extension)
• SW_GID (XaAES only extension)
• SHW_XMDFLAGS (MagiC6 only extension)

If the upper byte is empty, extended mode is not entered and cmd specifies the filename (to search for the file with mt_shel_find() ) or the complete file specification. Otherwise, if any extended bits are set, cmd points to a SHELW structure (or XSHW_COMMAND structure if you use MagiC6 extension).

Since

All AES versions. In AES versions 4.0 and above, mt_appl_getinfo() with parameter AES_SHELL can be used to determine the highest legal value for mode as well as the functionality of extended mode bits.