|
www.riscos.com Technical Support: |
The DDEUtils module performs three functions. These functions have been combined in one module for convenience:
These functions are described individually in the rest of the chapter.
R0 = Pointer to 0 terminated directory name, or R0 = 0
All registers preserved
None
This sets a directory name to be prefixed to all relative filenames used by this task. If R0 = 0 this removes any previously set prefix. If you use this SWI within a program to set a directory prefix you should call it again with R0 = 0 immediately before exiting your program.
This sets the specified directory name to be prefixed to all relative filenames used by this task. *Prefix with no arguments removes any previously set prefix.
The system variable <Prefix$Dir> is set to the prefix used for the currently executing task. This can be set by you, and this will have the same effect as *Prefix.
These SWIs are used to pass long command lines between programs. Typically they will be called by library veneers. For example, the C run-time library initialisation calls DDEUtils_GetCLSize and DDEUtils_GetCL to fetch any long command lines set up by a calling program and calls DDEUtils_SetCLSize and DDEUtils_SetCL in the system library call.
R0 = Length of command line buffer required
R0 destroyed
None
This SWI should be called by a program when it has a long command line which it wishes to pass to another program. The SWI should be called with the length of the command line in R0. A buffer of suitable size is allocated in the RMA.
R0 = Pointer to zero terminated command line tail
All registers preserved
Possible errors are
CLI buffer not set
This error is generated if the program has not previously called DDEUtils_SetCLSize to establish the size of the command line.
This should be called after calling DDEUtils_SetCLSize to set the size of the command line buffer. R0 contains a pointer to the command tail (i.e. the command line without the name of the program to be run).
don't care
R0 = Size of command line
None
This is called by a program which may have been run with a long command line. The size of the command line is returned in R0. 0 is returned if no command line has been set.
R0 = Pointer to buffer to receive command line
All registers preserved
None
This SWI is called to fetch the command line. The command line is copied into the buffer pointed to by R0.
R0 = task handle of caller
All registers preserved
Possible errors are:
Another task is registered for throwback Throwback not available outside the desktop
This registers a task which is capable of dealing with throwback messages, with the throwback module. The task handle will be used in passing Wimp messages to the caller, when they are generated by an application.
R0 = task handle of caller
All registers preserved
Possible errors are:
Task not registered for throwback Throwback not available outside the desktop
This call should be made when the Wimp task which registered itself for throwback is about to exit.
don't care
All registers preserved
Possible errors are:
No task registered for throwback Throwback not available outside the desktop
When a non-desktop tool detects errors in the source(s) it is processing, and throwback is enabled, the tool should make this SWI to start a throwback session.
R0 = reason code
R2-R5 = depends on reason code (see below)
If R0 = 0 (Throwback_ReasonProcessing)
R2 = pointer to nul-terminated full pathname of file being processed
If R0 = 1 (Throwback_ReasonErrorDetails)
R2 = pointer to nul-terminated full pathname of file being processed
R3 = line number of error
R4 = severity of error
= 0 for warning
= 1 for error
= 2 for serious error
R5 = pointer to nul-terminated description of error
If R0 = 2 (Throwback_ReasonInfoDetails)
R2 = pointer to nul-terminated full pathname of file being processed
R3 = line number to which 'informational' message refers
R4 = must be 0
R5 = pointer to nul-terminated 'informational' message
R0-R4 preserved
Possible errors are:
No task registered for throwback Throwback not available outside the desktop
This SWI should be called with reason
once, when the first error in processing a file was found. Then it should be called once for each error found, with the reason
or for each informational line that needs displaying with the reason:
All registers preserved
Possible errors are:
No task registered for throwback Throwback not available outside the desktop
These messages are sent by the DDEUtils module to an editor that has registered itself for throwback using the SWI DDEUtils_ThrowbackRegister. You only need to know about them if you want to write your own editor.
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_ThrowbackStart (&42580) |
The translator then passes messages giving full information on each error, or each 'informational' message, to the editor.
A complete series of messages sent by the translator to the editor is described by the grammar below. Items in <..> are individual Wimp messages, identified by their reason code.
ErrorDialogue ::= <DDEUtils_ThrowbackStart>
ErrorsWhileProcessing{ErrorsWhileProcessing}
<DDEUtils_ThrowbackEnd>
ErrorsWhileProcessing ::= <DDEUtils_ProcessingFile>
ErrorFoundIn{ErrorFoundIn}
ErrorFoundIn ::= <DDEUtils_ErrorIn>
<DDEUtils_ErrorDetails>
InfoDialogue ::= <DDEUtils_ThrowbackStart>
InfoDetails{InfoDetails}
<DDEUtils_ThrowbackEnd>
InfoDetails ::= <DDEUtils_InfoforFile>
<DDEUtils_InfoDetails>
The format of such Wimp messages is as follows:
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_ProcessingFile (&42581) |
| +20 | Nul-terminated filename |
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_ErrorsIn (&42582) |
| +20 | Nul-terminated filename |
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_ErrorDetails (&42583) |
| +20 | Line number |
| +28 | Severity
= 0 for warning = 1 for error = 2 for serious error |
| +32 | Nul-terminated description |
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_ThrowbackEnd (&42584) |
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_InfoforFile (&42585) |
| +20 | Nul-terminated filename |
| Byte Offset | Contents |
|---|---|
| +16 | DDEUtils_InfoDetails (&42586) |
| +20 | Line number |
| +28 | must be 0 |
| +32 | Nul-terminated 'informational' message |