CD Shell Development: Macro Services

Macro Services

Macro Services List

Modules are able to present a list of macro services to the core. The list is a linear array made up of individual macro service definitions, each of which define a single macro supported by the module. These macros are then uses as a type of active memory, allowing users to store and retrieve strings from them, but also allowing the module to perform actions as the macro is accessed. (for an example of this, see the $MD5 macro)

There are a couple notible differences in the macro service definition when compared to the ones for commands and functions. The definitions in the macro services list need not be in alphabetical order, and the macro name can specified by a far pointer rather than a near one. These differences are designed to make it easier for a module to dynamically add macros to the list at runtime, as is done when user variables are created.

A 2-byte (16-bit) zero value terminates the list.

Macro Service Definition

Offset	Size	Description
0	2 bytes	service routine pointer
2	2 bytes	flags
4	2 bytes	name pointer
6	2 bytes	name segment
8	2 bytes	identifier

Service Routine Pointer

This is the offset into the module segment of the handler routine that processes this macro.

Flags

This field is a set of flags that determine how the macro is handled. The bitfields are defined as follows:

Bit	Field	Description
[0]	Ignore	pretend this macro is not in the list
[1]	Hide	don't display info about this macro
[2]	Readable	this macro is capable of being read from
[3]	Writable	this macro is capable of being written to
[4]	Case-Sensitive	this macro's name is case-sensitive
[15:5]	Reserved	these flags are reserved for future use

Name Pointer

This is the offset into the name segment (see below) of the macro name, a null-terminated string.

Name Segment

This is the segment that the macro name resides in. Note that this does not have to be the module segment, but if this value is zero then the module segment is assumed.

Identifier

This is a unique 16-bit value used to identify the macro to the service routine. A single service routine can therefore handle multiple macros if it uses this field to distinguish them.

Service Routine Environment

A macro that is readable and writable will require a service routine capable of handling both operations. The environment will be different depending upon which action is being performed, as described below. Thus the service routine should first test the ax register to determine the read/write access mode, and then assume the corresponding context.

Call Context (read operation)

The macro service routine is called by the core with the following context:

Register	Contents
ax	access mode (Macro.Read)
bx	macro id
cs	module segment
ds	module segment
es	module segment
gs	Core Services Table segment
ss:sp	global stack, far return pointer on top

Note: Macro.Read is defined in cdshell.inc.

Call Context (write operation)

The macro service routine is called by the core with the following context:

Register	Contents
ax	access mode (Macro.Write)
bx	macro id
si	offset of macro contents string
cs	module segment
ds	segment of macro contents string
es	module segment
gs	Core Services Table segment
ss:sp	global stack, far return pointer on top

Note: Macro.Write is defined in cdshell.inc.

Return Context (read operation)

The core expects the following context upon return from the service routine:

Register/Flag	Contents
carry flag	set if read operation failed
si	offset of macro contents string (string treated as read-only)
ds	segment of macro contents string
ss:sp	global stack, far return pointer popped

Return Context (write operation)

The core expects the following context upon return from the service routine:

Register/Flag	Contents
carry flag	set if write operation failed
ss:sp	global stack, far return pointer popped

- Previous -

- Next -