Specifications

2 COMMUNICATING WITH THE SYSTEM SCREEN
2-9
In case
DatUsedPathNamePtr
is null, the value of the string at
DatProcessNamePtr
(if any) is used instead:
failing that, the process name (as returned by
p_pname
) is used.
Initially, the name of the open file is part of the command line (see below). However, when this has to be
changed - either as a result of an
Open
or
Save as
command inside the application, or in response to a
Switchfile
request from the System Screen - a new buffer has to be used for this purpose. (The command
line buffer is sized to precisely the right length needed for the initial file.)
Typically, file-based applications will maintain a permanent buffer, of length
P_FNAMESIZE
, to store any
change in the name of the file open. Once the new name has been copied into this buffer, a call such as
hSetUpStatusNames
(described below) should be made, to adjust all Epoc statics as appropriate, including
DatUsedPathNamePtr
.
DatStatusNamePtr (0x3c)
The Epoc reserved static
DatStatusNamePtr
is used to determine which text string should be displayed as
the name of the application in any status window shown for that application.
If non-zero, this is assumed to point to a string giving the text to use, with the text being clipped at the
first dot encountered, and in any case after eight characters. The text is also converted into standard
capitalised form. Thus if
DatStatusNamePtr
points to
"DIARY.AGN"
, the text
Diary
will be displayed in
the status window.
The rules for what text to display when
DatStatusNamePtr
is null are the same as those employed when
DatUsedPathNamePtr
is null (see above).
DatLocked (0x3a)
When the user attempts to terminate an application using the "Quit application" command in the System
Screen, or to change the file currently open, by pressing
ENTER
on another entry in the file list for that
application, the System Screen checks the value of the Epoc reserved static
DatLocked
for that application.
If this is non-zero, a message
Application is busy
is displayed, and the user's request is refused.
Applications which enter a state in which they are unable to respond to such requests from the System
Screen should accordingly set
DatLocked
to
TRUE
. Good programming practice dictates that
DatLocked
be
set back to
FALSE
again as soon as possible afterwards.
The Series 3 command line
The command line communicates the following information to a Series 3 application about to start:
•
the
public name
of the application
•
the
default extension
for files used, if any
•
any
alias information
specified in an alias file
•
the full path name of the file to open, if any
•
whether this file should be opened or created anew
•
exceptionally, whether the application is to connect to the Window Server
in background
.
When a program starts, its command line is placed in an allocated cell within the heap of the application,
with the address of this cell being written to the Epoc reserved static
DatCommandPtr
. See the section on
p_execc
in the
Plib Reference
manual for some general information about
DatCommandPtr
.
The command line for
any
Epoc program always starts with a zero-terminated string given the full path
name of the process being run. The byte after this gives the length of any following data. Ordinarily,
when referring to "the command line", it is this latter data that is in mind.
For example, suppose the user presses
TAB
inside the
Prog
file list in the System Screen, navigates using
the file selector to
loc::m:\dat\data.dbf
, and then presses
ENTER
. The full command line passed to the
application thereby chosen (
Word
) is as follows:
ROM::WORD.APP<0><29>OProgram<0>.OPL OROPO<0>LOC::M:\DAT\DATA.DBF<0>