% $Id: APPNAME.TEX 1.1 2000/01/24 10:18:50 ska Exp ska $
\section{\labal{ssAppName}\subsys{appName}}

To provide various information about the currently running
application in a portable way this subsystem has been implemented.

\subsys{appName} stands for "{}application name"{} and more or less
returns information derived from the name of the application only.
The term {\em application} refers to the program (executable file)
that has been invoked lately.

\subsection{Design}

When an application is invoked by DOS3+, its name and location are
stored in its environment segment within the string area as
the first entry, refer to \ref{envBackground} for more details.
\subsys{appName} now extracts this information and preprocesses it to
provide the user with some broken up and derived information, such as:
\begin{itemize}
\item name of the application,
\item fully-qualified path of the executable of the application, and
\item the fully-qualified name of the executable.
\end{itemize}

Due to efficiency and portably reasons no auto-configuration feature
can be provided -- though this may change in the future or in conjunction
with particular compilers and libraries. To have no auto-configuration means
that an initialization function must be called prior to invoke functions
of \subsys{appName} {\em and} trust their return values.

Because this information is assumed to remain unchanged during the
life-time of the application and that there is no need to change it
by request of the programmer, the information is retreived once and
kept within a buffer and is re-used all the time. This also implies that
the values returned may never be modified by the user.

In order to support maximum portability no assumptions about the
length of the returned strings nor that the pointers are always the
same must be made.

\subsection{Implementation}

\paragraphe{Initialization functions} are required to set up internally
used structures and must be called in order to let the other functions
work correctly. Two such functions are available:
\begin{enumerate}
\item \fct{int appInit(const char * const fnam)}, and
\item \fct{int appInitEnv(void)}.
\end{enumerate}
Both functions return non-zero on failure.

Usually, C programmers are to use the hosted C environment
described in the ISO9899 standard (ANSI C), in which the command line
arguments and the name of the executable file are passed within an array
to the \fct{main()} function. In this case the function \fct{appInit} seems
to be the most portable way:
\begin{verbatim*}
#include <stdio.h>

int main(int argc, char **argv)
{	/* Name of application in: argv[0] */

	if(appName(argv[0])) {
		puts("Cannot initialize subsystem 'appName'");
		return 1;
	}

	...
	return 0;
}
\end{verbatim*}

Tprior retreiving the particular information, if and only
if \subsys{appName} has not been initialized already. That way the
implementation can make use of the retreival function with some sort of
ensurance that they return proper values. Though, the function \fct{main()} can alternatively be used without
parameters, thus, ignoring both command line paramters and the name of
the file. Doing so saves some of the valueable memory in DOS with many
compilers. In such cases the other function tries to fetch the proper
name of the executable file itself, thus the program might look like
this:
\begin{verbatim*}
#include <stdio.h>

int main(void)
{	/* Name of application in argv[0] is not accessable */

	if(appNameEnv()) {
		puts("Cannot initialize subsystem 'appName'");
		return 1;
	}

	...
	return 0;
}
\end{verbatim*}
The function \fct{appInitEnv()} can be called in the other case, too,
of course.

Both functions will permanently setup the internally used structures,
but can be called any time the programmer wishes to re-evaluated the
name of the application. Latter opportunity has been implemented to provide a
{\em robust} architecture rather than force the programmer to {\em fake}
the name of the application.

Because there are reasons to ensure that \subsys{appName} has been initialized,
two additional functions are provided with a trailing \fct{Ex}:
\begin{enumerate}
\item \fct{int appInitEx(const char * const fnam)}, and
\item \fct{int appInitEnvEx(void)}.
\end{enumerate}
The useage and return values of them are identical to the other function,
but they do nothing, if \subsys{appName} has been initialized already.

\paragraphe{Productive functions} return information derived from
the internally cached name of the application:
\begin{enumerate}
\item \fct{char *appName(void)},
\item \fct{char *appPath(void)}, and
\item \fct{char *appFile(void)}.
\end{enumerate}
Note: Although the returned pointers are not modified by the \fct{const}
keyword, the user must not alter the returned string, otherwise 
\subsys{appName} will not work properly no longer! The keyword is omitted
to ease the useage of these functions only.

The function \fct{appName()} returns a pointer to the name of the
currently running application. Usually this is the filename of the
executable file.

The function \fct{appFile()} returns a pointer to the fully-qualified
filename of the executable file associated with the currently active
application.

The function \fct{appPath()} returns a pointer to the fully-qualified
path to the executable file.

Each invocation of these functions alter the buffer the value is stored in
and the returned pointer points to. That means that one cannot use two or
more values the same time, e.g. within the same function call.
For example the following code will fail:
\example{\subsys{appName}--functions cannot be used simultaneously}{%
\begin{verbatim*}
#include <appName.h>

main(void)
{	char *cfgFile;

	appInitEnv();

	cfgFile = EStrConcat(4, appPath(), "\\", appName(), ".CFG");
	...
}
\end{verbatim*}}
because the both calls to \fct{appPath()} and \fct{appName()} alter the
same internally used buffer so that its contents is not determineable
once the function \fct{EStrConcat()} accesses the passed in pointers.

To ease the implementation each of these three functions have an associated
function, which name ends in \fct{Ex}. It calls the function
\fct{appInitEnv()} prior retreiving the particular information, if and only
if \subsys{appName} has not been initialized already. That way the
implementation can make use of the retreival function with some sort of
ensurance that they return proper values.
