[Front] [Prev Chapter]

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

AL Hex

Calls:

00

Installation Check

01

TaskMGR Status

02

Get EMS Memory Limit

03

Set EMS Memory Limit

04

Register Task Manager

05

Direct Switching

06

Switch Tasks

07

Create Task

08

Delete Task

09

Name Task

0A

Convert Task Index

0B

Convert Task ID

0C

Check Open Files

0D

Check Task

0E

Get/Set Text Paste Lead-in

0F

Get/Set Numeric Paste Lead-in

10

Get/Set Enter String

11

Get/Set Decimal Point

12

Export Task Data

13

Import Task Data

14

Get Swap Space

15

Switch to Task Manager

16

Query Paste Buffer Status

17

Paste Data Direct

18

Copy Data Direct

Installation Check (2700H)

Check Whether TaskMGR is Resident

Entry Parameters:

Register AL:00H
Returned Values:
RegisterAL:000H TaskMGR not resident
0FFH TaskMGR resident

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

TaskMGR Status (2701H)

Read the Status of TaskMGR
Entry Parameters:
Register AL:01H
Returned Values:
Register AX:Maximum number of tasks supported
BX: Foreground task index inTASK_IDS
CX:Number of tasks active currently
DX:TaskMGR version (0001H forDR DOS 6.0)
ES:SIPointer to TASK_IDS
ES:DIPointer to TASK_NAMES

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.

Undisplayed Graphic

Get EMS Memory Limit (2702H)

Get the EMS Memory Limit Per Task

Entry Parameters:

Register AL:

02H

Returned Values:

DX:

Maximum number of free LIM pagesto return from LIM function 2(AH=42H) to applications

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.

Set EMS Memory Limit (2703H)

Set the EMS Memory Limit Per Task

Entry Parameters:

Register AL:

03H

DX:

Maximum number of free LIM pagesto return from LIM function 2(AH=42H) to applications

Returned Values:

DX:

New maximum number of LIM pages

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

Register Task Manager (2704H)

Register or Unregister a Task Manager

Entry Parameters:
RegisterAL:04H
DL:00H Unregister task manager
01H Register task manager
Returned Values:
RegisterDL:00H Task manager registered
01H Task manager unregistered

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.

Direct Switching (2705H)

Enable or Disable Direct Switching

Entry Parameters:

Register AL:

05H

DL:

00H Disable direct switching01H Enable direct switching

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.

Switch Tasks (2706H)

Switch to a Specific Task

Entry Parameters:

Register AL:

06H

DX:

Task index to switch to

Returned Values:

Register DX:

Task index of last active 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.

Create Task (2707H)

Create a New Task

Entry Parameters:
Register AL:07H
DS:DXPointer to ASCIIZ name of .EXE or .COM file
ES:BXPointer to parameter block
CX:Tick count for return to task manager (0=none)
Returned Values:
Register DX:Task index of the new task or 0FFFFH if the task has been terminated

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.

Undisplayed Graphic

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.

Delete Task (2708H)

Delete a Task

Entry Parameters:

Register AL:DX:

08HIndex of task to delete

Returned Values:

Register DX:0FFFFH (active taskdeleted)

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.

Name Task (2709H)

Name a Task

Entry Parameters:
RegisterAL:09H
DX:Task index
DS:SIPointer to 8-byte name (all 0’s to remove name)
Returned values:
RegisterES:DIPointer to name in TASK_NAMES
BX:Task ID
AL:TASK_TABLE[bx]

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

Convert Task Index (270AH)

Convert a Task Index to a Task ID

Entry Parameters:

Register AL:DX:

0AHTask index

Returned Values:

Register DX:

Task IDor 0FFFFH if the task index is invalid

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.

Convert Task ID (270BH)

Convert a Task ID to a Task Index

Entry Parameters:

Register AL:DX:

0BHTask ID

Returned Values:

Register DX:Task index or 0FFFFH if the task is not active

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.

Check Open Files (270CH)

Get the Number of Open Files

Entry Parameters:

Register AL:DX:

0CHTask index

Returned Values:

Register AX:

Number of open files

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.

Check Task (270DH)

Check if a Task is at the Root Process

Entry Parameters:
RegisterAL:0DH
DX:Task index
Returned Values:
RegisterDX:0000H if primary command interpreter is running
0001H if not at primary COMMAND.COM

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.

Get/Set Text Paste Lead-in (270EH)

Get/Set Lead-in Characters for Text Paste String

Entry Parameters:
RegisterAL:0EH
DS:SI:Pointer to text paste lead-in string
CX:New length of string, or 0 to get address of current lead-in string
Returned Values:
RegisterES:DI:Pointer to current lead-in string

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.

Get/Set Numeric Paste Lead-in (270FH)

Get/Set Lead-in Characters for Numeric Paste String

Entry Parameters:
Register AL:0FH
DS:SIPointer to numeric paste lead-in string
CX:New length of string, or 0 to get the address of the current lead-in string
Returned Values:
Register ES:DIPointer to current lead-in string

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.

Get/Set Enter String (2710H)

Get/Set the Enter String for a Paste Operation

Entry Parameters:
RegisterAL:10H
DS:SIPointer to enter string
CX:New length of string, or 0 to get the address of the current enter string
Returned Values:
RegisterES:DIPointer to current enter string

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.

Get/Set Decimal Point (2711H)

Get/Set Numeric Paste Decimal Point

Entry Parameters:
Register AL:11H
DX:ASCII code for the separator,or 0FFFFH to get the current separator
Returned Values:
RegisterDL:Current separator

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.

Export Task Data (2712H)

Export Data From a Task

Entry Parameters:

Register AL:DX:

12HTask index

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

Import Task Data (2713H)

Import Data into a Task

Entry Parameters:
Register AL:13H
DX:Task index
CX:Paste mode:
0= alphanumeric
1=numeric
2=text

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

Get Swap Space (2714H)

Get Swap Space Information

Entry Parameters:
Register AL:14H
Returned Values:
RegisterDX:Available swap space in 1 Kb blocksTotal swap space in 1 Kb blocks
CX:Total swap space in 1 Kb blocks

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.

Switch to Task Manager (2715H)

Switch to the Task Manager

Entry Parameters:

Register AL:

15H

Returned Values:

Menu pops up or switch to task manager.Returns only after selecting again the task that called this function.

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).

Query Paste Buffer Status (2716H)

Get the Status of the Paste Buffer

Entry Parameters:
RegisterAL:16H
Returned Values:
RegisterAX:0000H - Functions 2716H, 2717H and2718H are supported
CX:Number of bytes in the paste buffer
DX:Paste buffer’s current generation number

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.

Paste Data Direct (2717H)

Copy Data from the Paste Buffer

Entry Parameters:
Register AL:17H
ES:DIPointer to destination buffer
CX:Size of the destination buffer in bytes
Returned Values:
RegisterAX:0000H - Functions 2716H, 2717H,and 2718H are supported
CX:Number of bytes copied
DX:0FFFFH - Destination buffer is too small Paste buffer’s current generation number

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.

Copy Data Direct (2718H)

Copy Data3to the Paste Buffer

Entry Parameters:
Register AL:18H
DS:SIPointer to source buffer
CX:Size of the source buffer in bytes
Returned Values:
Register AX:0000H - Functions 2716H, 2717H,and 2718H are supported
CX: Number of bytes copied
DX:Paste buffer’s current generation number

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]


info@caldera.com
Copyright © 1993, 1997 Caldera, Inc All rights reserved.