Appendix B Task Manager Functions

This appendix describes the programming interface for the DR-DOS Task Manager.

The Task Manager (TASKMGR) is accessed via the general-purpose INT2F Multiplex Interrupt, with TASKMGR being specified by the value 27H (39 decimal) in register AH. The hexadecimal value in register AL identifies the individual TASKMGR functions, which are summarized on the next page.

Table B-1
TaskMGR Function Calls

The Installation Check call must be the first one you make, because other TaskMGR functions can only be accessed if TaskMGR is resident.

The maximum number of tasks that are active currently can be between 1 and the value returned in AX. If the number of active tasks equals the value in AX, you should not attempt to create any more tasks.

The task index is the position of a task in the Task Manager menu, while a task’s ID is the position of the task in the internal task name table, TASK_NAMES. The IDs of all active tasks are stored in the TASK_IDS array. Note though, that most of the TaskMGR function calls use task indices, rather than IDs.

Task names stored in TASK_NAMES are up to 8 bytes each, in ASCIIZ format; they can be terminated by a NUL byte (00H) if they are less than 8 bytes and are not padded out by spaces.

The relationship between the tables is illustrated in the next figure, where WP is the task issuing the status call.

Each LIM page is 16 Kbytes.

Note that the allocation of EMS (LIM) memory is limited only by not returning a value larger than the maximum, and applications that make multiple allocation or status calls might therefore produce inconsistent results. However, most applications will leave all remaining EMS memory for other tasks.

To illustrate the type of inconsistent result that might arise from multiple allocation or status calls, assume there are 2 Mbytes of LIM memory, and the LIM limit is set to 1 Mbyte. A call to get the free LIM space will return 1Mb. However, if 1Mb is subsequently allocated, a call to get free LIM space will still return 1Mb.

See the description of the function Get EMS Memory Limit (02H) on the previous page.

A task manager is an application that replaces the TaskMGR popup menu system with a proprietary interface, such as a graphical user interface.

If an attempt to register a task manager returns the value 00H, then the call has succeeded, otherwise a task manager is already registered and the application should disable its task manager functionality.

If an attempt to unregister a task manager returns 01H, the call has been successful, otherwise it has failed and the task manager is still registered.

While a task manager is registered, the TaskMGR wakeup keys switch to the manager task instead of displaying the TaskMGR menus. Any attempt to reboot the computer via Ctrl+Alt+Del also switches to the manager task.

The task manager should be unregistered before it terminates.

Only a registered task manager should call this function. It disables or enables the use of the key combinations normally used to switch to the next, previous, or specified task.

This function can be used by the task manager to pass control to a specified task. Register DX returns the index of the last task that was active: note that the last active task is not necessarily the one that was last switched to via this call.

The parameter block corresponds to that of DOS function Load and Execute a Program (4BH), shown below. The Environment String field is reserved by TaskMGR, and should be set to 0000H for compatibility with future versions. Refer to the description of the Load and Execute a Program function in Chapter 4 for further details of the parameter block.

If the application should initialize, but then return to the Task Manager, a tick count should be given. Ticks occur at approximately 18 times per second. Enough time should be given for the application to load, which in most cases means 5 to 10 seconds. If a tick count of 0 is given, the application starts and continues to run until it is terminated, or until a switch request is made via the keyboard.

Use this function only to terminate tasks abnormally.

Before terminating a task, check for open files via the function Check Open Files (0CH), described later in this appendix.

Note that applications that use EMS or XMS memory should be terminated normally via the program’s exit function, not via this Delete Task function.

Note also that this function switches to the task to be deleted. Therefore, if you need to perform any actions prior to the switch occuring, do them before this function is called.

Normally, TaskMGR determines the name of a task dynamically. If this method fails for any reason, or a different task name should be used, it can be assigned via this function. Once a name has been assigned, it remains assigned until a NUL name is assigned, or the task terminates.

A table called TASK_TABLE contains a flag for each possible task. The flags signify whether, and in what manner, the task IDs are used:

00H Task ID unused, or task terminated
01H Task ID in use (i.e. TASK_NAMES entry valid)
81H Task ID in use, and task name fixed

This function translates a task index to a task ID. A task index may change if other tasks are deleted, whereas task IDs are global. If the task index is larger than the number of active tasks, a value of 0FFFFH is returned.

This function translates a task ID to a task index. A task index may change if other tasks are deleted, whereas task IDs are global. If the task ID is that of an inactive task, a value of 0FFFFH is returned.

This function returns the number of open files associated with a task.

Take care not to delete tasks while they have any files open, because if you do delete such tasks, data may be lost.

It is safe to delete a task at the root process, that is, a task at the COMMAND.COM prompt. You should, however, take care when you delete a task that is not at the root process, or that is shelled from within an application, because it may be using resources, such as EMS or XMS memory, that may be lost. Note that if you spawn a second command interpreter, via the Create Task (2707H) function, Check Task will return 0001H for this task.

The lead-in string consists of character/scan code pairs as used by the IBM ROM BIOS (interrupt 16H). No more than 15 characters may be specified. This sequence is fed into the application before each line of a text mode spreadsheet paste operation.

To get the current string, set CX=0.

To set the string, set CX to the new length of the string, and set DS:SI to point to the lead-in string.

This function can be used to prepare for pasting into an application that requires non-standard paste strings.

The string consists of character/scan code pairs as used by the IBM ROM BIOS (interrupt 16H). No more than 15 characters may be specified. This sequence is fed into the application before each number of a numeric mode spreadsheet paste operation.

To get the current string, set CX=0.

To set the string, set CX to the new length of the string, and set DS:SI to point to the lead-in string.

This function can be used to prepare for pasting into an application that requires non-standard paste strings.

The string consists of character/scan code pairs as used by the IBM ROM BIOS (interrupt 16H). No more than 15 characters may be specified. This sequence is fed into the application after each line of a spreadsheet paste operation (text or numeric). It usually moves the cursor down to the next cell.

This function can be used to prepare for pasting into an application that requires non-standard paste strings.

The decimal point is used during a numeric paste operation, as all non-digits other than signs and decimal points are stripped off numbers in this mode.

Normally, an ASCII period (.) or comma ( ,) is used here, depending on the language. The default used by TaskMGR will depend on the value of the COUNTRY= statement in the CONFIG.SYS file.

This function initiates an export operation, just as from the Task Manager menu.

This function initiates a paste operation, just as from the Task Manager menu.

The total amount of swap space is based on the MAXIMUM= value of the [MEMORY] section in the taskmgr.ini file. This value may be larger than the initial disk free space. The available swap space is based on:

Disk free space.

Free space inside the swap file.

Free space in EMS and XMS memory that was allocated to
TaskMGR when it installed.

You may want to stop the user from creating tasks when the available swap space falls below a minimum value.

This function permits an application to invoke the Task Manager menu without requiring user interaction, and thus performs the same purpose as the wakeup key on the keyboard (normally Ctrl+Esc).

The value returned in register AX specifies whether this version of TaskMGR supports the TaskMGR paste buffer functions: Query Paste Buffer Status (2716H), Paste Data Direct (2717H), and Copy Data Direct (2718H).

The number of bytes returned in CX takes in all the data from a previous copy operation, including a carriage return and line feed pair after each line of data.

The paste buffer generation number changes after each copy operation. An application can judge whether the contents of the paste buffer have changed by comparing the current generation number with the number returned by a previous query.

This function copies data from the paste buffer to the buffer specified by registers ES:DI.

The value returned in register AX specifies whether this version of TaskMGR supports the TaskMGR paste buffer functions: Query Paste Buffer Status (2716H), Paste Data Direct (2717H), and Copy Data Direct (2718H).

If the destination buffer is too small to take all the data from the paste buffer, register CX returns 0FFFFH and the paste operation does not take place. This situation may arise if another task copies further data to the paste buffer between the time an application queries the paste buffer status (function 2716H) and the time it pastes data.

This function copies data into the current paste buffer from a buffer specified by registers DS:SI. The data to be copied should be plain ASCII (that is, ASCII without any kind of formatting information), with carriage return and line feed pairs after each line. Avoid control codes (ASCII 0 through 31), because they may cause problems when the data is pasted.

The value returned in register AX specifies whether this version of TaskMGR supports the TaskMGR paste buffer functions: Query Paste Buffer Status (2716H), Paste Data Direct (2717H), and Copy Data Direct (2718H).

[Front] [Prev Chapter]