home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
VSCPPv4.zip
/
VACPP
/
IBMCPP
/
HELP
/
CP3.INF
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1995-03-10
|
260KB
|
9,073 lines
ΓòÉΓòÉΓòÉ 1. Memory Management ΓòÉΓòÉΓòÉ
This chapter describes the memory management features and functions of the OS/2
operating system. The key features of OS/2 memory management are paged virtual
memory and a 32-bit linear (flat) address space that is mapped through page
tables to physical memory. An OS/2 application can allocate memory for its own
use or to be shared with other applications.
The following topics are related to the information in this chapter:
o Exception Handling
o Program Execution and Control
o Semaphores
o Queues
ΓòÉΓòÉΓòÉ 1.1. About Memory Management ΓòÉΓòÉΓòÉ
The OS/2 operating system offers developers a 32-bit, linear (flat) memory
address space. The OS/2 operating system uses a paged memory structure. The
operating system allocates, protects, and manipulates memory in terms of pages.
ΓòÉΓòÉΓòÉ 1.1.1. Process Address Space ΓòÉΓòÉΓòÉ
The OS/2 memory allocation functions return a 32-bit pointer to the allocated
memory object. While a 32-bit pointer is sufficient to address the entire 4
gigabyte global address space, applications can access only the first 512MB of
linear memory, called the process address space. Of this 512MB process address
space, a minimum of 64MB is reserved for shared memory regions, leaving 448MB.
Of this 448MB, some will be used by the application itself and a small amount
will be taken by operating system overhead. The remainder is available for
allocation. The amount of memory that can actually be committed and used is, of
course, determined by the physical memory and hard disk space available on the
machine.
Keep in mind that the amount of memory that can be committed for actual use is
limited by the amount of physical memory and free hard disk space that is
available on the computer on which the application is executing.
ΓòÉΓòÉΓòÉ 1.1.2. Memory Objects ΓòÉΓòÉΓòÉ
Applications allocate and manipulate memory in terms of memory objects. A
memory object consists of one or more pages of memory. An OS/2 application can
allocate any number of memory objects, within the following limits:
o the physical memory in the system
o the free hard disk space on the hard disk containing the swap file
o the 512MB process address space limit (see Process Address Space).
When requesting memory, the size of the memory object is rounded up to the
next higher multiple of 4KB. An application can suballocate a memory object
into memory blocks whose size can range from 1 byte to the size of the memory
object.
Memory objects have the following characteristics:
o They are not relocatable.
o They are allocated in units of 4KB. One 4KB unit is called a page.
o They can be larger than 64KB in size.
ΓòÉΓòÉΓòÉ 1.1.3. Memory Pages ΓòÉΓòÉΓòÉ
The operating system allocates and commits memory objects in pages. A memory
page is a 4KB (4096 bytes) piece of memory. Memory access protection is also
done on a page-basis, rather than the segment-based protection used in previous
versions of the operating system.
A page range is a linearly contiguous group of pages within a memory object. A
page range can be:
o the entire memory object,
o part of the memory object, or
o a single page within a memory object
If an application requests 512 bytes of memory, it will receive a 32-bit
pointer to a 4KB page. All 4096 bytes are available to the application, even
though the request specified only 512 bytes. If an application requests 62000
bytes, it will receive a pointer to a 65536-byte (64KB, 16-page) object.
Again, all 65536 bytes are available for use.
Each page in the virtual address space of the process is either free
(unallocated), private (available only to the process that allocated it), or
shared (memory that is shared between processes).
Each page within a memory object can be in one of two states, either
uncommitted (that is, the linear address range has been reserved, but is not
yet backed by physical storage) or committed (physical storage has been
allotted for the logical address range).
Access to a committed page is controlled by the page's access protection
attribute. These protection attributes are read access, write access, execute
access (on the 80386, this is the same as read access), and guard page access.
An uncommitted page is not accessible.
ΓòÉΓòÉΓòÉ 1.1.4. Memory Overcommitment and Swapping ΓòÉΓòÉΓòÉ
Memory overcommitment occurs when applications allocate and commit more memory
than is actually available in the computer. The operating system handles memory
overcommitment by copying memory to the system swap file, SWAPPER.DAT, on the
hard disk then reusing the memory for another allocation. The operating system
copies as many pages of memory as are necessary to make room for the new
allocation. The swapped memory can be retrieved the next time it is accessed;
at that time, some other memory might be written to the swap file.
The operating system selects the memory to swap based on when it was last used.
The page that is least-recently-used, that is, the page that has gone the
longest since its last access, is the page chosen to swap to disk.
Swapping is transparent to an application, although excessive swapping can
cause an application to run slowly.
Through swapping, the OS/2 operating system enables applications to allocate
more memory than actually exists in the computer, bounded only by the amount of
free space on the hard disk that contains the swap file.
ΓòÉΓòÉΓòÉ 1.1.5. User Configuration of Memory Swapping ΓòÉΓòÉΓòÉ
Although an application cannot control swapping, the user can specify whether
the system can swap memory by including the MEMMAN command in the CONFIG.SYS
file.
If the MEMMAN command specifies SWAP, the operating system writes selected
memory pages to the SWAPPER.DAT file whenever insufficient physical memory
exists to satisfy an allocation request. This is the default choice. If the
MEMMAN command specifies NOSWAP, the operating system does not swap memory.
Note: Be aware that disabling swapping will severely limit the number of
applications that the user will be able to run concurrently; if there is
not enough physical memory present, the operating system might not even
boot.
The exact amount of memory available to an application depends on the amount
of physical memory in the machine and the amount of free disk space on the
partition that contains the SWAPPER.DAT file. The location of the SWAPPER.DAT
file can be specified by including the SWAPPATH command in the CONFIG.SYS
file. With the SWAPPATH command, one can specify the location of the
SWAPPER.DAT file, the amount of free disk space to reserve in the partition
which will contain SWAPPER.DAT, and the initial size of SWAPPER.DAT. The
operating system adjusts the size of SWAPPER.DAT as necessary, leaving other
files on the drive and the requested free space untouched.
ΓòÉΓòÉΓòÉ 1.1.6. Memory Allocation and Commitment ΓòÉΓòÉΓòÉ
When an application asks the operating system to allocate memory, a linear
address range is reserved. The range is not backed by physical memory until the
memory is committed. Commitment assigns physical memory to the linear address
range.
A memory object that is allocated, but not committed is called a sparse memory
object. A sparse memory object must be committed before it can be used. An
attempt to read from or write to uncommitted memory will cause an access
violation.
An application can ask the operating system to commit the memory at the same
time it is allocated, thus making it immediately usable, or the memory can be
committed at a later time. If the application commits the memory at the same
time the memory is allocated, the entire memory object is committed. If the
application commits the memory at a later time, it can commit the entire sparse
memory object or only commit a portion of it.
When multiple pages are committed at the same time (a page range), the pages
will have sequential linear addresses.
Managing Memory Allocation and Commitment
The recommended way to manage memory is to make a large memory allocation early
in program execution, then to commit or suballocate memory as the need occurs.
The initial allocation should be for as much space as you expect to use during
program execution. Allocation without commitment does not actually use any
physical memory, so there is no waste involved in allocating several megabytes.
After the memory object is allocated, the application uses one of two ways to
manage the memory object:
o Commit and decommit the memory as it is required
o Set up the memory object as a heap and suballocate memory from the heap.
Committing and decommitting memory gives the application more control over the
process, but the application will have to keep track of which pages are
committed and which pages are not. When suballocating memory from a heap, the
application can have the operating system track commitment and decommitment of
physical memory pages, so the application does not have to. If you want
DosSubAllocMem to manage the commitment of the pages spanned by the heap, all
of the pages spanned by the memory object must be uncommitted initially.
Remember, no matter how much memory is originally allocated, the amount that
an application will ultimately be able to commit and use is limited by the
amount of physical memory and free disk space available on the machine.
Applications are not limited to a single large allocation of memory-other
memory allocations can be made as necessary during execution-but large
allocations and small commitments or suballocations are the most efficient way
to manage memory.
ΓòÉΓòÉΓòÉ 1.1.7. Memory Resizing and Reallocation ΓòÉΓòÉΓòÉ
In earlier versions of the operating system, an application could increase or
decrease the size of an allocated memory segment by reallocating the segment.
Memory objects cannot be resized. Instead, an application should allocate a
sparse memory object of whatever size might be necessary, then commit or
decommit portions of the object.
If the amount of memory required cannot be determined at the time the memory is
allocated, the application should allocate a sparse memory object large enough
to meet the largest memory requirement. The application can then change the
amount of committed memory as necessary.
For example, if you anticipate your application will use around 512KB of memory
for most purposes, but might use 5MB under certain circumstances, you might
take the following steps:
o During program initialization, use DosAllocMem to allocate 5MB.
o Commit the first 512KB (or some part of it) using DosSetMem.
o Proceed with normal processing.
o If extra memory is required occasionally, commit it and decommit it using
DosSetMem.
o When the situation arises that the application requires the full 5MB,
commit it at that time, using DosSetMem, then decommit it after you are
finished with it, also using DosSetMem.
o When the application is finished with the memory, use DosFreeMem to
release the memory back to the system.
ΓòÉΓòÉΓòÉ 1.1.8. Memory Protection ΓòÉΓòÉΓòÉ
When an application allocates a memory object, it can specify the type of
access to allow to the object. Memory access protection provides a program with
control over the type of access that its threads have to a page of memory.
Access protection can only be defined for committed pages of memory and is
initially set at the time the memory is committed. Different pages within the
same memory object can have different access attributes and access attributes
can be changed on a page-by-page basis at any time.
An application can request any combination of the following access protection
attributes:
Memory Access Protection Attributes
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAccess ΓöéDefined Constant ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRead Access ΓöéPAG_READ ΓöéThe object can be Γöé
Γöé Γöé Γöéread from, but not Γöé
Γöé Γöé Γöéwritten to. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWrite Access ΓöéPAG_WRITE ΓöéThe object can be Γöé
Γöé Γöé Γöéwritten to. On the Γöé
Γöé Γöé Γöé80386 Γöé
Γöé Γöé Γöémicroprocessor, Γöé
Γöé Γöé Γöéwrite access impliesΓöé
Γöé Γöé Γöéboth read and Γöé
Γöé Γöé Γöéexecute access. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéExecute Access ΓöéPAG_EXECUTE ΓöéThis is equivalent Γöé
Γöé Γöé Γöéto read access on Γöé
Γöé Γöé Γöéthe 80386. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGuard Page Access ΓöéPAG_GUARD ΓöéCauses a Γöé
Γöé Γöé Γöéguard-page-entered Γöé
Γöé Γöé Γöéexception to be Γöé
Γöé Γöé Γöéraised in a process Γöé
Γöé Γöé Γöéthat attempts to Γöé
Γöé Γöé Γöéaccess the memory. Γöé
Γöé Γöé ΓöéThis exception can Γöé
Γöé Γöé Γöébe ignored or Γöé
Γöé Γöé Γöéhandled by the Γöé
Γöé Γöé Γöéapplication's Γöé
Γöé Γöé Γöéexception handler, Γöé
Γöé Γöé Γöéif one is Γöé
Γöé Γöé Γöéregistered. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The guard page attribute is intended to provide automatic stack growth and
stack limit checking. An application can also use it in other data structures,
such as arrays. For example, if an application is using an array of 4096 bytes
(one page), the application can allocate and commit two pages, one with read
and write access and one designated as a guard page. If the application tries
to write past the end of the array a page guard exception will be generated.
Any reference-read, write, or execute-to a guard page causes an access
violation (page fault) to be generated. This fault causes a Guard Page Entered
exception to occur for the thread that referred to the guard page. The
exception can be handled by the exception handler of the process, if one is
registered. If the process does not have an exception handler registered, the
operating system's default exception handler will handle the exception. The
default action by the system exception handler is to convert the page from a
guard page to a committed page, then try to mark the next page in memory as a
guard page. If the system is not successful in marking the next page as a guard
page, an Unable-To-Grow-Stack exception occurs. The thread is allowed to
continue execution, but must be aware that it has at most 4KB of stack
remaining.
ΓòÉΓòÉΓòÉ 1.1.9. Obtaining Information about a Page Range ΓòÉΓòÉΓòÉ
DosQueryMem is used to obtain information about a range of pages within the
virtual address space of the current process.
Each page in the virtual address space of a process is either free, private, or
shared.
Each page within a memory object can be in one of two states, either committed
or uncommitted.
A committed page has its access controlled by an access protection attribute.
These protection attributes are read protection (PAG_READ), write protection
(PAG_WRITE), execute protection (PAG_EXECUTE), and guard page protection
(PAG_GUARD).
ΓòÉΓòÉΓòÉ 1.1.10. Protection Violations ΓòÉΓòÉΓòÉ
The operating system fully utilizes the memory protection capabilities of the
80386 microprocessor. The operating system grants an application access to a
memory object only if the object has been explicitly allocated by the
application or made available for use by the application.
If an application attempts to access memory that it is not assigned, the system
interrupts the application and executes the exception handling routine for
protection violations. Protection violations can be handled by the application
(in its own exception handling routines) or by the operating system. If the
protection violation is handled by the operating system, the system exception
handling routine determines the cause of the exception, displays an error
message, and then terminates the application.
It is usually not possible for an application to recover from a protection
violation. Therefore, programmers should ensure that all pointers are valid.
Because protection violations commonly occur during application debugging, each
message displayed for a protection violation includes the contents of the
registers when the violation occurred. If the violation occurred as a result of
passing an invalid pointer to a memory function, an error code is returned by
the memory function.
In earlier versions of the operating system, protection violations could be
used to find bugs when an application accessed memory that was not allocated to
the application. This approach will no longer work because memory objects can
be larger than the size requested by the application because the memory objects
are allocated on 4KB page boundaries. For example, a pointer to the 513th byte
of a 512 byte memory object is valid and does not cause a protection violation.
This means that programmers cannot always rely on protection violations to spot
memory addressing errors.
ΓòÉΓòÉΓòÉ 1.1.11. Memory Suballocation and Using Heaps ΓòÉΓòÉΓòÉ
There are times when a process requires only small amounts of memory rather
than an entire memory object. It would be wasteful to allocate an entire page
of memory when only a few bytes are necessary, so a mechanism is provided for
applications to allocate a large block of memory and then suballocate portions
of the memory as necessary to fulfill small requests from an application. This
is done by creating a heap.
A heap is a region of storage within a memory object from which an application
can allocate blocks of memory. A memory block is a piece of memory within a
heap. The size of the memory block is rounded up to the next higher multiple of
8 bytes.
Because the operating system allocates a 4KB page for each memory allocation,
using a heap to suballocate amounts of memory smaller than 4KB is more
efficient than using DosAllocMem.
When an application creates a heap, it can have the operating system track the
committing and decommitting of memory within the heap. When the application
commits and decommits memory itself, it has to keep track of the access state
of each page as they are accessed.
Applications use DosSubSetMem to initialize a memory object for suballocation,
then use DosSubAllocMem and DosSubFreeMem to allocate and free the memory.
Memory is still committed in pages when an application uses suballocation. If
the application suballocates 512 bytes, 4096 bytes will be committed. Accessing
the 513th byte will not cause a protection violation, but you could be
accessing memory that was suballocated by another thread in the process.
ΓòÉΓòÉΓòÉ 1.1.12. Shared Memory ΓòÉΓòÉΓòÉ
Shared memory is memory that two or more applications can read from and write
to. Shared memory is prepared in such a way that any application can receive a
pointer to the memory and access the data. Applications must explicitly request
access to shared memory; the shared memory is protected from applications that
are not granted access.
There are two kinds of shared memory: named and unnamed. For named shared
memory, any application that knows the name of the shared memory can access it.
For unnamed shared memory, a pointer to the shared memory must be passed from
the process that created the shared memory to the process being given access.
Access can be granted to any application; it is not necessary that the process
being granted access be related (parent-child) to the application that created
the shared memory.
Since memory sharing is done by sharing linear addresses, the linear address
range of the shared memory object is reserved in all process address spaces.
There are two basic methods of managing shared memory:
o In one method, two or more applications share the same memory at the same
time. These applications read from and write to the memory object,
usually controlling access to the memory by using a semaphore.
o In the other method of managing shared memory, one application prepares
data in memory, then passes that memory to another application for
further processing. The first application releases the memory after
passing it along, so that only one application accesses the memory at a
time.
ΓòÉΓòÉΓòÉ 1.1.13. Thread Local Memory ΓòÉΓòÉΓòÉ
Thread local memory is a 128-byte region of thread-specific memory that the
operating system assigns to a thread when the thread is created. Thread local
memory for each thread is always at the same virtual address, but each thread's
local memory region is backed by different physical memory, so the memory is
specific to each thread. This memory region is divided into 32 DWORDS (4 bytes
per DWORD), and is normally used to store a small number of pointers.
A thread can allocate thread local memory by calling DosAllocThreadLocalMemory.
Thread local memory is freed by calling DosFreeThreadLocalMemory.
Note that thread local memory should be used sparingly. You should not use the
entire 128 byte region.
ΓòÉΓòÉΓòÉ 1.2. Using Memory Management ΓòÉΓòÉΓòÉ
This section describes how to use the OS/2 memory management functions and
configuration commands to control the use of memory for OS/2 applications.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 1.2.1. Allocating Private Memory ΓòÉΓòÉΓòÉ
An application can allocate regions of storage within the virtual address space
of the process. Such an allocated region is called a memory object.
DosAllocMem is used to allocate a memory object. You specify a variable to
receive the pointer that will address the new object, the amount of memory
needed, and the allocation attributes and access protection attributes of the
new memory object. When choosing the size of the memory object to allocate,
remember that the maximum size of the memory object is defined when it is
allocated, and memory objects cannot be resized.
When applications call DosAllocMem, the operating system reserves a range of
private pages large enough to fulfill the specified allocation request from the
private virtual address space of the subject process.
DosAllocMem will reserve this linear space and return zero if the allocation
was successful. If it was unsuccessful, DosAllocMem will return an error code.
An application should always test the return value before attempting to use the
memory.
The following code fragment requests an allocation of 512 bytes. Remember that
4096 bytes will actually be allocated for this request:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
PBYTE pb;
APIRET rc;
rc = DosAllocMem((PVOID *) &pb, 512, fALLOC);
/* pb receives the base address of the 4KB memory object */
if (!rc) { /* If the allocation was successful, rc == 0 */
*pb = 3000; /* Use the allocated memory */
}
In this example, DosAllocMem returns a 32-bit pointer to a 4096 byte committed
memory object and allows the application to write to and read from the memory.
This pointer is valid only for the 4096 bytes allocated by the system. An
attempt to use the pointer outside the allocated memory will cause a protection
violation.
ΓòÉΓòÉΓòÉ 1.2.2. Committing and Decommitting Page Ranges ΓòÉΓòÉΓòÉ
If an application allocates a sparse memory object, no physical memory location
is committed for the object. Memory in a sparse object must be committed before
it can be used. DosSetMem is used to commit or decommit a range of previously
allocated pages in a private or shared memory object. Applications can make
specific address ranges within a memory object valid or invalid. Commitment and
decommitment always take place in multiples of one or more pages.
Applications can also use DosSetMem to change the access protection attributes
of a range of pages within a memory object.
The following code fragment requests allocation of 2MB of uncommitted memory
and then commits 4096 bytes of the memory:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
APIRET rc;
PBYTE pb;
/* Allocate 16KB object */
rc = DosAllocMem((PVOID *) &pb, 2097152, PAG_READ | PAG_WRITE);
/* Commit 4KB */
rc = DosSetMem(pb, 4096, PAG_COMMIT | PAG_DEFAULT);
An application can also allocate a large committed object and then decommit
portions of it as they are no longer needed. Decommitment, like commitment, is
done on page boundaries; an application can decommit no less than a 4096 byte
page.
The following code fragment allocates 16384 bytes of committed memory and then
decommits the first 4096 bytes of the memory:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
APIRET rc;
PBYTE pb;
rc = DosAllocMem((PVOID *) &pb, 16384, fALLOC); /* Allocate 16 K object */
rc = DosSetMem(pb, 4096, PAG_DECOMMIT); /* Decommit 4KB */
After memory is decommitted, an attempt to access the decommitted memory will
cause a protection violation.
You cannot pass an argument that crosses multiple memory objects. The function
will return an error.
ΓòÉΓòÉΓòÉ 1.2.3. Establishing Access Protection ΓòÉΓòÉΓòÉ
When an OS/2 application commits a memory object, it specifies the types of
access permitted for the memory object. This can be done at the same time the
memory object is allocated, with DosAllocMem, or at a later time, using
DosSetMem.
Any combination of read, write, execute, or guard-page access can be set, but
at least read or write access must be specified when the memory object is
committed; it is not possible to commit an object with no access protection
attributes.
The application can also use DosSetMem to change the access permission of pages
within a previously committed memory object. An application can permit read
access to one page of the memory object and write access to the rest.
When using DosSetMem, all the pages in the range being changed must be either
committed or decommitted.
The following code fragment commits a region of two pages within a previously
allocated memory object, and sets read-only access rights for the region.
Assume that the base address for DosSetMem was previously obtained by the
process.
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#include <stdio.h>
PVOID BaseAddress; /* Pointer to the range of pages to be changed */
ULONG RegionSize; /* Size, in bytes, of the region to be changed */
ULONG AttributeFlags; /* Flag describing the page range */
APIRET rc; /* Return code */
RegionSize = 8192; /* Specify a two-page region */
AttributeFlags = PAG_COMMIT | PAG_READ;
rc = DosSetMem(BaseAddress, RegionSize, AttributeFlags);
if (rc != 0) {
printf("DosSetMem error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 1.2.4. Querying Memory Object Information ΓòÉΓòÉΓòÉ
DosQueryMem is used to determine the allocation state and access protection for
a specified memory object. The application can query an entire memory object or
a range of pages within an object.
The following code fragment uses DosQueryMem to ensure that memory is committed
before the application attempts to use the memory:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#define HF_STDOUT 1 /* Standard output handle */
PBYTE pb; /* Base address of an allocated object */
ULONG ulSize, flFlags, ulWritten;
APIRET rc; /* Return Code */
ulSize = 4096;
rc = DosQueryMem(pb, &ulSize, &flFlags); /* Queries first 4096 bytes */
if (flFlags & PAG_COMMIT) { /* If memory is committed, use it */
rc = DosWrite(HF_STDOUT, "\r\n 4KB is committed.\r\n", 21, &ulWritten);
}
ΓòÉΓòÉΓòÉ 1.2.5. Freeing Memory ΓòÉΓòÉΓòÉ
When memory object is no longer needed, the application uses the DosFreeMem
function to release the memory.
If applications do not release memory, the operating system either swaps the
memory to the hard disk (if swapping is enabled) or uses memory that could be
used by other applications. If the operating system swaps the memory to the
hard disk, the SWAPPER.DAT swap file could become very large. Therefore,
applications should release memory as soon as it is no longer needed. Any
memory that is still allocated when the application ends is released by the
operating system.
DosFreeMem frees a private or shared memory object from the virtual address
space of the process. The released pages are returned to the system.
The following code fragment allocates 8192 bytes of committed memory and then
releases the memory:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
PBYTE pb;
APIRET rc;
rc = DosAllocMem((PVOID *) &pb, 8192, fALLOC); /* Allocate 8KB object */
.
.
.
rc = DosFreeMem(pb); /* Free the object */
ΓòÉΓòÉΓòÉ 1.3. Using Suballocation and Heaps ΓòÉΓòÉΓòÉ
This section describes how you can use DosAllocMem, DosSubSetMem,
DosSubAllocMem, DosSubFreeMem, and DosSubUnsetMem to manage a memory heap.
ΓòÉΓòÉΓòÉ 1.3.1. Suballocating Memory ΓòÉΓòÉΓòÉ
DosAllocMem can be used to create a memory heap.
Before an application can allocate small portions of the heap, it must use the
DosSubSetMem function to set up the memory for suballocation. The size of the
heap is rounded up to the next higher multiple of 8 bytes.
Then, the application uses DosSubAllocMem to allocate sections of the heap and
the DosSubFreeMem function to release the memory.
DosSubAllocMem returns a 32-bit pointer to a block of memory. The pointer can
be used to access the memory without further modification.
The following code fragment sets up 8192 bytes for suballocation and then
allocates two small blocks of memory:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
APIRET rc;
PBYTE pbBase, pb1, pb2;
rc = DosAllocMem((PVOID *) &pbBase, 8192, fALLOC); /* Allocate 8 K object */
rc = DosSubSetMem(pbBase, DOSSUB_INIT, 8192); /* Set up object */
/* for suballocation */
rc = DosSubAllocMem(pbBase, (PVOID *) &pb1, 100); /* Suballocate 100 bytes */
rc = DosSubAllocMem(pbBase, (PVOID *) &pb2, 500); /* Suballocate 500 bytes */
rc = DosSubFreeMem(pbBase, pb1, 100); /* Free 1st suballocation*/
rc = DosSubAllocMem(pbBase, (PVOID *) &pb1, 50); /* Suballocate 50 bytes */
ΓòÉΓòÉΓòÉ 1.3.2. Increasing the Size of a Heap ΓòÉΓòÉΓòÉ
DosSubSetMem can also be used to increase the size of a previously initialized
heap. The heap size can be increased up to the size of the memory object that
contains it.
The size of the heap is rounded up to the next higher multiple of 8 bytes.
The following code fragment increases the size of a heap. Assume that a memory
object was previously allocated for the heap, and that the Offset variable was
previously loaded with the virtual address of the memory object.
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#include <stdio.h>
PVOID Offset; /* Address of the heap to be used for suballocation */
ULONG Flags; /* Flags describing the memory object being resized */
ULONG Size; /* Size in bytes to increase the size of the heap */
APIRET rc; /* Return code */
Size = 20000; /* Indicate a heap size increase of 20000 bytes */
Flags = DOSSUB_GROW | DOSSUB_SPARSE_OBJ;
rc = DosSubSetMem(Offset, Flags, Size);
if (rc != 0) {
printf("DosSubSetMem error: return code = %ld", rc);
return;
}
In this example, the heap is incremented, and that memory commitment is managed
internally within subsequent DosSubAllocMem calls.
When using DosSubSetMem to increase the size of the heap, the Flags parameter
must have the same setting as when the heap was initialized.
Note: Do not call DosSetMem to change the allocation attribute or access
protection attributes of any pages spanned by a memory object that the
suballocation functions are managing. Otherwise, unpredictable results
could occur.
Call DosSubUnsetMem when finished with the heap that was set up with
DosSubSetMem. This enables the suballocation function to free the resources
that it uses to manage the heap. When you are through with the memory object
that the heap was part of, use DosFreeMem to free the memory object.
ΓòÉΓòÉΓòÉ 1.3.3. Allocating a Block of Memory from a Heap ΓòÉΓòÉΓòÉ
DosSubAllocMem allocates a block of memory from a heap that was previously
initialized by DosSubSetMem. This is used when an application needs an area of
memory that is smaller than an entire heap.
The size of the memory block is rounded up to the next higher multiple of 8
bytes.
The following code fragment allocates a block of memory from a heap that was
previously initialized by DosSubSetMem. Assume that the Offset variable has
been set to the address of the initialized heap already.
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#include <stdio.h>
PVOID Offset; /* The heap to suballocate from */
PPVOID BlockOffset; /* Pointer to the variable where the offset of */
/* the suballocated memory block is returned */
ULONG Size; /* Size in bytes of the memory block requested */
APIRET rc; /* Return code */
Size = 102; /* Ask for 102 bytes. This will be rounded */
/* to 104 bytes (a multiple of 8 bytes). */
rc = DosSubAllocMem(Offset, &BlockOffset, Size);
if (rc != 0) {
printf("DosSubAllocMem error: return code = %ld", rc);
return;
}
In this example, the address of the allocated block (from the heap) is stored
in the BlockOffset variable.
Remember to call DosSubFreeMem to free this block of memory when you are
finished with it.
ΓòÉΓòÉΓòÉ 1.3.4. Freeing Memory Blocks ΓòÉΓòÉΓòÉ
DosSubFreeMem frees a block of memory that was previously allocated by
DosSubAllocMem.
Call DosSubFreeMem to free a block of memory in the heap when you are finished
with that memory block.
The following code fragment frees a block of memory that was previously
allocated from a heap. DosSubFreeMem returns the block to the heap. Assume that
the Offset variable has been previously set to the address of the initialized
heap, and that the BlockOffset variable has been previously set to the address
of the block to be returned to the heap.
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#include <stdio.h>
PVOID Offset; /* Offset of the heap to which the */
/* block is to be freed */
PVOID BlockOffset; /* Offset of memory block to be freed */
ULONG Size; /* Size in bytes of block to be freed */
APIRET rc; /* Return code */
Size = 102; /* Return 102 bytes. This will be rounded */
/* to 104 bytes (a multiple of 8 bytes). */
rc = DosSubFreeMem(Offset, BlockOffset, Size);
if (rc != 0) {
printf("DosSubFreeMem error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 1.3.5. Ending the Use of the Heap ΓòÉΓòÉΓòÉ
DosSubUnsetMem terminates the use of a heap within a memory object. All calls
to DosSubSetMem must eventually be followed by a call to DosSubUnsetMem. This
enables the suballocation function to free the resources that it uses to manage
the heap.
The application must call DosSubUnsetMem before it frees the memory object that
contains this heap (with DosFreeMem).
The following code fragment shows the termination of a heap. Assume that the
address of the heap was placed into Offset already.
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#include <stdio.h>
PVOID Offset; /* Offset of the heap whose use is being terminated */
APIRET rc; /* Return code */
rc = DosSubUnsetMem(Offset);
if (rc != 0) {
printf("DosSubUnsetMem error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 1.3.6. Allocating and Freeing Thread Local Memory ΓòÉΓòÉΓòÉ
Thread local memory is a small region of thread-specific memory assigned to a
thread when it is started.
A thread can allocate thread local memory by calling DosAllocThreadLocalMemory.
Thread local memory is freed by calling DosFreeThreadLocalMemory.
The thread local memory region is 32 DWORDS (4 bytes per DWORD) in size, and up
to 8 DWORDS can be allocated with each call to DosAllocThreadLocalMemory. To
allocate more than 8 DWORDS, a thread must call DosAllocThreadLocalMemory more
than once.
Note that thread local memory should be used sparingly. You should not use the
entire 128 byte region.
The following code fragment allocates six DWORDS in thread local memory and
then frees these six DWORDS.
#define INCL_DOSPROCESS
#define INCL_DOSERRORS
#include <os2.h>
#include <stdio.h> /* Needed for printf */
PULONG pulMemBlock = NULL; /* Pointer to thread DWORDs returned */
APIRET rc = NO_ERROR; /* Return code */
rc = DosAllocThreadLocalMemory( 6, &pulMemBlock ); /* Allocate 6 DWORDs */
if (rc != NO_ERROR) {
printf("DosAllocThreadLocalMemory error: return code = %u\n", rc);
return 1;
}
/* ... Use the thread-local memory block ... */
rc = DosFreeThreadLocalMemory( pulMemBlock ); /* Free the memory block */
if (rc != NO_ERROR) {
printf("DosFreeThreadLocalMemory error: return code = %u\n", rc);
return 1;
}
ΓòÉΓòÉΓòÉ 1.4. Using Shared Memory ΓòÉΓòÉΓòÉ
This section describes how you can use DosAllocSharedMem, DosGiveSharedMem,
DosGetSharedMem, and DosGetNamedSharedMem to use shared memory.
ΓòÉΓòÉΓòÉ 1.4.1. Using Named Shared Memory ΓòÉΓòÉΓòÉ
An application uses DosAllocSharedMem to allocate shared memory. When
allocating the shared memory, an application can assign a unique name to the
memory. Any application that has the name of the shared memory can use
DosGetNamedSharedMem to retrieve a pointer to the memory. This makes it
possible for two or more applications to share memory at the same time.
The name of a shared memory object has the following form:
\sharemem\name
The "\sharemem\" is required. The "name" parameter can be any name that
conforms to the rules for an OS/2 file name. No file is actually created for
the memory object. There is no actual "\sharemem\" subdirectory.
The following code fragment allocates 65536 bytes of named shared memory with
the name "\sharemem\mymem".
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
APIRET rc;
CHAR szMem[] = { "\\sharemem\\mymem" };
PULONG pb;
rc = DosAllocSharedMem((PVOID *) &pb, szMem, 65536, fALLOC);
*pb = 2762;
Once the named memory is allocated, any other process can retrieve a pointer to
the named memory by using DosGetNamedSharedMem.
The following code fragment retrieves a pointer to the named memory allocated
above:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
#define HF_STDOUT 1 /* Standard output handle */
APIRET rc;
CHAR szMem[] = { "\\sharemem\\mymem" };
PULONG pb2;
ULONG ulWritten;
rc = DosGetNamedSharedMem((PVOID *) &pb2, szMem, PAG_READ | PAG_WRITE);
if (*pb2 == 2762)
rc = DosWrite(HF_STDOUT, "\r\n Success!\r\n", 13, &ulWritten);
ΓòÉΓòÉΓòÉ 1.4.2. Using Unnamed Shared Memory ΓòÉΓòÉΓòÉ
An application can allocate unnamed shared memory by using DosAllocSharedMem
with the object name set to NULL and the memory options set to OBJ_GIVEABLE or
OBJ_GETTABLE. Sharing unnamed memory is more difficult than sharing named
memory because the application allocating the memory must somehow pass a
pointer to another application. This is typically done by using some form of
interprocess communication, such as a queue or a named pipe.
If an application allocates shared memory with the OBJ_GETTABLE option, it can
pass a pointer to another application. The second application can then gain
access to the shared memory by using DosGetSharedMem to validate the passed
pointer. If an application allocates shared memory with the OBJ_GIVEABLE
option, the process that allocates the memory can validate the pointer in
another process with DosGiveSharedMem. The allocating process must still pass a
pointer to the second process, but the second process need not use
DosGetSharedMem.
The following code fragment allocates 24576 bytes (24KB) of unnamed shared
memory:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
APIRET rc;
PBYTE pb;
rc = DosAllocSharedMem((PVOID *) &pb, (PSZ) NULL, 24576,
fALLOC | OBJ_GETTABLE);
Once the memory is allocated, the process can pass the memory pointer to a
second process via interprocess communication. Once the second process receives
the pointer, it can validate the memory with DosGetSharedMem, as shown in the
following code:
#define INCL_DOSMEMMGR /* Memory Manager values */
#include <os2.h>
APIRET rc;
PBYTE pb2;
rc = DosGetSharedMem(pb2, PAG_READ | PAG_WRITE);
ΓòÉΓòÉΓòÉ 2. Message Management ΓòÉΓòÉΓòÉ
This chapter describes the use of message files to hold an application's text
messages to the user. Keeping messages in a message file simplifies changing
those messages, for example when maintaining versions of the same application
for different countries.
The following topic is related to the information in this chapter:
National Language Support
ΓòÉΓòÉΓòÉ 2.1. About Message Management ΓòÉΓòÉΓòÉ
For full-screen applications, text messages-used by an application to display
information to the user-can be held in a message file.
To keep and maintain messages in a message file, create a separate message file
for each national language you intend to support. Use the MKMSGF utility
program to create a binary version of a message file, and the MSGBIND utility
program to bind the binary file to the application's executable file. Binding
the messages to an application's executable file inserts the messages into the
.EXE file. This enables faster access (but, of course, a larger .EXE file).
The OS/2 operating system provides several functions to assist in message
management. Applications can get messages from a message file, substitute
variable information into the messages, and write messages to the screen or to
a file.
Code Page Considerations
You can have versions of the message file for each code page you choose to
support. When you use MKMSGF to create the message files, the utility will
insert the code page information and link together the message files of the
different versions.
When message files are linked together in this manner, DosGetMessage will
search for the appropriate version of the message for the code page that is
active at the time the function is called. If there is no version of the
message for the current code page, the function will return the first version
of the message, no matter which code page it is associated with.
ΓòÉΓòÉΓòÉ 2.2. Using Message Management ΓòÉΓòÉΓòÉ
DosGetMessage retrieves a message from the specified system message file, and
inserts variable information into the body of the message.
DosInsertMessage inserts variable text-string information into the body of the
message, but does not retrieve the message.
DosPutMessage sends the message in a buffer, usually to a display screen.
DosPutMessage formats the screen buffer to prevent words from being split at
the end of a line.
DosQueryMessageCP retrieves the message file list of code pages and language
identifiers.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 2.2.1. Message Retrieval and String Substitution ΓòÉΓòÉΓòÉ
DosGetMessage retrieves a message from a system message file, and inserts
variable text-string information into the message.
In the following code fragment, the message file is "D:\MESSAGE\AUTOMSG.MSG".
The third message within the message file contains the string "%1 Error at
Station %2". The application calls DosGetMessage to convert this message into
the string "Automation Failure Error at Station 69B".
#define INCL_DOSMISC /* Miscellaneous values */
#include <os2.h>
#include <stdio.h>
UCHAR *IvTable[2]; /* Table of variables to insert */
ULONG IvCount; /* Number of variables */
UCHAR DataArea[80]; /* Message buffer (returned) */
ULONG DataLength; /* Length of buffer */
ULONG MsgNumber; /* Number of the message */
UCHAR FileName[40]; /* Message file path-name string */
ULONG MsgLength; /* Length of message (returned) */
UCHAR Field1[20]; /* String to substitute into variable */
/* field %1 of the message */
UCHAR Field2[20]; /* String to substitute into variable */
/* field %2 of the message */
APIRET rc; /* Return code */
strcpy(Field1,"Automation Failure"); /* Define the field with which to */
/* perform the first substitution */
strcpy(Field2,"69B"); /* Define the field with which to */
/* perform the second substitution */
IvTable[0] = Field1; /* Set up the array of pointers to */
IvTable[1] = Field2; /* substitute strings */
IvCount = 2; /* Two variable message fields in message */
DataLength = 80; /* Data buffer that will receive the */
/* complete message is 80 bytes in size */
MsgNumber = 3; /* Specify the third message in the */
/* message file */
strcpy(FileName,"D:\\MESSAGE\\AUTOMSG.MSG"); /* Path name of the */
/* message file */
rc = DosGetMessage(IvTable, IvCount, DataArea, DataLength,
MsgNumber, FileName, &MsgLength);
if (rc != 0) {
printf("DosGetMessage error: return code = %ld", rc);
return;
}
On successful return, the DataArea buffer contains the complete message (with
the two variable fields appropriately updated), and the MsgLength variable
contains the length of the message that was placed into the DataArea buffer.
If an error occurs (that is, if the return code does not equal 0), a message
that is related to the error will be placed in the message buffer. See the
DosGetMessage API reference in Control Program Programming Reference for a
description of the default messages that can be placed into the user's buffer
if an error occurs during the processing of these requests.
ΓòÉΓòÉΓòÉ 2.2.2. Text String Substitution in Memory ΓòÉΓòÉΓòÉ
DosInsertMessage inserts variable text-string information into a message that
resides within program memory.
In the following code fragment, the message resides in a program string
variable named Message. The message is the string "%1 Error at Station %2". The
application calls DosInsertMessage to convert this message into the string
"Automation Failure Error at Station 69B".
#define INCL_DOSMISC /* Miscellaneous values */
#include <os2.h>
#include <stdio.h>
UCHAR *IvTable[2]; /* Table of variables to insert */
ULONG IvCount; /* Number of variables */
UCHAR MsgInput[40] = "%1 Error at Station %2"; /* The input message */
ULONG MsgInLength; /* Length of input message */
UCHAR DataArea[80]; /* Message buffer (returned) */
ULONG DataLength; /* Length of updated message buffer */
ULONG MsgLength; /* Length of updated message (returned) */
UCHAR Field1[20]; /* String to substitute into variable */
/* field %1 of the message */
UCHAR Field2[20]; /* String to substitute into variable */
/* field %2 of the message */
APIRET rc; /* Return code */
strcpy(Field1,"Automation Failure"); /* Define the field with which to */
/* perform the first substitution */
strcpy(Field2,"69B"); /* Define the field with which to */
/* perform the second substitution */
IvTable[0] = Field1; /* Set up the array of pointers to */
IvTable[1] = Field2; /* substitute strings */
IvCount = 2; /* Two variable message fields in */
/* message */
MsgInLength = strlen(MsgInput); /* Length of input message */
DataLength = 80; /* Data buffer that will receive */
/* the complete message is 80 */
/* bytes in size */
rc = DosInsertMessage(IvTable, IvCount, MsgInput, MsgInLength,
DataArea, DataLength, &MsgLength);
if (rc != 0) {
printf("DosInsertMessage error: return code = %ld", rc);
return;
}
On successful return, the DataArea buffer contains the complete message (with
the two variable fields appropriately updated), and the MsgLength variable
contains the length of the message that was placed into the DataArea buffer.
If an error occurs (that is, if the return code does not equal 0), a message
that is related to the error will be placed in the message buffer. See the
DosGetMessage API reference in Control Program Programming Reference for a
description of the default messages that can be placed into the user's buffer
if an error occurs during the processing of these requests.
ΓòÉΓòÉΓòÉ 2.2.3. Writing Messages ΓòÉΓòÉΓòÉ
DosPutMessage is used to write the message to the screen or to a file on a
disk.
The following code fragment writes the message string contained in
MessageBuffer to the file specified by FileHandle. The message string has
already been placed in MessageBuffer using either DosGetMessage or
DosInsertMessage. MsgLength was set to the length of the message string by the
same call that put the message into MessageBuffer.
#define INCL_DOSMISC /* Miscellaneous values */
#include <os2.h>
#include <stdio.h>
HFILE FileHandle; /* Handle of output file or device */
ULONG MsgLength; /* Length of message buffer */
UCHAR MessageBuffer[80]; /* Message buffer */
APIRET rc; /* Return code */
rc = DosPutMessage(FileHandle, MsgLength, MessageBuffer);
if (rc != 0) {
printf("DosPutMessage error: return code = %ld", rc);
return;
}
To write a message to the screen, use the standard output file handle.
ΓòÉΓòÉΓòÉ 2.2.4. Code Page Information Associated with Message Files ΓòÉΓòÉΓòÉ
DosQueryMessageCP obtains a list of code page identifiers and language
identifiers that are associated with a specified message file.
In the following code fragment code page and language identifiers associated
with the message file "D:\MESSAGE\AUTOMSG.MSG" are retrieved.
#define INCL_DOSMISC /* Miscellaneous values */
#include <os2.h>
#include <stdio.h>
UCHAR BufferArea[20]; /* Buffer for the returned list */
ULONG BufferLength; /* Length of the buffer area */
UCHAR FileName[40]; /* Message file path-name string */
ULONG DataLength; /* Length of the returned data */
APIRET rc; /* Return code */
strcpy(FileName, "D:\\MESSAGE\\AUTOMSG.MSG"); /* Path name of message file */
BufferLength = 20; /* Length of buffer area */
rc = DosQueryMessageCp(BufferArea, BufferLength, FileName,
&DataLength);
if (rc != 0) {
printf("DosQueryMessageCp error: return code = %ld", rc);
return;
}
On successful return, the BufferArea buffer contains a set of information
concerning the code page identifiers and language identifiers that are
associated with the message file.
ΓòÉΓòÉΓòÉ 3. National Language Support ΓòÉΓòÉΓòÉ
Many applications need to be independent of a particular language. Rather than
being hard-coded in English, they want to support, for example, an English
version of the application, and a French version, and a German version;
preferably without having to change the program code for each version. Meeting
this requirement is simplified through the use of such resources as string
tables, menu templates, dialog templates, accelerator tables, and through the
use of code pages.
This chapter describes the functions an application uses to be NLS enabled, or
language independent.
The following topic is related to the information in this chapter:
o Message Management
ΓòÉΓòÉΓòÉ 3.1. About National Language Support ΓòÉΓòÉΓòÉ
The support of national languages by applications requires the following
considerations:
o Displayed text must be translated into the appropriate language.
o Symbols or icons might not convey the same meaning in all countries.
Alternative designs for different countries might be necessary.
o Translation changes the length of text strings.
o Different languages often have different text characters.
The use of national language resource files can help with the first three
items, and the ability of the application to receive input and display output
in any ASCII code page can help with the last item.
The use of ASCII code page 850 avoids many of the problems in this area, since
it contains most of the characters required for Latin-1 languages, which
include much of Western Europe and North and South America. However, older
programs use code page 437 for U.S. English, and code pages 860, 863, and 865
for various languages. The code page applies to both input and output data.
Note: Code page 850 was used for translating Presentation Manager text. Use
code page 850 whenever possible for all Presentation Manager
applications that might require translation.
ΓòÉΓòÉΓòÉ 3.1.1. National Language Resource Files ΓòÉΓòÉΓòÉ
When creating an application, define national language dependencies in
resources that are held in resource files separate from the program code. That
is:
o Keep pure text strings in string tables.
o Keep menus in menu templates.
o Keep dialog boxes in dialog templates.
o Keep accelerators in accelerator tables.
The language displayed by the application can then be changed by translating
the resources, in most cases without changing the application.
However, when translating from one language to another, the length of a text
string can change substantially. For example, when translating from English to
German, the length of a text string can double in length.
The following table furnishes a general idea of the amount of expansion that
can be expected during translation.
Translation Expansion
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFor English Phrases ΓöéTranslation Expansion Factors Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéUp to 10 characters Γöé101 - 200% Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé11 - 20 characters Γöé81 - 100% Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé21 - 30 characters Γöé61 - 80% Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé31 - 50 characters Γöé41 - 60% Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé51 - 70 characters Γöé31 - 40% Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéOver 70 characters Γöé30% Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
When designing your dialog boxes and text string messages, add white space to
allow for the expansion that will occur when the text is translated. You might
have to adapt the application program to allow for the change in the length of
text strings after they are translated. For example, a change in the length of
a text string can cause it to become misaligned with other displayed objects.
You can also use the Dialog Box Editor to adjust for misalignments, or to
change the size of the dialog box. This would enable you to leave your
application program unchanged.
Text strings explicitly displayed by the application program are more of a
problem. You will have to include program code that can handle text strings of
varying length and format them at runtime according to their size.
ΓòÉΓòÉΓòÉ 3.1.2. Language-Specific Versions of NLS-Enabled Applications ΓòÉΓòÉΓòÉ
There are two methods of creating a specific national language version of a
program designed to handle more than one national language. The choice of the
method depends on the amount of available disk space and whether the user wants
to change between different languages once the program is installed. The two
methods are:
o Statically link the resources to the application's .EXE files. The
executable files are then language-specific and cannot be changed to
another national language. The specific .EXE files are then sent to the
user.
o Place the resources into a language-specific, dynamic link library.
Designate one library file for each national language. Selecting a
particular library file for use with the application gives the desired
version of the program. Using this method, all national languages can be
shipped with the product; selection of the national language occurs
during installation (for example, by naming a specific .DLL file). It is
possible to change the national language setting while the program is
operating.
ΓòÉΓòÉΓòÉ 3.2. About Code Page Management ΓòÉΓòÉΓòÉ
A code page is a table that defines how the characters in a language or group
of languages are encoded. A specific value is given to each character in the
code page. For example, in code page 850 the letter "╨┤" (lowercase) is encoded
as hex A4 (decimal 164), and the letter "╨╡" (uppercase) is encoded as hex A5
(decimal 165).
Code page management enables a user to select a code page for keyboard input,
and screen and printer output before starting an application, a system command,
or a utility program in the OS/2 multitasking environment.
This means that a user in a particular country, such as England (code page
850), Norway (code page 865), or a language region such as Canadian French
(code page 863) can use a code page that defines an ASCII-based character set
containing characters used by that particular country or language.
Installable code page files include keyboard translate tables, display
character sets, printer character sets, and country/language information for
each code page supported.
Of particular interest are two code pages:
o Code Page 850
o Code Page 437
Code Page 850 (CP850)
Code Page 850 is also called the Latin-1, multilingual code page. This code
page supports the alphabetic characters of the Latin-1-based languages. It
contains characters required by 13 languages used in approximately 40
countries.
CP850 also provides the flexibility to develop new applications based on
non-Latin-based or special industry-based code pages.
Code Page 850 supports countries using the following languages:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéBelgian French ΓöéCanadian French Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDanish ΓöéDutch Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFinnish ΓöéFlemish Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFrench ΓöéGerman Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéItalian ΓöéNorwegian Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPortuguese ΓöéSpanish Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLAD Spanish ΓöéSwedish Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSwiss French ΓöéSwiss German Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéU.K. English ΓöéU.S. English Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Code Page 437 (CP437)
Code Page 437 is the standard personal computer code page.
The lower 128 characters are based on the 7-bit ASCII code. The upper 128
characters contain characters from several European languages (including part
of the Greek alphabet) and various graphic characters. However, some of the
accented characters, such as those used in the Nordic countries, are not
represented. The missing characters are available in other code pages (code
page 850 will usually contain the desired characters).
Note: Some of the 256 symbols that can be displayed are printer control
characters, and are not printed.
ΓòÉΓòÉΓòÉ 3.2.1. ASCII and EBCDIC Code Page Support ΓòÉΓòÉΓòÉ
The two leading character-coding systems are ASCII and EBCDIC. Presentation
Manager applications can use an EBCDIC code page instead of an ASCII code page.
Code pages based on both systems are supported by the OS/2 operating system.
Any code page that either is defined in the CONFIG.SYS file, or is one of the
EBCDIC code pages supported, can be selected.
ΓòÉΓòÉΓòÉ 3.2.2. Code Page Preparation ΓòÉΓòÉΓòÉ
During system initialization, the code pages specified in the CODEPAGE
statement are prepared to enable run-time code page switching of the display,
the keyboard, the printer, and the country information. The display, keyboard,
and printer must be defined in a DEVINFO statement in order to be prepared.
Country information is prepared for the system country code specified in the
COUNTRY statement.
If a resource cannot be prepared for the selected code page during system
initialization, it is prepared for a default code page. The following are the
defaults:
o A keyboard layout defaults to the code page of the translate table
designated as the default layout in the KEYBOARD.DCP file. The default
layout is based on the national code page of its associated country. You
must explicitly specify KEYBOARD.DCP in the DEVINFO statement for the
keyboard in CONFIG.SYS.
o The display defaults to the code page of ROM_0 for the device.
(ROM_0 means a device default code page that is the device native code
page or the lowest addressed ROM code page.)
o The printer defaults to the code page of ROM_0 for the device.
(ROM_0 means a device default code page that is the device native code
page or the lowest addressed ROM code page.)
o The country information defaults to the code page of the first entry
found in the COUNTRY.SYS file for the country code. Each entry is the
same information for a given country code, but is encoded in a different
code page. The first entry is based on the preferred country code page.
If country information cannot be prepared at system initialization because it
is not found in the COUNTRY.SYS file, for a code page selected with the
CODEPAGE statement, then it is prepared (maintained for run-time code page
switching in memory) in the default code page. Similarly, a keyboard layout is
prepared in its default code page if it cannot be prepared in the selected
code page, because it is not found in the KEYBOARD.DCP file.
COUNTRY.SYS contains one default entry per country code, and KEYBOARD.DCP
contains one default entry per keyboard layout based on these assignments.
ΓòÉΓòÉΓòÉ 3.2.3. Code Page Functions ΓòÉΓòÉΓòÉ
At the system level, the operating system switches the code pages of supported
displays and printers to agree with the code page of the process sending the
output. At the application level, OS/2 functions enable a process to control
code page assignments.
ΓòÉΓòÉΓòÉ 3.3. Using Code Pages ΓòÉΓòÉΓòÉ
The OS/2 operating system provides applications with several functions to
obtain information about and manipulate code pages. These functions enable
applications to determine and set the current code page.
OS/2 code page management functions enable applications to read keyboard input
and write display and printer output for multiple processes using ASCII-based
data encoded in different code pages.
The system switches to the required code page, for a code-page-supported
device, before input or output.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 3.3.1. Querying Code Page Support and the Current Code Page ΓòÉΓòÉΓòÉ
DosQueryCp is used to determine the code page of the current process and the
prepared system code pages. The following code fragment shows how to get the
current code page, and then up to three other prepared pages:
#define INCL_DOSNLS /* National Language Support values */
#include <os2.h>
ULONG CpList[8];
ULONG CpSize;
APIRET rc; /* Return code */
rc = DosQueryCp(sizeof(CpList), /* Length of list */
CpList, /* List */
&CpSize); /* Length of returned list */
The required code page is the current code page of the process at the time it
opens a device, or a specific code page selected by the process with a
set-code-page function. A character set can also be specified for some devices,
for example, for some printers.
The country functions retrieve country- and language-dependent information in
the current code page of the calling process, or in a code page selected by the
process.
ΓòÉΓòÉΓòÉ 3.3.2. Setting the Code Page for Text Characters ΓòÉΓòÉΓòÉ
Each process has a code page tag maintained by the operating system. A code
page tag is the identifier of the current code page for the process.
A child process inherits the code page tag of its parent. The default code page
for the first process in a session is the same as the session code page. The
default code page for a new session is the primary code page specified in the
CODEPAGE configuration statement.
To change the code page tag of a process, call DosSetProcessCp. This will not
change the process code page tag of its parent or any child process.
ΓòÉΓòÉΓòÉ 3.3.3. Obtaining the Case Map String ΓòÉΓòÉΓòÉ
DosMapCase performs case mapping on a string of binary values that represent
ASCII characters.
The case map that is used is the one in the country file that corresponds to
the system country code or selected country code, and to the process code page
or selected code page. The default name of the country file is COUNTRY.SYS.
ΓòÉΓòÉΓòÉ 3.3.4. Obtaining the DBCS Environment Vector ΓòÉΓòÉΓòÉ
DosQueryDBCSEnv obtains a double-byte character set (DBCS) environment vector
that resides in the country file. The default name of the country file is
COUNTRY.SYS.
The vector corresponds to the system country code or selected country code, and
to the process code page or selected code page.
The following code fragment shows how to use DosQueryDBCSEnv:
#define INCL_DOSNLS /* National Language Support values */
#include <os2.h>
#include <stdio.h>
ULONG Length; /* Length of data area provided */
COUNTRYCODE Structure; /* Input data structure */
UCHAR MemoryBuffer[12]; /* DBCS environmental vector (returned) */
APIRET rc; /* Return code */
Length = 12; /* A length of 12 bytes is sufficient */
/* to contain the DBCS data returned */
Structure.country = 0; /* Use the default system country code */
Structure.codepage = 0; /* Return DBSC information for the */
/* caller's current process code page */
rc = DosQueryDBCSEnv(Length, &Structure, MemoryBuffer);
if (rc != 0) {
printf("DosQueryDBCSEnv error: return code = %ld", rc);
return;
}
On successful return, the buffer MemoryBuffer will contain the country
dependent information for the DBCS environmental vector.
Instead of the single-byte character set (SBCS) representation used for Latin
text, some Asian countries use code pages that consist of double-byte character
set characters, in which each character is represented by a two-byte code. The
DBCS code pages enable single-byte data, double-byte data, or mixed
(single-byte and double-byte) data.
ΓòÉΓòÉΓòÉ 3.3.5. Obtaining Formatting Information ΓòÉΓòÉΓòÉ
DosQueryCtryInfo obtains country dependent formatting information that resides
in the country file. The default name of the country file is COUNTRY.SYS.
The information corresponds to the system country code or selected country
code, and to the process code page or selected code page.
ΓòÉΓòÉΓòÉ 3.3.6. Obtaining Collating Information for SORT ΓòÉΓòÉΓòÉ
DosQueryCollate obtains a collating sequence table (for characters 00H through
FFH) from the country file. The default name of the country file is
COUNTRY.SYS. The SORT utility program uses this table to sort text according to
the collating sequence.
The collating table returned corresponds to the system country code or selected
country code, and to the process code page or selected code page.
ΓòÉΓòÉΓòÉ 4. Pipes ΓòÉΓòÉΓòÉ
Communication between processes is valuable in a multitasking operating system
to enable concurrent processes to work together. Pipes are one of three forms
of interprocess communication (IPC), the other forms of IPC being semaphores
and queues.
This chapter describes how to create, manage, and use pipes. Pipes enable two
or more processes to communicate as if they were reading from and writing to a
file.
The following topics are related to the information in this chapter:
o Memory (Shared Memory)
o Program Execution and Control
o Semaphores
o Queues
ΓòÉΓòÉΓòÉ 4.1. About Pipes ΓòÉΓòÉΓòÉ
A pipe is a named or unnamed buffer used to pass data between processes. A
process writes to or reads from a pipe as if the pipe were standard input or
standard output. A parent process can use pipes to control the input that a
child process receives and to receive the output that the child process
produces.
There are two types of pipes-named and unnamed.
ΓòÉΓòÉΓòÉ 4.1.1. Unnamed Pipes ΓòÉΓòÉΓòÉ
An unnamed pipe is a circular buffer in memory. The buffer has in and out
pointers that are maintained by the system.
An unnamed pipe can transfer information only between related processes. A
child process started by a parent process with DosExecPgm inherits the handles
to any unnamed pipes created by its parent. This inheritance enables the parent
process and the child process to use the unnamed pipe to communicate with one
another. This type of pipe is typically used to redirect the standard input and
standard output of a child process.
To do this, a process opens a pipe and duplicates the read and write handles of
the pipe as the standard input and standard output files for the child process.
Once the handles are duplicated, the parent process can use DosExecPgm to start
the child process. When the child process reads and writes to its standard
input and standard output handles, it is reading and writing to the pipe. The
parent process can also communicate with the child process through the pipe.
Using an unnamed pipe, a text editor could run another program, such as a
compiler or assembler, and display the output of the compiler or assembler
within the editor.
DosCreatePipe creates an unnamed pipe. This function returns two file handles
for the pipe, one for writing to the pipe and another for reading from the
pipe. A process can then write to the pipe by using DosWrite and read from the
pipe by using DosRead.
A pipe exists until both handles are closed. The order in which the handles are
closed is sometimes important. For example, DosWrite might wait for data to be
read from the pipe before completing its operation. In this case, the read
handle is closed before the write handle is closed, writing to the pipe
generates an error.
No control or permission mechanisms or checks are performed on operations to
unnamed pipes.
ΓòÉΓòÉΓòÉ 4.1.2. Named Pipes ΓòÉΓòÉΓòÉ
Named pipes enable related or unrelated processes on either the same computer
system or different systems to communicate with each other. Any process that
knows the name of a pipe can open and use a named pipe. In addition, named pipe
data can be transparently redirected across a network, such as a local area
network (LAN). (Unnamed pipes, by contrast, can be used only by related
processes that are on the same computer system.)
One process (the server process) creates the pipe and connects to one end of
it. Other processes that access the named pipe are called client processes;
they connect to the other end of the pipe. The server and client processes can
then pass data back and forth by reading from and writing to the pipe. The
server process controls access to the named pipe.
The client process can be either local or remote. A local client process is one
that runs on the same computer system as the server process. A remote client
process runs on a different system and communicates with the server process
across a local area network (LAN).
When the server process creates a named pipe with DosCreateNPipe, it must
specify the direction that data will flow through the pipe. The process
specifies an inbound pipe if it intends to read data from the client process,
an outbound pipe if it intends to write data to the client process, or a duplex
pipe if it intends to read from and write to the client process.
The server process also specifies whether data passes through the pipe as bytes
or messages. A message is a block of data, with a system-supplied header, that
is read or written as a single unit. The server and client processes define the
size and format of a message.
The server process also specifies whether child processes will inherit the
named pipe and how information will be read from and written to the pipe. If
the server specifies wait mode, DosRead will be blocked (it will not return to
the process) until data is available in the pipe, and DosWrite will be blocked
until there is enough room in the pipe to contain the entire data buffer. If
the server specifies no-wait mode, reading from an empty pipe or writing to a
full pipe immediately returns an error value.
A named pipe consists of two pipe buffers, one for each direction of
communication. However, each end of the pipe has only one handle associated
with it. The server receives the handle for its end when it creates the pipe
with DosCreateNPipe. The client receives the handle for its end when it opens
the pipe with DosOpen.
The server and the client use their respective handles both to read from the
pipe and to write to it. (This is in contrast to unnamed pipes, for which both
the server and the client read from one handle and write to another.) In other
words, data that is written by the process at one end of the pipe is read by
the process at the other end.
A named pipe can have multiple instances, up to the number specified when the
pipe is first created. Pipe instances are actually separate pipes-that is,
unique sets of pipe buffers with unique handles-that share the same name. The
ability to create multiple pipe instances enables the server to communicate
with multiple client processes at the same time.
ΓòÉΓòÉΓòÉ 4.1.2.1. Server-Client Communications Using Named Pipes ΓòÉΓòÉΓòÉ
A server process initiates a connection to a client process by using
DosConnectNPipe. Once the pipe has been connected by the server process, the
client process must open the pipe by using DosOpen to complete the connection.
If no client process has opened the pipe when the server process calls
DosConnectNPipe, the function either waits until a client opens the pipe or
returns ERROR_PIPE_NOT_CONNECTED, depending on whether the server process
created the pipe to wait for data.
Each client process requires a separate instance of a pipe. For example, if a
server process creates a named pipe and specifies that four instances of the
pipe can be created, the process can then create three more instances of the
named pipe (for a total of four pipes, including the original). Each instance
has the same name, but each has a unique pipe handle. The process can then
connect each pipe to the server. (Each instance must be connected by an
explicit use of DosConnectNPipe.) In this example, the server must use each
function four times to create and connect four separate instances of the named
pipe. Each pipe is then available to a separate client process.
If a client process receives the ERROR_PIPE_BUSY return value from DosOpen, no
instances of the given pipe are available. The process can use DosWaitNPipe to
wait for an instance to become available. The function waits until an instance
is free or until the specified time interval elapses. When an instance becomes
free, the process can open the pipe. If several processes are waiting for an
instance to become available, the system gives the named pipe to the process
that has been waiting the longest.
The server process can disconnect a client process from a pipe by using
DosDisConnectNPipe. Ideally, the client process closes the pipe by using
DosClose before the server process disconnects the pipe. If the client process
has not closed the pipe when the server process disconnects it, the server
process forces the pipe closed and the client process subsequently receives
errors if it attempts to access the pipe. Note that forcing the closure of the
pipe might discard data in the pipe before the client process has had an
opportunity to read it.
A process can read and write bytes to a named pipe by using DosRead and
DosWrite. A process can read or write messages by using DosTransactNPipe.
Depending on the access mode, DosTransactNPipe writes a message to the pipe,
reads a message from the pipe, or both. If a named pipe contains unread data or
is not a message pipe, DosTransactNPipe fails. If it is reading from the pipe,
DosTransactNPipe does not return until a complete message is read, even if the
server process specified no-wait mode when the pipe was created.
A process can also read data from a named pipe without removing the data from
the pipe by using DosPeekNPipe. This function copies the specified number of
bytes from the pipe and returns the number of bytes of data left in the pipe
and the number of bytes left in the current message, if any.
DosPeekNPipe also returns the state of the pipe. A named pipe can be in one of
the following states:
Named Pipe States
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéState ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéConnected ΓöéThe pipe has been created and connected by Γöé
Γöé Γöéthe server process and has been opened by a Γöé
Γöé Γöéclient process. Only connected pipes can be Γöé
Γöé Γöéwritten to or read from. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéClosing ΓöéThe pipe has been closed by the client Γöé
Γöé Γöéprocess but has not yet been disconnected by Γöé
Γöé Γöéthe server process. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDisconnected ΓöéThe pipe has been created by the server Γöé
Γöé Γöéprocess but not connected, or has been Γöé
Γöé Γöéexplicitly disconnected and not yet Γöé
Γöé Γöéreconnected. A disconnected pipe cannot Γöé
Γöé Γöéaccept a DosOpen request. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéListening ΓöéThe pipe has been created and connected by Γöé
Γöé Γöéthe server process but has not yet been Γöé
Γöé Γöéopened by a client process. A listening pipe Γöé
Γöé Γöéis ready to accept a request to open. If the Γöé
Γöé Γöépipe is not in a listening state, DosOpen Γöé
Γöé Γöéreturns ERROR_PIPE_BUSY. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
DosCallNPipe is used to open, write to, read from, and close a named
message-format pipe. This function is equivalent to calling DosOpen,
DosTransactNPipe, and DosClose If no instances of the pipe are available,
DosCallNPipe waits for an instance or returns without opening the pipe if the
specified interval of time elapses.
A process can retrieve information about the handle state of a named pipe by
using DosQueryNPHState. The handle state is a combination of the instance
count, the access mode, and the pipe type (byte or message). DosQueryNPHState
also specifies whether the process owning the handle is a server or client and
whether the pipe waits if reading and writing cannot proceed.
A process can modify the handle state of a named pipe by using DosSetNPHState.
For example, the process can change the reading mode for the pipe, enabling a
process to read bytes from the pipe instead of messages.
ΓòÉΓòÉΓòÉ 4.1.2.2. Steps in Managing Server-Client Transactions ΓòÉΓòÉΓòÉ
The following sequence summarizes the typical steps in the management of a
named pipe:
1. The server process creates the pipe by calling DosCreateNPipe.
DosCreateNPipe returns a handle for the server end of the pipe. (Note
that the server uses the same handle to both read from and write to the
pipe.) The pipe is now in the disconnected state and cannot be opened by
a client process. The server process calls DosConnectNPipe to put the
pipe into a listening state.
2. The pipe can now be opened by a client process.
3. A client process supplies the name of the pipe in a call to DosOpen and
receives a pipe handle in return. (The client uses the same handle to
both read from and write to the pipe.) The pipe is now in the connected
state and can be read from or written to by the client.
4. The server and client processes communicate by calling DosRead and
DosWrite. DosResetBuffer can be used to synchronize read and write
dialogs. A server process that supports a large number of clients for a
local named pipe can use DosSetNPipeSem and DosQueryNPipeSemState to
coordinate access to the pipe. Server and client processes can also use
DosTransactNPipe and DosCallNPipe to facilitate their communication.
5. After completing its transactions, the client process calls DosClose to
close its end of the pipe. The pipe is now in the closing state and
cannot be accessed by another client.
6. The server process calls DosDisConnectNPipe to acknowledge that the
client has closed its end of the pipe. The pipe is now in the
disconnected state again.
7. To enable another client process to open the pipe, the server must call
DosConnectNPipe again. This puts the pipe back into the listening state.
To end its access to the pipe, the server calls DosClose. When all of the
handles for both ends of the pipe have been closed, the pipe is
deallocated by the system.
ΓòÉΓòÉΓòÉ 4.1.2.3. Preparing a Named Pipe for a Client ΓòÉΓòÉΓòÉ
A server process uses DosConnectNPipe to put a newly created named pipe into
the listening state. The pipe must be in the listening state in order for a
client process to gain access to the pipe by calling DosOpen.
After successfully opening the pipe and finishing its transactions, the client
process calls DosClose to end its access to the pipe. The server process must
acknowledge the close by calling DosDisConnectNPipe. It can then call
DosConnectNPipe again to put the pipe into the listening state for the next
client.
Together, DosConnectNPipe and DosDisConnectNPipe enable a server to create a
named pipe and to reuse it for communication with different clients. Without
these functions, the server would have to delete and re-create the pipe for
each client.
Note: If multiple instances of a named pipe have been created, then each
instance of the pipe must be put into the listening state before it can
be opened by a client.
ΓòÉΓòÉΓòÉ 4.1.2.4. Facilitating Transaction Processing ΓòÉΓòÉΓòÉ
DosTransactNPipe and DosCallNPipe facilitate the use of named pipes by
combining other named pipe functions. Compared to calling the other functions
separately, DosTransactNPipe and DosCallNPipe provide significant performance
gains for applications that operate in a networked environment. They can also
be used by local processes. However, both of these functions can be used only
with duplex message pipes.
o DosTransactNPipe performs a transaction (a DosWrite followed by DosRead)
on a duplex message pipe.
o DosCallNPipe has the combined effect of DosOpen, DosTransactNPipe, and
DosClose, and is referred to as a procedure call. It provides an
efficient means of implementing local and remote procedure call
interfaces between processes.
ΓòÉΓòÉΓòÉ 4.1.2.5. Coordinating Access to a Local Named Pipe with Semaphores ΓòÉΓòÉΓòÉ
When a process writes to a named pipe, the process at the other end (or handle)
of the pipe might require notification that data is available to be read.
Similarly, when a process reads from a named pipe, the process at the other end
might require notification that write space has become available. As long as
the communicating processes are on the same computer system, shared event
semaphores and muxwait semaphores can be used to provide this notification.
Using shared semaphores for this purpose is more efficient than dedicating a
thread to periodically poll each pipe, particularly when a server process is
communicating with a large number of client processes. The server or client
(whichever is writing to the pipe) can post a semaphore whenever data is
available in the pipe. This means that the reading process can use
DosWaitEventSem or DosWaitMuxWaitSem to wait for data to arrive, rather than
devote a thread to periodically polling the pipe.
A process associates a semaphore with a named pipe by using DosSetNPipeSem.
First, create an event semaphore with DosCreateEventSem, specifying the initial
state of the semaphore as reset. Then call DosSetNPipeSem to attach the event
semaphore to a particular named-pipe handle. Up to two event semaphores can be
attached to each named pipe, one for the server process and one for the client
process. If there is already a semaphore associated with one end of the pipe,
that semaphore is replaced. A process can check the state of the semaphores by
using DosQueryNPipeSemState.
The server or client process must then call DosWaitEventSem. The particular
thread that calls this function will block until data is either read from or
written to the pipe. At that time, the system posts the event semaphore,
enabling the blocked thread to resume its execution.
If a process requires notification whenever any one of multiple named pipes has
been written to or read from, it can either attach the same event semaphore to
multiple pipes, or it can create a muxwait semaphore:
o If the same event semaphore is attached to multiple pipes, then the
KeyHandle parameter of DosSetNPipeSem is used to assign a unique value to
each pipe. After the event semaphore has been posted, the process calls
DosQueryNPipeSemState. This function returns information about each of
the named pipes that are attached to the semaphore, including key-handle
values. The calling process can use this information to determine which
one of the named pipes has either data or write space available.
o To use a muxwait semaphore, a process first creates an event semaphore
for each of the pipes that it wants to monitor. Each semaphore must then
be attached to a pipe by calling DosSetNPipeSem. Again, a unique
key-handle value must be assigned to each pipe.
Next, the process calls DosCreateMuxWaitSem to create the muxwait
semaphore, specifying DCMW_WAIT_ANY as one of the flAttr flags. The
muxwait semaphore will consist of a linked list of the previously created
event semaphores.
The process calls DosWaitMuxWaitSem so that it will be notified the next
time data is read from or written to any of the pipes. However, it must
call DosQueryNPipeSemState to determine which one of the pipes is ready
to be read from or written to.
ΓòÉΓòÉΓòÉ 4.2. Using Unnamed Pipes ΓòÉΓòÉΓòÉ
Unnamed pipes are useful in applications that transfer data between related
processes. They are commonly used to control the input and output of child
processes by redirecting the standard input and output of the child process to
a pipe controlled by the parent process.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 4.2.1. Creating Unnamed Pipes ΓòÉΓòÉΓòÉ
DosCreatePipe creates an unnamed pipe. Two handles are returned: one for read
access to the pipe and one for write access. The pipe size specified is
advisory; its actual size is dependent on the amount of available memory. If
the size parameter is 0, the pipe is created with the default size, which is
512 bytes.
This example creates an unnamed pipe. The current process can use the unnamed
pipe for communication between itself and a child process.
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#include <stdio.h>
HFILE ReadHandle; /* Pointer to the read handle */
HFILE WriteHandle; /* Pointer to the write handle */
ULONG PipeSize; /* Pipe size */
APIRET rc; /* Return code */
PipeSize = 4096; /* Ask for 4KB of internal storage */
/* for the pipe */
rc = DosCreatePipe(&ReadHandle, &WriteHandle, PipeSize);
if (rc != 0) {
printf("DosCreatePipe error: return code = %ld", rc);
return;
}
On successful return, the ReadHandle variable contains the read handle for the
pipe, and the WriteHandle variable contains the write handle for the pipe.
After a process creates a pipe, any child process started with DosExecPgm
inherits the pipe handles. Using shared memory, the parent process can pass one
of the pipe handles to the child process; thus, one process can store data in
the pipe and the other can retrieve it.
ΓòÉΓòÉΓòÉ 4.2.2. Reading from and Writing to Unnamed Pipes ΓòÉΓòÉΓòÉ
Applications use the OS/2 file system functions to read from and write to
unnamed pipes.
The handles returned by DosCreatePipe are used as file handles to DosRead and
DosWrite.
To write (or add data) to an unnamed pipe, call DosWrite, specifying the write
handle of the pipe in DosWrite's file handle parameter. DosWrite requests to a
pipe are processed in the order in which they are made. Multiple calls to
DosWrite can be made before data is read (or removed) from the pipe. When the
pipe becomes full, write requests are blocked until space is freed by read
requests.
To read from a pipe, call DosRead, specifying the read handle of the pipe in
DosRead's file handle parameter. Subsequent calls to DosRead can empty the pipe
if no further calls to DosWrite are made in the meantime.
If the process reading the pipe ends, the next DosWrite request for that pipe
returns ERROR_BROKEN_PIPE.
Calling DosClose terminates access to an unnamed pipe. However, the pipe is not
deleted from memory until all handles to the pipe have been closed, including
any handles that were defined with DosDupHandle.
ΓòÉΓòÉΓòÉ 4.2.3. Redirecting Standard I/O for Child Processes ΓòÉΓòÉΓòÉ
An application can use unnamed pipes to redirect the standard input and the
standard output for a child process.
A typical use of an unnamed pipe is to read the output of a child process. An
application creates a pipe and then duplicates the standard output handle. When
the child process is started, its standard output will be written into the
pipe, where the application can read and display it. The following code
fragment shows how to do this:
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#define PIPESIZE 256
#define HF_STDOUT 1 /* Standard output handle */
HPIPE hpR, hpW;
RESULTCODES resc;
ULONG cbRead, cbWritten;
CHAR achBuf[PIPESIZE], szFailName[CCHMAXPATH];
HFILE hfSave = -1,
hfNew = HF_STDOUT;
DosDupHandle(HF_STDOUT, &hfSave); /* Saves standard output handle */
DosCreatePipe(&hpR, &hpW, PIPESIZE); /* Creates pipe */
DosDupHandle(hpW, &hfNew); /* Duplicates standard output handle */
DosExecPgm(szFailName, sizeof(szFailName), /* Starts child process */
EXEC_ASYNC, (PSZ) NULL, (PSZ) NULL, &resc,
"DUMMY.EXE");
DosClose(hpW); /* Closes write handle to ensure */
/* Notification at child termination */
DosDupHandle(hfSave, &hfNew); /* Brings stdout back */
/*
* Read from the pipe and write to the screen
* as long as there are bytes to read.
*/
do {
DosRead(hpR, achBuf, sizeof(achBuf), &cbRead);
DosWrite(HF_STDOUT, achBuf, cbRead, &cbWritten);
} while(cbRead);
A parent process can also use unnamed pipes to communicate with a child process
by redirecting both the standard input and the standard output for the child
process. To do this, the parent process:
1. Uses DosDupHandle to redefine the read handle of one pipe as standard
input (0000), and the write handle of the other pipe as standard output
(0001).
2. Starts the child process with DosExecPgm.
3. Uses the remaining pipe handles to read and write to the pipes.
The parent process controls the meanings for standard I/O for the child
process. Thus, when the child process uses standard I/O handles with DosRead
and DosWrite, it reads from and writes to the pipes of its parent instead of
reading from the keyboard and writing to the display.
ΓòÉΓòÉΓòÉ 4.3. Using Named Pipes ΓòÉΓòÉΓòÉ
Named pipes are useful in applications that transfer data between processes.
The processes using named pipes can be related, unrelated, or even on different
computers.
ΓòÉΓòÉΓòÉ 4.3.1. Creating Named Pipes ΓòÉΓòÉΓòÉ
The server process creates a named pipe by using DosCreateNPipe.
You must specify the name of the pipe, the access modes, the type of pipe (byte
or message), and the sizes of the input and output buffers. DosCreateNPipe
returns a pipe handle that can be used in subsequent pipe operations.
Each named pipe must have a unique name of the following form:
\PIPE\PipeName
The "\PIPE\" in the name above is required, but need not be uppercase. It is
not the name of a subdirectory.
To open a pipe on a remote computer, the client process must specify the name
of the server process that opened the pipe as part of the pipe name, as
follows:
\\Server\PIPE\PipeName
"\\Server" in the name above is the name of the remote computer; again,
"\PIPE\" is required.
The name parameter must conform to the rules for OS/2 file names, but no actual
file is created for the pipe.
In the following code fragment, DosCreateNPipe creates a pipe named \pipe\pipe1
and supplies a unique handle identifying the pipe. OpenMode is set to
NP_ACCESS_DUPLEX. This activates full duplex access to the named pipe. There
will be no inheritance to child process, and no write-through (write-through
only affects remote pipes). PipeMode is set to "NP_WMESG | NP_RMESG | 0x01".
This specifies that the pipe should be read as a message stream for both
reading and writing and an instance count of 1 (only one instance of the named
pipe can be created at a time). The pipe will block on Read/Write if no data is
available.
#define INCL_DOSNMPIPES /* Named-pipe values */
#include <os2.h>
#include <stdio.h>
UCHAR FileName[40]; /* Pipe name */
HPIPE PipeHandle; /* Pipe handle (returned) */
ULONG OpenMode; /* Open-mode parameters */
ULONG PipeMode; /* Pipe-mode parameters */
ULONG OutBufSize; /* Size of the out-buffer */
ULONG InBufSize; /* Size of the in-buffer */
ULONG TimeOut; /* Default value for DosWaitNPipe time-out parameter */
APIRET rc; /* Return code */
strcpy(FileName,"\\PIPE\\PIPE1");
OpenMode = NP_ACCESS_DUPLEX; /* Full duplex, no inheritance, */
/* no write-through */
PipeMode = NP_WMESG | NP_RMESG | 0x01; /* Block on read and write, message */
/* stream, instance count of 1 */
OutBufSize = 4096; /* The outgoing buffer must be 4KB in size */
InBufSize = 2048; /* The incoming buffer must be 2KB in size */
TimeOut = 10000; /* Time-out is 10 seconds (units are in milliseconds) */
rc = DosCreateNPipe(FileName, &PipeHandle, OpenMode,
PipeMode, OutBufSize, InBufSize,
TimeOut);
if (rc != 0) {
printf("DosCreateNPipe error: return code = %ld", rc);
return;
}
Once the named pipe is created, the application can call DosConnectNPipe to
connect a client process to the pipe.
Once a client process connects to the pipe, the process can read from and write
to the pipe. The preceding example creates a byte pipe, so the process can use
DosRead and DosWrite to read from and write to the pipe.
After the client process finishes using the pipe, the server process can
disconnect the pipe by using DosDisConnectNPipe. The server process can either
connect again or close the named pipe by using DosClose.
When a server process creates a named pipe, it defines the pipe to the system
by specifying the file write-through mode, the inheritance mode, the access and
blocking modes, the pipe type, the read mode, the size of the in and out
buffers, and the instance count. The following list describes these modes,
types, and buffers.
o The file write-through mode has significance only for communication with
remote client processes. When the file write-through bit is set, data is
sent across the network as soon as it is written; otherwise, the
operating system will in some cases hold data briefly in a local buffer
before sending it across the network.
o The inheritance mode specifies whether or not the pipe handle will be
inherited by a child process.
o The access mode specifies the direction in which data will flow through
the pipe. The server creates an inbound pipe (a pipe with inbound access
mode) if it intends to read data from the client process, an outbound
pipe if it intends to write data to the client process, or a duplex pipe
if it intends to both read from and write to the client process.
o The blocking mode specifies whether or not DosRead and DosWrite will
block when no data is available to read, or there is no room to write
data.
o The pipe type is the form in which a stream of data is written to the
pipe. If the pipe is a byte pipe, the server and client processes write
data as an undifferentiated stream of bytes. If the pipe is a message
pipe, the processes write data as a stream of messages; messages are
blocks of data, each with a system-supplied header, that are written as
single units. The server and client processes define the size and format
of a message.
o The read mode is the form in which data is read from the pipe. The data
in a pipe that was created as a byte pipe can only be read as bytes;
therefore, a byte pipe will always be in byte-read mode. The data in a
message pipe, however, can be read either as messages or as bytes. (If
it is to be read as bytes, DosRead skips over the message headers).
Therefore, message pipes can be in either message-read mode or byte-read
mode.
Note: The terms "byte pipe" and "message pipe" always refer to the pipe
type-the form in which data is written to the pipe. When the read
mode of a pipe is being referred to, it is always explicitly
identified as either message-read mode or byte-read mode.
o The in and out buffers can be up to 64KB in size. If the pipe will be
read in message-read mode, and if the message size is known, the server
can control how many messages the buffer will hold at one time by
specifying the appropriate buffer size.
o The instance count is the maximum number of instances of the named pipe
that can be created. A pipe instance is actually a separate pipe-that is,
a unique set of pipe buffers with unique handles. However, the term "pipe
instance" is used to distinguish pipes that share the same name from
pipes with different names. Because a client process uses only the name
of the pipe when opening it, the existence of multiple pipe instances is
transparent to a client process.
Creating Multiple Instances of a Named Pipe
Although each named pipe must have a unique name, a server process can create
multiple instances of a pipe, all of which have the same name. A pipe instance
is actually a separate pipe-that is, a unique set of pipe buffers with unique
handles.
The ability to create multiple pipe instances enables the server to
communicate with multiple client processes at the same time. Because a client
process uses only the name of the pipe when opening it, the existence of
multiple pipe instances is transparent to a client process.
The ICount parameter of DosCreateNPipe specifies the maximum number of named
pipe instances that can be created. (An unlimited number can also be
specified.) This parameter is specified only when the first instance of a
named pipe is created; any subsequent attempt to redefine the instance count
will be ignored.
If the instance count is greater than 1, the server process can create
additional pipe instances by specifying the same pipe name in subsequent calls
to DosCreateNPipe. Generally, the attributes of the subsequent pipe instances
are defined to be the same as those of the original pipe instance, because a
client process that requests the pipe has no way of controlling which pipe
instance will be assigned to it.
After an additional pipe instance has been created, it is used in the same
manner as the original pipe instance. That is, the same sequence of named
pipe functions is used in the control or management of all named pipe
instances. (See Steps in Managing Server-Client Transactions for more
information.)
Note: If all of the instances of a named pipe are in use when a client calls
DosOpen, ERROR_PIPE_BUSY is returned. However, the client can wait for
an instance of that pipe to become available by calling DosWaitNPipe.
Multiple instances of a named pipe can be created by different processes. That
is, multiple server processes can create and use instances of the same named
pipe to communicate with their clients.
ΓòÉΓòÉΓòÉ 4.3.2. Opening Named Pipes ΓòÉΓòÉΓòÉ
A client process can open the client end of a named pipe by using DosOpen.
DosOpen opens the client end of a pipe by name and returns a handle. The
application must use the appropriate pipe name and access modes to open the
pipe for reading, writing, or both. (To open a pipe on a remote computer, the
client process must also specify the name of the computer system as part of the
pipe name, as follows:
\\ComputerName\PIPE\PipeName.)
If a pipe name includes a remote LAN server name, DosOpen attempts to open the
pipe on a remote computer. The server process can then read input from the
client process through the pipe.
The following code fragment opens a remote pipe, reads from the standard input
(usually the keyboard), and sends the information to the server process through
the pipe:
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#define PIPESIZE 256
#define SERVER_PIPE_NAME "\\\\myserver\\pipe\\mypipe"
#define HF_STDIN 0 /* Standard input handle */
HPIPE hp;
BYTE abBuf[PIPESIZE];
ULONG ulAction, cbRead, cbWritten;
APIRET rc;
rc = DosOpen(SERVER_PIPE_NAME, &hp, &ulAction, 0,
FILE_NORMAL, FILE_OPEN,
OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE,
(PEAOP) NULL);
if (rc)
DosExit(EXIT_PROCESS, 0); /* Open pipe failed */
do { /* Open pipe succeeded */
DosRead(HF_STDIN, abBuf, sizeof(abBuf), &cbRead);
DosWrite(hp, abBuf, cbRead, &cbWritten); /* Writes to the pipe */
} while (cbRead > 2); /* Stop on a blank line */
DosClose(hp);
The client process checks the return value from DosOpen to verify that the pipe
was actually opened. If the server process has not yet created the pipe,
DosOpen returns an error. When the client process finishes using the pipe, it
closes the pipe by using DosClose.
When a named pipe is opened, its initial state is set by the system to block
read and write operations (blocking mode), and to read data as a byte stream
(byte-read mode). However, the client can change these modes by calling
DosSetNPHState. A call to DosOpen fails if all instances of the named pipe are
already open.
The open also fails if the pipe has been closed by a client, but the server has
not called DosDisConnectNPipe (to acknowledge the client's close), followed by
DosConnectNPipe (to prepare the pipe for the next client). In both of these
situations, ERROR_PIPE_BUSY is returned.
If all instances of a named pipe are busy, a client process can call
DosWaitNPipe to wait for an instance to become available before it calls
DosOpen again.
After a pipe instance has been opened by a client, that same instance cannot be
opened by another client at the same time. However, the opening process can
duplicate the handle as many times as desired by calling DosDupHandle. This
enables child processes to share access to a pipe instance with a parent
process.
The access-mode and sharing-mode fields that are specified for DosOpen must be
the same as those that were specified by the server when it created the pipe
with DosCreateNPipe.
ΓòÉΓòÉΓòÉ 4.3.3. Reading from Named Pipes ΓòÉΓòÉΓòÉ
Both the server and the client processes read data from a pipe by calling
DosRead. The server reads from the handle that was returned when it created the
pipe with DosCreateNPipe, and the client reads from the handle that was
returned to it by DosOpen.
When a pipe is created, the PipeMode parameter is used to specify both the pipe
type and the read mode for the server end of the pipe:
o A byte pipe can be read-only in byte-read mode. (DosCreateNPipe and
DosSetNPHState return ERROR_INVALID_PARAMETER if message-read mode is
specified for a byte pipe.) In byte-read mode, all currently available
data is returned, up to the buffer size specified by DosRead.
o A message pipe can be read in either byte-read mode or message-read mode,
as follows:
- When a message pipe is read in byte-read mode, the message headers
are skipped, and the pipe is read as if it were a byte pipe.
- When a message pipe is read in message-read mode, each message is
read either in its entirety, or not at all, depending on the size of
the message and the buffer length:
o If the buffer length that was specified for DosRead is larger
than the next available message, then only that message is
read, and the Bytes-Read parameter indicates the size of the
message.
o If the buffer length for DosRead is smaller than the next
available message, DosRead returns the number of bytes
requested and ERROR_MORE_DATA. Subsequent calls to DosRead are
blocked until the rest of the message can be transferred.
(DosPeekNPipe can be used to find out how many bytes are left
in the message.)
The PipeMode parameter of DosCreateNPipe also specifies the blocking mode for
the server end of the pipe:
o If nonblocking mode was specified, DosRead returns immediately with 0 in
the Bytes-Read parameter if no data is available.
o If blocking mode was specified, DosRead blocks until data is available;
the only time it will return with 0 in the Bytes-Read parameter is if it
reaches end-of-file.
DosRead works the same for both ends of the pipe. However, the read mode and
blocking mode are not necessarily the same for the client end of the pipe as
they are for the server end, because DosOpen always opens the CLIENT end in
byte-read mode and blocking mode.
The read mode and blocking mode for either end of the pipe can be changed by
calling DosSetNPHState. The pipe type, however, is always the same for both
the server and client ends of the pipe, and it cannot be changed.
ΓòÉΓòÉΓòÉ 4.3.4. Writing to Named Pipes ΓòÉΓòÉΓòÉ
Both the server and the client processes write to a pipe by calling DosWrite.
The server writes to the handle that was returned to it by DosCreateNPipe, and
the client writes to the handle that was returned to it by DosOpen.
Either bytes or messages can be written, depending on whether the pipe was
created as a byte pipe or as a message pipe.
When a process writes to a message pipe, the buffer-length parameter for
DosWrite holds the size of the message that the process is writing. Because
DosWrite automatically encodes message lengths in the pipe, applications do not
have to encode this information in the data buffers.
The action taken by DosWrite depends on the blocking mode of the pipe, which is
not necessarily the same for the server and client ends of the pipe. For the
server process, the blocking mode of the pipe is specified when the pipe is
created. For a client process, the blocking mode is automatically set to
blocking when the pipe is opened. The blocking mode can also be reset by
calling DosSetNPHState.
If the end of the message pipe that is being written to is in blocking mode,
DosWrite does not return until all of the requested bytes have been written.
(It might have to wait for the first part of the message to be read before it
can write the rest of the message.)
If the message pipe is in nonblocking mode, DosWrite takes the following
action:
o If the message is larger than the pipe buffer, DosWrite blocks until the
entire message has been written. (Again, it might have to wait for the
first part of the message to be read before it can write the rest of the
message.)
o If the message is smaller than the pipe buffer, but there is currently
not enough room in the buffer, DosWrite returns with a value of 0 in the
Bytes-Written parameter.
If a byte pipe is in nonblocking mode, and if there is more data to be written
than will fit in the pipe buffer, then DosWrite writes as many bytes as will
fit in the buffer and returns the number of bytes that were actually written.
If a process tries to write to a pipe whose other end is closed,
ERROR_BROKEN_PIPE is returned.
ΓòÉΓòÉΓòÉ 4.3.5. Synchronizing Named Pipe Dialogs ΓòÉΓòÉΓòÉ
Communicating processes can synchronize their named pipe dialogs by calling
DosResetBuffer after each call to DosWrite.
When used with external files, DosResetBuffer flushes the buffer cache of the
requesting process to disk. When used with named pipes, this function blocks
the calling process at one end of the pipe until the data the calling process
has written to the pipe has been successfully read at the other end of the
pipe.
ΓòÉΓòÉΓòÉ 4.3.6. Determining Pipe Status ΓòÉΓòÉΓòÉ
DosQueryNPHState and DosQueryNPipeInfo can be used to obtain information about
named pipes.
DosQueryNPHState
A client process can read data from the pipe, write data to the pipe, or both,
depending on the access mode specified when the pipe was created. To check the
current access mode, the client process can call DosQueryNPHState.
The following code fragment shows how to use DosQueryNPHState to obtain
information about a named pipe:
#define INCL_DOSNMPIPES /* Named-pipe values */
#include <os2.h>
#include <stdio.h>
HPIPE Handle; /* Pipe handle */
ULONG PipeHandleState; /* Pipe-handle state */
APIRET rc; /* Return code */
rc = DosQueryNPHState(Handle, &PipeHandleState);
if (rc != 0) {
printf("DosQueryNPHState error: return code = %ld", rc);
return;
}
On successful return, PipeHandleState will contain information that describes
the nature of the named pipe.
DosQueryNPHState returns the following information about the pipe handle and
the attributes of the pipe:
o The end of the pipe that the handle is for (server or client end)
o The pipe type (byte pipe or message pipe)
o The instance count
o The blocking mode (blocking or nonblocking)
o The read mode (byte-read mode or message-read mode)
The values for pipe type and instance count cannot be changed, so they are
always the same as those that were specified when the pipe was created with
DosCreateNPipe. The information returned for blocking mode and read mode,
however, can come from different sources:
o If the handle is for the server end of the pipe, then the blocking mode
and the read mode were set with DosCreateNPipe, but could have been reset
with DosSetNPHState.
o If the handle is for the client end of the pipe, then the blocking mode
and the read mode were set to "blocking" and "byte-read" by the system
when the client called DosOpen. However, again, they could have been
reset with DosSetNPHState.
The pipe attributes are described in more detail in Creating Named Pipes.
An application can use DosSetNPHState to change the wait mode and the read
mode. The pipe cannot be changed to no-wait mode when another thread is
blocked on a read or write operation to the same end of the pipe.
DosQueryNPipeInfo
More detailed information about a named pipe can be obtained by using
DosQueryNPipeInfo. This function returns information in a PIPEINFO data
structure that includes the name of the pipe, the current and maximum instance
counts (the current number of pipes and the maximum number of times the pipe
can be created), the size of the input and output buffers for the pipe, and
the pipe identifier of the client process.
The following code fragment shows how to use DosQueryNPipeInfo:
#define INCL_DOSNMPIPES /* Named-pipe values */
#include <os2.h>
#include <stdio.h>
HPIPE Handle; /* Pipe handle */
ULONG InfoLevel; /* Pipe data required */
PIPEINFO InfoBuf; /* Pipe information data structure */
ULONG InfoBufSize; /* Pipe data-buffer size */
APIRET rc; /* Return code */
InfoLevel = 1; /* Ask for standard level of pipe info */
InfoBufSize = sizeof(PIPEINFO); /* Length of pipe info data structure */
rc = DosQueryNPipeInfo(Handle, InfoLevel, &InfoBuf, InfoBufSize);
if (rc != 0) {
printf("DosQueryNPipeInfo error: return code = %ld", rc);
return;
}
On successful return, the pipe information data structure contains a set of
information describing the nature and the current state of the named pipe.
DosQueryNPipeInfo returns level 1 or level 2 file information for the pipe.
Level 1 information includes the following:
o The actual sizes of the in-buffer and out-buffer
o The maximum number of pipe instances permitted
o The current number of pipe instances
o The length of the pipe name
o The ASCIIZ name of the pipe, including \\ComputerName if the pipe is in a
remote computer system.
Level 2 information consists of a unique 2-byte identifier for each of
the pipe's client processes.
ΓòÉΓòÉΓòÉ 4.3.7. Examining the Contents of Named Pipes ΓòÉΓòÉΓòÉ
DosPeekNPipe examines the current contents of a named pipe. It is similar to
DosRead, except that DosPeekNPipe does not remove data from the pipe. In
addition, DosPeekNPipe never blocks, even if the pipe is in blocking mode; if
the pipe cannot be accessed immediately, ERROR_PIPE_BUSY is returned.
Because DosPeekNPipe does not block, it returns only what is currently in the
pipe. Thus, if a message pipe is being examined, only a portion of a message
might be returned, even though the specified buffer length could accommodate
the entire message.
DosPeekNPipe also returns the state of the pipe. A named pipe can be in any of
the following states: Connected, Disconnected, Listening, Closing.
The following code fragment shows how to use DosPeekNPipe:
#define INCL_DOSNMPIPES /* Named-pipe values */
#include <os2.h>
#include <stdio.h>
HPIPE Handle; /* Pipe handle */
UCHAR Buffer[200]; /* Address of user buffer */
ULONG BufferLen; /* Buffer length */
ULONG BytesRead; /* Bytes read (returned) */
struct _AVAILDATA BytesAvail; /* Bytes available (returned) */
ULONG PipeState; /* Pipe state (returned) */
APIRET rc; /* Return code */
BufferLen = 200; /* Length of the read buffer */
rc = DosPeekNPipe(Handle, Buffer, BufferLen,
&BytesRead, &BytesAvail, &PipeState);
if (rc != 0) {
printf("DosPeekNPipe error: return code = %ld", rc);
return;
}
On successful return, the input buffer Buffer will contain up to the first 200
bytes from the named pipe, BytesRead will contain the number of bytes read into
Buffer, BytesAvail will contain the total number of bytes that were available
in the pipe, and PipeState will contain a value indicating the state of the
named pipe.
ΓòÉΓòÉΓòÉ 4.3.8. Closing Named Pipes ΓòÉΓòÉΓòÉ
DosClose closes the specified pipe handle. When all of the handles that access
one end of a pipe have been closed, the pipe is referred to as a broken pipe.
If the client end of the pipe closes, no other process can reopen the pipe
until the server calls DosDisConnectNPipe (to acknowledge the client's close)
followed by DosConnectNPipe (to prepare the pipe for a new client). Until it
calls DosDisConnectNPipe, the server will receive ERROR_EOF if it tries to read
from the pipe, and ERROR_BROKEN_PIPE if it tries to write to it. Clients that
attempt to open the pipe receive ERROR_PIPE_BUSY.
If the server end closes when the client end is already closed, the pipe is
deallocated immediately; otherwise, the pipe is not deallocated until the last
client handle is closed.
The following code fragment shows how to close a named pipe. Assume that a
previous call to DosOpen provided the named pipe handle that is contained in
Handle.
#define INCL_DOSNMPIPES /* Named-pipe values */
#include <os2.h>
#include <stdio.h>
HPIPE Handle; /* Pipe handle */
APIRET rc; /* Return code */
rc = DosDisConnectNPipe(Handle);
if (rc != 0) {
printf("DosDisConnectNPipe error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 5. Program Execution Control ΓòÉΓòÉΓòÉ
Multitasking is the ability of the operating system to manage the execution of
more than one application at a time. A multitasking operating system, such as
OS/2, enables users to run many applications simultaneously.
For the programmer, the OS/2 operating system supports two types of
multitasking. An application can start other programs, in separate processes,
that will execute concurrently with the application. These programs can be a
new copy of the application, a related program that is designed to work with
the application, or an unrelated program. Running multiple processes is the
first type of multitasking provided for programmers.
Running multiple threads is the second type of multitasking supported by the
OS/2 operating system. The OS/2 operating system enables applications to run
multiple threads of execution within the same process; separate activities can
be multitasked within the application. An example of multiple-thread
multitasking would be for the application to dispatch a separate subroutine to
load a file from the disk, and have the subroutine execute at the same time the
main program continues to monitor and respond to user input.
This chapter describes processes, threads, and sessions, and the OS/2 functions
used to create and manage them. Additionally, there is a section describing CPU
scheduling.
The following topics are related to the information in this chapter:
o Memory
o Semaphores
o Queues
o Pipes
o Exception Handling
o Debugging
ΓòÉΓòÉΓòÉ 5.1. About Program Execution Control-Thread, Processes, and Sessions ΓòÉΓòÉΓòÉ
To successfully use multitasking-multiple processes and multiple threads-in
your programs, you need to understand the difference between a thread, a
process, and a session.
A thread is a dispatchable unit of execution that consists of a set of
instructions, related CPU register values, and a stack. Each process has at
least one thread, called the main thread or thread 1, and can have many threads
running simultaneously. The application runs when the operating system gives
control to a thread in the process. The thread is the basic unit of execution
scheduling.
A process is the code, data, and other resources-such as file handles,
semaphores, pipes, queues, and so on-of an application in memory. The OS/2
operating system considers every application it loads to be a process. System
resources are allocated on a per-process basis.
A session is one (or more) processes with their own virtual console. (A virtual
console is a virtual screen-either a character-based, full screen or a
Presentation Manager window-and buffers for keyboard and mouse input.)
The OS/2 operating system supports up to 255 concurrent sessions and up to 4095
processes. The operating system supports a system-wide maximum of 4095 threads,
but the number of threads available in a single process will be lower, and will
vary, because of resource usage within the process.
ΓòÉΓòÉΓòÉ 5.1.1. Threads ΓòÉΓòÉΓòÉ
Applications always have at least one thread of execution-thread 1. Using
multiple threads of execution, an application can do several things at the same
time.
For example, a simple Presentation Manager application consists of a single
process with two threads:
o A user interface thread that listens and responds to user requests, and
that queues work for the second thread
o A processing thread that handles lengthy processing
The operating system creates the first thread of execution for a process when
it starts the executable file. To create another thread of execution, a thread
calls DosCreateThread, specifying the address within the program module where
the thread begins asynchronous execution. Although a thread can execute any
part of the application, including a part being executed by another thread,
threads typically are used to execute separate sections of the application. By
using several threads, the system can distribute the available CPU time and
enable an application to carry out several tasks simultaneously. For example,
an application can load a file and prompt the user for input at the same time.
Each thread in a process has a unique stack and register context. Threads
shares the resources of the process with the other threads in the process. For
example, threads in the same process have access to the memory spaces of other
threads within the process. However, threads of one process do not have access
to the data spaces of other processes.
Each thread has a priority, that determines the amount of CPU time the thread
is allocated. Threads inherit the priority of the thread that creates them.
The priority of a thread can be changed by the application; see Changing the
Priority of a Thread for details.
An application can use DosSuspendThread and DosResumeThread to suspend and
resume the execution of a given thread. When an application suspends a thread,
the thread remains suspended until the application calls DosResumeThread.
When an application has more than one thread, it might be necessary to ensure
that one thread is finished executing before another thread uses a shared
resource, such as a disk file. DosWaitThread causes the application to wait
until a specific thread has finished. DosWaitThread can also be used to
determine the state of a thread; the function can return immediately with an
error value if the identified thread is still running.
A thread ends when it calls DosExit.
ΓòÉΓòÉΓòÉ 5.1.2. Processes ΓòÉΓòÉΓòÉ
An OS/2 application that has been loaded into memory and prepared for execution
is called a process. As mentioned earlier, a process consists of the code,
data, and other resources (for example, open file handles) that belong to the
application. Each process has at least one thread, called the main thread or
thread 1.
When the operating system executes an application, it confirms that the process
code and data are in memory and that the main thread's registers and stack are
set before starting the application. Each application has access to all
resources of the computer, such as memory, disk drives, screen, keyboard, and
the CPU itself. The system carefully manages these resources so that
applications can access them without conflict.
A process can have more than one thread. The operating system creates the first
thread of execution for a process when it starts the executable file. More
threads can be created with DosCreateThread. Each thread runs independently,
with its own stack and register values. Unless the application changes a
thread's priority, each thread gets a slice of the CPU in a round-robin
strategy. All the threads in a process share the application's globally defined
variables and other resources (open file handles, and so on).
A process or thread ends when it calls DosExit. The operating system
automatically closes any files or other resources left open by the process when
the process ends. When a thread ends, however, any open resources remain open
until another thread closes them or the process ends. A process can direct the
operating system to carry out other actions when the process ends, by using
DosExitList to create a list of termination functions. The operating system
calls the termination functions, in the order given, when the process is about
to end. If the thread has registered any exception handlers, the exception
handlers will also be called before the thread terminates.
ΓòÉΓòÉΓòÉ 5.1.2.1. Creating Processes ΓòÉΓòÉΓòÉ
An application can load and execute other applications by using DosExecPgm. The
new application, once loaded, is called a child process. The process that
starts the new application is called the parent process.
A child process is like any other process. It has its own code, data, and
threads. The child process inherits the resources-such as file handles, pipes,
and queues-that belong to the parent process at the time the child process is
created, although not necessarily with the same access rights. The parent
process can place restrictions on the access of the child process to these
resources:
o Files are inherited except for files that were opened with no inheritance
indicated.
o Pipes are inherited.
Assuming that the parent process gives the child process appropriate access
rights, the child process can use the inherited resources without preparing
them. For example, if the parent process opens a file for reading and then
starts a child process, the child process can read from the file immediately;
it does not have to open the file. However, once the child process is created
additional resources that the parent process creates are not available to the
child process. Similarly, resources the child process creates are not
available to the parent process.
The parent process also has control over the meanings of standard input,
output, and error for the child process. For example, the parent can write a
series of records to a file, open the file as standard input, open a listing
file as standard output, and then execute a sort program that takes its input
from standard input and writes to standard output.
Note that memory is not included in the list of things that a child process
can inherit from its parent process. The child process is created with its own
process address space that is separate and distinct from the memory of the
parent process. A new linear address space is built for the new process. The
only way for a parent process and a child process to access the same memory is
to set up a shared memory area.
The executable file of the child process can be started either synchronously
or asynchronously to the parent process. If the parent process starts the
child process running synchronously, the parent process is suspended and waits
until the child process ends before continuing. A child process running
asynchronously executes independently of the parent process (that is, both run
at the same time). The parent process specifies how the child process is to
run by setting a parameter in the call to DosExecPgm.
The OS/2 command processor, CMD.EXE, starts most child processes
synchronously. The parent process waits for each child process to end before
it prompts the user for the next command. The command processor also enables
the user to start asynchronous applications by using the DETACH command. When
the user detaches an application, the command processor starts the application
asynchronously, in the background, and continues to prompt for input.
ΓòÉΓòÉΓòÉ 5.1.2.2. Process Termination ΓòÉΓòÉΓòÉ
A parent process can use DosWaitChild to determine the termination status of a
child process that is running independently. The parent process can have one of
its threads call DosWaitChild to wait for completion of the child process while
other threads of the parent continue processing.
If the child has started another process, DosWaitChild waits for the completion
of any grandchild processes before returning, but does not report their status.
If the specified child process has multiple threads, DosWaitChild returns the
result code of the last DosExit request.
If there are no child processes, either active or ended with a return code,
DosWaitChild returns with an error code. If no child processes have terminated,
DosWaitChild can optionally wait until one terminates before returning to the
parent.
ΓòÉΓòÉΓòÉ 5.1.2.3. Process Exit Lists ΓòÉΓòÉΓòÉ
Because any process can terminate any other process for which it has a process
identifier, applications might lose information if a process terminates the
application before it can save its work. To prevent this loss of data, you can
create a list of functions to clean up data and files before the operating
system terminates the process. This list is called an exit list. The operating
system maintains an exit list for each process and calls these functions
whenever the application is terminated, whether by another process or by
itself.
You call DosExitList to add to the exit list a routine that is to be given
control when a process is terminated (or finishes its execution). Multiple
routines can be added to the list. When the process is terminating, the
operating system transfers control to each address on the list.
Exit-list functions perform clean-up operations on resources. For example, an
exit-list function can be used in a dynamic link library module to free
resources or clear flags and semaphores when a client program has ended.
ΓòÉΓòÉΓòÉ 5.1.3. Multitasking with Threads and Multitasking with Processes ΓòÉΓòÉΓòÉ
The creation and termination of a process is relatively slow compared to the
creation and termination of a thread, and is more costly in terms of system
resources.
For example, sharing data and resources between processes requires shared
memory and the mechanisms of interprocess communication; threads, on the other
hand, have full access to the memory and other resources that belong to the
process the threads are part of and can be coordinated using semaphores. For
these reasons, thread-to-thread task context switches are faster than
process-to-process context switches.
Because the operating system can create and execute threads more quickly than
processes, the preferred multitasking method for applications is to distribute
tasks among threads in the same process instead of among processes.
ΓòÉΓòÉΓòÉ 5.1.4. Sessions ΓòÉΓòÉΓòÉ
The OS/2 operating system uses sessions to help the user move from one
application to the next without disrupting the screen display of an
application.
A session consists of at least one process and a virtual console-buffers for
keyboard and mouse input and either a character-based, full screen or a
Presentation Manager window. When the system creates a session, the process in
the session displays output in the screen or window. The user can view the
output and supply input by moving to the session. The user moves to a session
by pressing the Alt+Esc key combination, by selecting the title of the session
from the Window List, or, for windowed sessions, by clicking the mouse in the
session window.
A child session is under the control of the session that creates it. The
session that starts the child session is called the parent session. Any process
in the parent session can exercise control over a child session.
An unrelated session is not under the control of the session that started it.
The process that creates the unrelated session cannot select it, make it
nonselectable, bind it, or terminate it, nor can any other session.
DosStartSession does not even return a session identifier when an unrelated
session is started. Unrelated sessions are controlled entirely by the user.
When the operating system starts new sessions, it starts them as unrelated
sessions.
ΓòÉΓòÉΓòÉ 5.1.4.1. Creating Sessions ΓòÉΓòÉΓòÉ
A process creates a new session by using DosStartSession. DosStartSession
enables an application to start another session and to specify the name of the
application to be started in that session.
DosStartSession also specifies which of the five session types is to be
started:
o Full screen, protect mode
o Text windowed, protect mode
o Presentation Manager (PM)
o Full screen DOS Session
o Windowed DOS Session
Protect mode applications run in full screen and text windowed sessions, PM
and AVIO applications run in PM windows, and DOS applications run in full
screen DOS Sessions and windowed DOS Sessions.
OS/2 applications running in any of the OS/2 session types-full screen, text
windowed, and PM-can start sessions of any other type, including DOS Sessions.
DOS Session applications cannot start other sessions.
An application can start another process in a separate session when the
application will not manage any I/O done by the process. For example, an
application that starts an unrelated application could start it in a separate
session.
A session can be started as a related or an unrelated session. A related
session is called a child session, and the session starting the child session
is called the parent session. An application can control its child sessions by
using the session identifier returned by DosStartSession with the
DosSetSession, DosSelectSession, and DosStopSession. If an application starts
an unrelated session, the new session cannot be controlled by the application.
The Related field in the STARTDATA structure specifies whether the new session
is related to the session calling DosStartSession.
After a process has started a child session, no other process in its session
can start a child session until all dependent sessions started by this process
have ended.
When a session is created, the title specified in the function call (or the
application name if no title is specified) is added to the Window List.
DosStartSession can be used to start either a foreground or a background
session, but a new session can be started in the foreground only when the
caller's session, or one of the caller's descendant sessions, is currently
executing in the foreground. The foreground session for windowed applications
is the session of the application that owns the window focus.
Termination Queues
The parent session must create a termination queue prior to specifying the
queue name in a call to DosStartSession. The operating system will continue to
notify the parent session through the specified queue as long as the session
calling DosStartSession remains a parent session. In other words, when all the
child sessions for a particular parent session terminate, the termination
queue is closed by the operating system. An existing queue name must be
specified on the next DosStartSession call if the caller wants to continue
receiving termination notification messages.
The operating system writes a data element to the specified queue when any
child session terminates. The queue is posted regardless or who terminates the
child session (the child, the parent, or the user) and whether the termination
is normal or abnormal.
A parent session calls DosReadQueue to receive notification when a child
session has terminated. The word that contains the request parameter, returned
by DosReadQueue, will be 0. The data element has the following format:
Termination Queue Element Format
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéSize ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWORD ΓöéSession ID of the child session that terminated Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWORD ΓöéResult code Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The process that originally called the DosStartSession request should call
DosReadQueue, with the NOWAIT parameter set to 0. This is the only process
that has addressability to the notification data element. After reading and
processing the data element, the caller must free the segment containing the
data element by calling DosFreeMem.
When a child session terminates, the result code returned in the termination
queue's data element is the result code of the program specified in the
DosStartSession call, providing
o the program was executed directly, with no intermediate secondary command
processor, or
o the program is executed indirectly through a secondary command processor,
and the /C parameter is specified.
When a child session is running in the foreground at the time it terminates,
the parent session becomes the new foreground session. When a parent session
terminates, any child sessions are terminated. When an unrelated session
terminates in the foreground, the operating system selects the next foreground
session.
ΓòÉΓòÉΓòÉ 5.1.4.2. Child Session Control ΓòÉΓòÉΓòÉ
A session can be either a child session or an unrelated session. A child
session is under the control of the processes in the session that creates it
(the parent session). A process can select, set, or stop a child session by
using DosSelectSession, DosSetSession, or DosStopSession, respectively.
DosStartSession returns a unique session identifier for the child session for
use in these functions.
A session can run in either the foreground or background. A process can create
a foreground session only if the creating process or one of its descendant
sessions is executing in the current foreground session. A process can move a
child session to the foreground by selecting the child session using the
session identifier and calling DosSelectSession. A process can make a child
session nonselectable by using DosSetSession to change the SelectInd field in
the STATUSDATA structure. This prevents the user from selecting the session
from the Window List but does not prevent a process from selecting the child
session by using DosSelectSession.
A process can bind a child session to its own session by using DosSetSession.
Binding a session causes that session to move to the foreground whenever the
user selects the parent session from the Window List.
A parent session can use a session identifier with the DosSetSession function
only if the parent session created the child session associated with that
identifier. It cannot use identifiers for child sessions created by other
parent processes. This is true for all session management functions.
Although a child session is related to the session that started it, the
processes in the child and original sessions are not related. This means that
even though DosStartSession supplies the process identifier of the process in
the child session, the process identifier cannot be used with OS/2 functions
such as DosSetPriority.
ΓòÉΓòÉΓòÉ 5.1.4.3. Child Session Termination ΓòÉΓòÉΓòÉ
A parent session can stop a child session by using DosStopSession. Stopping the
child session terminates the processes in that session. It also stops any
sessions related to the child session. If a child session is in the foreground
when it is stopped, the parent session becomes the foreground session.
DosStopSession breaks any bond that exists between the parent session and the
specified child session.
A process running in the session specified in the call to DosStopSession can
ignore the request to terminate. If this happens, DosStopSession still returns
0 (indicating success). The only way to be certain that the child session has
terminated is to wait for notification through the termination queue specified
in the call to DosStartSession. The operating system writes a data element into
the specified queue when the child session terminates. The process in the
parent session must call DosReadQueue to retrieve this data element, which
contains the session identifier for the child session and the return value for
the process in the child session. Only the process that created the child
session can read the data element.
ΓòÉΓòÉΓòÉ 5.2. About CPU Scheduling ΓòÉΓòÉΓòÉ
The OS/2 operating system performs prioritized, preemptive, multitasking.
Prioritized means that the operating system does not divide CPU time equally
among all threads. All programs do not get equal access to the CPU. A
prioritizing, time-slicing strategy is used to allocate access to the CPU among
competing threads. Each thread has a priority and the operating system runs the
highest priority thread that is ready to run. Programs with higher priorities
(a real-time robotic application, for example), are given access to the CPU
before programs with lower priorities. If a thread with a higher priority than
the currently running thread becomes ready to run, the current thread is
stopped immediately, or preempted, and the higher priority thread is given the
CPU. The lower priority thread does not get to complete its time slice. Threads
of equal priority are given CPU time in a round-robin manner.
Preemptive means that the multitasking activity needs no cooperation from the
executing programs. The operating system maintains control over executing
programs, and stops, or preempts, them when their time slice with the CPU is
over or when a higher priority program is ready to run.
CPU scheduling is based on four priority classes-Time Critical, Fixed-High,
Regular, and Idle-Time. Each class has 32 levels of execution ordering.
Scheduling parameters are user-selectable at the time the system is started or
can be varied dynamically based on system load.
Depending on a thread's priority class and level, the operating system
periodically gives each thread in each process a small slice of CPU time.
Threads with higher priorities always run before threads having lower
priorities. A thread runs until its time is up or until a thread with a higher
priority is ready to run. At that time, the operating system preempts the
thread and starts another thread. Threads can also voluntarily relinquish the
CPU (for example, by calling DosSleep).
The amount of time in each time slice is defined by the TIMESLICE command in
the CONFIG.SYS file. The TIMESLICE command can be used by the user to customize
the size of the time slices that a thread gets. The default is for the
operating system to dynamically vary the size of the time slice based on the
activity of the thread and the overall system load.
When a thread is created (using DosCreateThread), it inherits the priority of
the thread that started it. DosSetPriority enables threads to change their
priority classes and levels in response to changes in their execution
environments. DosSetPriority enables a thread to change its own priority, or
the priority of any thread within its process. DosSetPriority also enables
changing priorities for the entire process and for descendant processes. Within
each class, the priority level of a thread can vary because of a DosSetPriorty
request or, if dynamic priority variation is being used, because of action
taken by the operating system.
ΓòÉΓòÉΓòÉ 5.2.1. Priority Classes ΓòÉΓòÉΓòÉ
The operating system uses four priority classes to determine when a thread
receives a time slice:
Priority Classes
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPriority ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTime-critical ΓöéHighest priority. For use Γöé
Γöé Γöéwhen response time is Γöé
Γöé Γöécritical. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFixed-high ΓöéUsed by threads that provide Γöé
Γöé Γöéservice to other threads. ThisΓöé
Γöé Γöépriority class is to be used Γöé
Γöé Γöéwhen it is desirable that the Γöé
Γöé Γöéthread not be too sensitive toΓöé
Γöé Γöéthe foreground/background Γöé
Γöé Γöéboost provided by dynamic Γöé
Γöé Γöépriority variation. It is Γöé
Γöé Γöémeant for programs that need Γöé
Γöé Γöéto execute before regular Γöé
Γöé Γöéprograms, but without the Γöé
Γöé Γöéimmediate response time Γöé
Γöé Γöérequirement called for by Γöé
Γöé Γöétime-critical threads. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRegular ΓöéDefault priority. Most Γöé
Γöé Γöéthreads belong in this class. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéIdle-time ΓöéLowest priority. This Γöé
Γöé Γöépriority only gets CPU time Γöé
Γöé Γöéwhen there is no other work toΓöé
Γöé Γöédo. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
A time-critical thread always receives a time slice before a fixed-high thread,
a fixed-high thread always receives a time slice before a regular thread, and a
regular thread always receives a time slice before an idle-time thread.
Time-Critical Threads
Time-critical threads have the highest priority class and execute before any
fixed-high, regular, or idle-time threads.
The time-critical class is for threads that must react to events outside the
system. For example, in a communications application, a thread responsible for
reading data from the communications device needs enough time to read all
incoming data. Because more than a regular time slice might be needed, a
time-critical classification ensures that the thread gets all the time
required.
Time-critical threads have a static priority that is not varied by the
operating system. They are scheduled among themselves in priority level order,
with round-robin scheduling of threads of equal priority.
Time-critical threads must be executed quickly, then free the CPU for other
work until another time-critical event occurs. This is important to maintain
good interactive responsiveness to the user and enable communications and other
time critical applications to run concurrently. The time-critical activity
should, when possible, be in a thread separate from the rest of the
application, to isolate and minimize the time spent processing at the
time-critical level. A good rule of thumb is that a time-critical thread should
consist of no more than about 20,000 assembly language instructions.
Fixed-High Threads
A fixed-high thread has a priority class that is lower than time-critical but
executes before any regular or idle-time threads. This class of threads should
be used to provide service for other threads where it is desirable that the
thread not be too sensitive to the foreground/background boost provided by
dynamic priority variation. A messaging thread, would be a good example of this
type of thread.
The operating system varies the priority of a fixed-high thread around a base
value according to the activity of the thread and the system at any point in
time. The base value can be set by the thread itself.
Regular Threads
A regular thread is the class that the majority of threads fall into. No
explicit action is necessary by the application to run at this priority, it is
the default.
The operating system varies the priority level of a regular thread around a
base value according to the activity of the thread and the system at any point
in time. The base value can be set by the thread itself.
Idle-Time Threads
An idle-time thread is one with very low priority that executes only when there
are no regular, fixed-high, or time-critical threads to execute. Idle-time
threads get CPU time only when there is no other work to do. The idle-time
class is for threads that need very little CPU time.
Idle-time threads have a static priority that is not varied by the operating
system.
ΓòÉΓòÉΓòÉ 5.2.2. Priority Levels ΓòÉΓòÉΓòÉ
Within each class, the operating system maintains a priority level for a
thread. For each of the four priority classes, there are 32 priority levels-0
to 31. A thread with priority level 31 always receives a time slice before a
thread with priority level 30, and so on.
If two or more threads have the same priority level, the operating system
distributes the CPU time equally by using a round-robin scheme; that is, the
operating system gives a time slice to first one, then another, and so on, and
then goes back to the first. A thread can use DosSetPriority to change its own
priority or the priority of any other thread within its process.
Although an application can set the priority level of a thread at any time,
only applications that use more than one thread or process should do so. The
best use of priority is to speed up threads or processes on which other threads
or processes depend. For example, an application might temporarily raise the
priority of a thread loading a file if another thread is waiting for that file
to be loaded. Because the priority of a thread is relative to all other threads
in the system, raising the priority of the threads in an application merely to
get the extra CPU time adversely affects the overall operation of the system.
There are other ways to affect the amount of CPU time a thread is given. A
thread can define a critical section of code by using DosEnterCritSec and
DosExitCritSec. While inside the critical section of code, a thread cannot be
preempted by any other thread within its process (threads in other processes
are still given their time slices). Using critical sections enables threads to
get more CPU time, while not unduly affecting the rest of the system.
The priority class and priority level are set using DosSetPriority. The
priority class is changed by passing the new priority class to the function.
The priority level, however, is changed by passing a value, called the
priority-delta, that is added to the existing priority level to produce the new
priority level; changes to the priority level are relative to the current
priority level. Specifying a positive priority-delta increases the priority
level, enabling the thread to obtain more CPU time than it normally would. A
negative priority-delta decreases the priority level, giving the thread less
CPU time than it would normally receive. The value is restricted to the valid
range, based upon the current priority class of the process.
If you change the priority level without changing the priority class, the
priority-delta is relative to the current priority level. However, if you
change the priority class at the same time that you change the priority level,
the priority-delta value is relative to 0. Whenever DosSetPriority is called
with a class specification, but no value is specified for priority-delta, the
base priority level defaults to 0.
The process identifier parameter of DosSetPriority specifies which process is
affected by the call. A process can change the priority of itself, of any
process that is a descendant of itself, or of one of its threads.
A thread can change the priority of any thread within its current process. When
a thread changes the priority of threads in a descendant process, however, only
those threads running at the default priority will be changed. You cannot
change the priority of a thread in a child process that has already changed its
priority from the default.
The initial thread of execution for an application is given a regular class
priority that varies by the system. When a thread is created, it is initially
dispatched in the same class and priority as the thread that started it. A
child process inherits the priority of the thread in the parent process that
creates it.
ΓòÉΓòÉΓòÉ 5.2.3. Priority Guidelines ΓòÉΓòÉΓòÉ
Within the two most common priority classes-time-critical and regular-there are
certain broad guidelines recommended for choosing the priority level for a
program.
o TIME-CRITICAL CLASS
The guidelines for level within the time critical class are set to
maximize the number of different applications that can successfully
multitask in an OS/2 system. The guidelines are described in the
following table.
Recommended Priority Levels for Time-Critical Threads
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéActivity ΓöéRange of ΓöéJustification/Comments Γöé
Γöé ΓöéRecommended Γöé Γöé
Γöé ΓöéPriority Γöé Γöé
Γöé ΓöéLevels Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRobotics/RealΓöé20-31 ΓöéOS/2 systems can be used on Γöé
Γöétime process Γöé Γöémanufacturing lines to controlΓöé
Γöécontrol Γöé Γöéequipment or in other real Γöé
Γöé Γöé Γöétime process control Γöé
Γöé Γöé Γöéapplications. In this case a Γöé
Γöé Γöé Γöéslow response from the PC Γöé
Γöé Γöé Γöécould cause expensive damage Γöé
Γöé Γöé Γöéto equipment or even human Γöé
Γöé Γöé Γöéinjury. Therefore the highest Γöé
Γöé Γöé Γöépriority levels should be Γöé
Γöé Γöé Γöéreserved for these Γöé
Γöé Γöé Γöéapplications. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCommunicationΓöé10-19 ΓöéIn communications, the Γöé
Γöé Γöé Γöéinability to get the processorΓöé
Γöé Γöé Γöécould cause a loss of data or Γöé
Γöé Γöé Γöécommunications sessions. Γöé
Γöé Γöé ΓöéTherefore this class of Γöé
Γöé Γöé Γöéapplications is next highest. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéOther Γöé0-09 ΓöéOther threads might need to Γöé
Γöé Γöé Γöépreempt the foreground in Γöé
Γöé Γöé Γöéspecial cases (for example, Γöé
Γöé Γöé ΓöéControl-Break). These should Γöé
Γöé Γöé Γöébe set below the other 2 Γöé
Γöé Γöé Γöéclasses. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
In general, application performance is not a good reason to make a thread
time critical.
o REGULAR CLASS
In cases where explicit priority levels are set, they should follow the
guidelines listed below.
Recommended Priority Levels for Regular Priority Threads
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéActivity ΓöéRange of ΓöéJustification Γöé
Γöé ΓöéRecommended Γöé Γöé
Γöé ΓöéPriority Γöé Γöé
Γöé ΓöéLevel Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCommunicationΓöé26-31 ΓöéCommunications should take Γöé
Γöé Γöé Γöépriority over other backgroundΓöé
Γöé Γöé Γöéprocessing to increase overlapΓöé
Γöé Γöé Γöéwith transmission and Γöé
Γöé Γöé Γöéprocessing on the partner PC Γöé
Γöé Γöé Γöéor host. This gives the best Γöé
Γöé Γöé Γöésystem performance. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéOther Γöé0-25. ΓöéIf an application has multipleΓöé
Γöé Γöé Γöéthreads it might be necessary Γöé
Γöé Γöé Γöéto set them to several Γöé
Γöé Γöé Γöédifferent priorities to Γöé
Γöé Γöé Γöéoptimize the order in which Γöé
Γöé Γöé Γöéthey run. A range of priority Γöé
Γöé Γöé Γöélevels is provided to Γöé
Γöé Γöé Γöéfacilitate this. (The default Γöé
Γöé Γöé Γöépriority is regular class, Γöé
Γöé Γöé Γöélevel = 0.) Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 5.2.4. Dynamic Priority Alteration ΓòÉΓòÉΓòÉ
The operating system can be configured to dynamically alter the priority of a
process. The PRIORITY statement in CONFIG.SYS can be set to either ABSOLUTE or
DYNAMIC. If PRIORITY specifies the ABSOLUTE option, all processes receive CPU
time based on the priority established by calls to DosSetPriority. If the
PRIORITY command in the CONFIG.SYS file specifies the DYNAMIC option, the
operating system adjusts process priorities based on system load and process
activity, and on whether the process is in the foreground. DYNAMIC is the
default setting; if the PRIORITY command is not specified, the system uses
DYNAMIC priority. DYNAMIC is designed to gives the best overall system
performance under most conditions.
When dynamic priority variation is enabled, the operating system grants higher
priority to the foreground process than to background processes. System load
and process activity are also taken into consideration. The priority of the
process consists of a computed priority value that is based upon the display
status of the process (foreground or background), and its recent I/O and CPU
time usage history. When dynamic priority variation is enabled, I/O priority
boosts are generated for keyboard input, window, foreground, processor
starvation, device I/O, and DOS Session interrupts. This ensures that the
foreground process-the process most likely to be in use-receives enough CPU
time to provide quick response to user input.
There are times when dynamic priority variation can interfere with a
multi-threaded application's execution. For example, if you are doing a lot of
keyboard input on a thread, its priority will get boosted and other threads may
not get enough CPU time. A communication thread is an example of a time
sensitive background thread which would be one case. The solution is to either
set PRIORITY = ABSOLUTE or to call DosSetPriority on a regular basis to keep
the threads priority at the desired level.
ΓòÉΓòÉΓòÉ 5.2.5. Altering the Size of the Time Slice ΓòÉΓòÉΓòÉ
The TIMESLICE command in CONFIG.SYS sets the minimum and maximum amount of
processor time allocated to processes and programs for both OS/2 and DOS
sessions.
The first parameter selects the minimum TIMESLICE value in milliseconds. This
value is the minimum amount of time a thread is to be processed before yielding
the processor to a thread of the same priority level. This value must be an
integer greater than or equal to 32.
The second parameter selects the maximum TIMESLICE value in milliseconds. The
value of this parameter is the maximum amount of time a thread can be processed
before yielding processor time. This value must be an integer greater than or
equal to the minimum value, and less than 65536.
The default is dynamic time slicing, which varies the size of the time slice
depending on system load and paging activity. Dynamic time slicing is designed
to give the best performance in most situations.
ΓòÉΓòÉΓòÉ 5.3. Using Processes ΓòÉΓòÉΓòÉ
An OS/2 application that has been loaded into memory and prepared for execution
is called a process. A process is the code, data, and other resources of the
application, such as the open file handles, semaphores, pipes, queues and so
on. The OS/2 operating system considers every application it loads to be a
process.
Each process has at least one thread, called the main thread or thread 1. The
application runs when the system scheduler gives control to a thread in the
process. For more on thread management, see Using Threads.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 5.3.1. Starting a Child Process ΓòÉΓòÉΓòÉ
You start a process by calling DosExecPgm. The process you start is a child of
the calling, or parent, process and inherits many of the resources owned by the
parent process, such as file handles.
DosExecPgm creates a process environment from an executable file. The target
program is loaded into storage, and it begins execution.
The following code fragment starts an application named ABC:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
CHAR szFailName[CCHMAXPATH];
RESULTCODES resc;
DosExecPgm(szFailName, /* Object-name buffer */
sizeof(szFailName), /* Length of buffer */
EXEC_SYNC, /* Sync flag */
(PSZ) NULL, /* Argument string */
(PSZ) NULL, /* Environment string */
&resc, /* Address for result */
"ABC.EXE"); /* Name of application */
In this example, ABC runs synchronously (as specified by EXEC_SYNC). This means
the parent process temporarily stops while the child process runs. The parent
process does not continue until the child process ends.
ΓòÉΓòÉΓòÉ 5.3.1.1. Starting an Asynchronous Child Process ΓòÉΓòÉΓòÉ
To start a child process and enable it to run asynchronously (that is, without
suspending the parent process until the child process ends), you use the
EXEC_ASYNC constant in a call to DosExecPgm. If you start a process in this
way, the function copies the process identifier of the child process to the
codeTerminate field of the RESULTCODES structure that is returned by
DosExecPgm. You can use this process identifier to check the progress of the
child process or to terminate the process.
You can also run a child process asynchronously by using DosExecPgm with the
EXEC_ASYNCRESULT constant. In addition to causing DosExecPgm to return to the
parent process immediately, this constant also directs the operating system to
save a copy of the termination status when the child process terminates. This
status specifies the reason the child process stopped. The parent process can
retrieve the termination status by using DosWaitChild.
The following code fragment starts the program SIMPLE.EXE, and then waits for
it to finish. It then prints the termination code and the return code.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
#define START_PROGRAM "SIMPLE.EXE"
CHAR LoadError[100];
PSZ Args;
PSZ Envs;
RESULTCODES ReturnCodes;
APIRET rc;
rc = DosExecPgm(LoadError, /* Object name buffer */
sizeof(LoadError), /* Length of object name buffer */
EXEC_SYNC, /* Asynchronous/Trace flags */
Args, /* Argument string */
Envs, /* Environment string */
&ReturnCodes, /* Termination codes */
START_PROGRAM); /* Program file name */
printf("Termination Code %d Return Code %d \n",
ReturnCodes.codeTerminate,
ReturnCodes.codeResult);
----------------SIMPLE.EXE------------------
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
#define RETURN_CODE 0
main()
{
printf("Hello!\n");
DosExit(EXIT_PROCESS, /* End the thread or process */
RETURN_CODE); /* Result code */
}
ΓòÉΓòÉΓòÉ 5.3.1.2. Starting a Background Process ΓòÉΓòÉΓòÉ
You can start a child process in the background by specifying the
EXEC_BACKGROUND constant in DosExecPgm. A background process runs independently
of the parent process and is called a detached process. A detached process
should not require any input from the keyboard or output to the video screen,
but it can use interprocess communication, such as pipes, queues, and shared
memory.
The following code fragment starts the program BATCH.EXE in the background.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
#define START_PROGRAM "BATCH.EXE"
CHAR LoadError[100];
PSZ Args;
PSZ Envs;
RESULTCODES ReturnCodes;
APIRET rc;
rc = DosExecPgm(LoadError, /* Object name buffer */
sizeof(LoadError), /* Length of object name buffer */
EXEC_BACKGROUND, /* Asynchronous/Trace flags */
Args, /* Argument string */
Envs, /* Environment string */
&ReturnCodes, /* Termination codes */
START_PROGRAM); /* Program file name */
if (rc != 0) {
printf("DosExecPgm error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 5.3.1.3. Setting the Command Line and Environment for a Child Process ΓòÉΓòÉΓòÉ
When you start a process, it inherits many of the resources of the parent. This
includes file handles, such as the standard input and standard output files. A
child process also inherits the resources of the screen group, such as the
mouse and video modes, and the environment variables of the parent process.
The call to DosExecPgm determines the command line and environment that the
child process receives. The fourth and fifth parameters of the function are
pointers to the command line and the environment, respectively. If these
pointers are NULL, the child process receives nothing for a command line and
only an exact duplicate of the environment of the parent process. The parent
process can modify this information by creating a string (ending with two NULL
characters) and passing the address of the string to the function. The command
line string must include the name of the application, followed by a NULL
character, and the command line arguments, followed by two NULL characters. Any
number of arguments can be passed to the child process, as long as the argument
string ends with two NULL characters.
The following code fragment passes to the child process the string "test
-option1 -option2" as its command line:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
RESULTCODES resc;
CHAR szFailName[CCHMAXPATH];
CHAR szCommandLine[] = "test\0-option1 -option2\0";
DosExecPgm(szFailName, /* Object-name buffer */
sizeof(szFailName), /* Length of buffer */
EXEC_SYNC, /* Sync flag */
szCommandLine, /* Argument string */
(PSZ) NULL, /* Environment string */
&resc, /* Address of result */
"test.exe"); /* Name of application */
ΓòÉΓòÉΓòÉ 5.3.2. Changing the Priority of a Process ΓòÉΓòÉΓòÉ
Changing the priority of a process is simply a matter of changing the priority
of every thread executing in the process. For the details see the section on
changing thread priorities, Changing the Priority of a Thread.
ΓòÉΓòÉΓòÉ 5.3.3. Obtaining Information about Child Processes ΓòÉΓòÉΓòÉ
The operating system creates and maintains a Process Information Block for
every process. An application can use DosGetInfoBlocks to access the Process
Information Block. This function returns a pointer to a PIB data structure,
which contains the information from the Process Information Block.
The following code fragment returns the address of the Process Information
Block of the current process. The calling thread can subsequently browse either
the PIB block.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
PTIB ptib; /* Address of pointer to Thread Information Block */
PPIB ppib; /* Address of pointer to Process Information Block */
APIRET rc; /* Return code */
rc = DosGetInfoBlocks(&ptib, &ppib);
DosGetInfoBlocks also returns the address of the Thread Information Block of
the current thread.
ΓòÉΓòÉΓòÉ 5.3.4. Waiting for a Child Process to Terminate ΓòÉΓòÉΓòÉ
You can synchronize the execution of a process with the execution of one of its
child processes by calling DosWaitChild. DosWaitChild does not return until the
specified child process terminates. This can be useful, for example, if the
parent process needs to ensure that the child process has completed its task
before the parent process continues with its own task.
In the following code fragment, the parent process starts a child process and
then waits for the child process to finish:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
RESULTCODES resc;
PID pidEnded;
CHAR szFailName[CCHMAXPATH];
CHAR szCommandLine[] = "APP\0test\0";
DosExecPgm(szFailName, /* Failed-name buffer */
sizeof(szFailName), /* Length of buffer */
EXEC_ASYNC, /* Sync flag */
szCommandLine, /* Argument string */
(PSZ) NULL, /* Environment string */
&resc, /* Address of result */
"APP.EXE"); /* Name of application */
DosWaitChild(DCWA_PROCESS, /* Only the process */
DCWW_WAIT, /* Waits until it is done */
&resc, /* Puts the result here */
&pidEnded, /* PID of ended process */
resc.codeTerminate); /* Child to wait for */
You can cause a process to wait for all its child processes to end by using the
DCWA_PROCESSTREE constant in the call to DosWaitChild.
ΓòÉΓòÉΓòÉ 5.3.5. Ending the Current Process ΓòÉΓòÉΓòÉ
You terminate the current process by calling DosExit. When you exit, the system
stops the process and frees any existing resources the process owns.
In the following code fragment, DosExit is used to terminate the process if the
given file does not exist:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#define HF_STDERR 2 /* Standard error handle */
HFILE hf;
ULONG ulAction, cbWritten;
APIRET rc;
rc = DosOpen("SAMPLE.TXT", &hf, &ulAction, 0, FILE_NORMAL,
FILE_OPEN, OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, (PEAOP2) NULL);
if (rc) {
DosWrite(HF_STDERR, "Cannot open file\r\n", 18, &cbWritten);
DosExit(EXIT_PROCESS, rc);
}
EXIT_PROCESS directs DosExit to terminate all the threads in a process
including the calling thread, thus terminating the process. DosExit includes an
error value that is returned to the parent process through the RESULTCODES
structure specified in the DosExecPgm call that started the process. If you
started the application from the command line, the command processor, CMD.EXE,
makes this value available through the ERRORLEVEL variable. If another process
started the application, that process can call DosWaitChild to determine the
error value.
If you want to exit only from a given thread, you can call DosExit with the
EXIT_THREAD constant. This will terminate only the calling thread; other
threads in the process are not affected. If the thread you terminate is the
last thread in the process, the process also terminates. If the thread consists
of a function, the thread terminates when the function returns.
ΓòÉΓòÉΓòÉ 5.3.6. Terminating a Process ΓòÉΓòÉΓòÉ
A process can terminate the execution of a descendant process by calling
DosKillProcess. This causes the operating system to send a XCPT_SIGNAL_KILLPROC
exception to the target process. The child processes of the target process can
also be terminated.
The following code fragment terminates the specified process and all child
processes belonging to that process:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
PID pidProcess;
DosKillProcess(DKP_PROCESSTREE, pidProcess);
In this example, the pidProcess parameter specifies which descendant process to
terminate. The process identifier is returned by DosExecPgm in the
codeTerminate field of the RESULTCODES structure when you start the child
process.
The parameter DKP_PROCESSTREE in the example indicates that the specified
process, pidProcess, and all of its descendant processes are to be terminated.
If you specify DKP_PROCESS in a call to DosKillProcess, only the specified
process is terminated. Its child processes, if any, continue to run.
The process to be terminated must either be the current process, or it must
have been directly created by the current process with DosExecPgm for
asynchronous execution. That is, a process can terminate itself and its
descendants.
The process to be terminated need not still be executing. If it has started its
own child processes, but has stopped executing, its children can still be
flagged for termination.
Obtaining the Termination Status of a Child Process
The operating system saves the termination status for a process if the process
was started by using the EXEC_ASYNCRESULT constant in the call to DosExecPgm.
You can retrieve the termination status of the most recently terminated process
by using the DCWW_NOWAIT constant with DosWaitChild and setting the child
process identification parameter to 0. The DCWW_NOWAIT constant directs the
function to return immediately, without waiting for a process to end. Instead,
the function retrieves the termination status from the process that most
recently ended. If you specify a child process identification with DCWW_NOWAIT,
DosWaitChild returns ERROR_CHILD_NOT_COMPLETE if the child process has not
terminated. Once the specified process has ended, DosWaitChild returns its
termination code.
The following code fragment starts a child session (the program SIMPLE.EXE),
and then retrieves the termination status from the process that most recently
ended.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
#define START_PROGRAM "SIMPLE.EXE"
CHAR LoadError[100];
PSZ Args;
PSZ Envs;
RESULTCODES ReturnCodes;
ULONG Pid; /* Process ID (returned) */
ULONG Target; /* Process ID of process to wait for */
APIRET rc; /* Return code */
strcpy(Args, "-a2 -l"); /* Pass arguments "-a2" and "-l" */
Target = 0; /* Process ID for the most recently terminated process */
rc = DosExecPgm(LoadError, /* Object name buffer */
sizeof(LoadError), /* Length of object name buffer */
EXEC_ASYNCRESULT, /* Asynchronous/Trace flags */
Args, /* Argument string */
Envs, /* Environment string */
&ReturnCodes, /* Termination codes */
START_PROGRAM); /* Program file name */
if (rc != 0) {
printf("DosExecPgm error: return code = %ld", rc);
return;
}
rc = DosWaitChild(DCWA_PROCESS, /* Execution options */
DCWW_NOWAIT, /* Wait options */
&ReturnCodes, /* Termination codes */
&Pid, /* Process ID (returned) */
Target); /* Process ID of process to wait for */
if (rc != 0) {
printf("DosWaitChild error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 5.3.7. Creating an Exit List ΓòÉΓòÉΓòÉ
You call DosExitList to add to the exit list a routine that is to be given
control when a process is terminated (or finishes its execution). Multiple
routines can be added to the list. When the process is terminating, the
operating system transfers control to each address on the list.
If there are multiple addresses on the list, each function gets control in
numerical order (with 0 being first and 0FFH being last), based on a value
supplied by the application when it calls DosExitList. In case of duplicate
entries for this parameter, the routines will be executed in LIFO (last in,
first out) order.
DosExitList requires a function code that specifies an action and a pointer to
the function that is to receive control upon termination.
The following code fragment adds the locally defined function SaveFiles to the
exit list:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#define HF_STDOUT 1 /* Standard output handle */
VOID main(VOID)
{
.
.
.
DosExitList(EXLST_ADD, (PFNEXITLIST) SaveFiles);
.
.
.
DosExit(EXIT_PROCESS, 0);
}
VOID APIENTRY SaveFiles(ULONG ulTermCode)
{
ULONG cbWritten;
switch (ulTermCode) {
case TC_EXIT:
case TC_KILLPROCESS:
DosWrite(HF_STDOUT, "Goodbye\r\n", 10, &cbWritten);
break;
case TC_HARDERROR:
case TC_TRAP:
break;
}
DosExitList(EXLST_EXIT, 0);
}
Any function that you add to the list must take one parameter. The function can
carry out any task, as shown in the preceding example, but as its last action
it must call DosExitList, specifying the EXLST_EXIT constant. An exit-list
function must not have a return value and must not call DosExit to terminate.
When an exit-list routine receives control, the parameter (located at ESP+4 on
the stack) contains an indicator of why the process ended. The values returned
are the same as those for termination codes returned by DosWaitChild or
DosExecPgm requests. These values are:
TC_EXIT (0) Normal exit
TC_HARDERROR (1) Hard-error halt
TC_TRAP (2) Trap operation for a 16-bit child process
TC_KILLPROCESS (3) Unintercepted DosKillProcess
TC_EXCEPTION (4) Exception operation for a 32-bit child process
To execute the exit-list functions, the operating system reassigns thread 1
after terminating all other threads in the process. If thread 1 has already
exited (for example, if it called DosExit without terminating other threads in
the process), the exit-list functions cannot be executed. In general, it is
poor practice to terminate thread 1 without terminating all other threads.
Before transferring control to the termination routines, the operating system
resets the stack to its initial value. Transfer is by way of an assembly
language JMP instruction. The routine must be in the address space of the
terminating process. The termination routine at that address takes the
necessary steps and then calls DosExitList with FunctionOrder=EXLST_EXIT.
Control is then transferred to the next address in the invocation order of the
exit list. When all such addresses have been processed, the process completes
exiting. If a routine on the list does not call DosExitList at the completion
of its processing, the process waits, and the operating system prevents
termination.
During DosExitList processing, the process is in a state of partial
termination. All threads of the process are terminated, except for the one
executing the exit-list routines. To ensure good response to a user request to
end a program, there should be minimal delay in completing termination.
Termination routines should be short and fail-safe.
You can use DosExitList with the EXLST_REMOVE constant to remove a function
from the list.
The designer of an exit-list routine must carefully consider which functions
will be used by the routine. In general, calls to most OS/2 functions are
valid in a DosExitList routine, but certain functions, such as DosCreateThread
and DosExecPgm, are not.
ΓòÉΓòÉΓòÉ 5.4. Using Threads ΓòÉΓòÉΓòÉ
A thread is a dispatchable unit of execution that consists of a set of
instructions, related CPU register values, and a stack. Every process has at
least one thread and can have many threads running at the same time. The
application runs when the operating system gives control to a thread in the
process. The thread is the basic unit of execution scheduling.
Every process has at least one thread, called the main thread or thread 1. To
execute different parts of an application simultaneously, you can start several
threads.
A new thread inherits all the resources currently owned by the process. This
means that if you opened a file before creating the thread, the file is
available to the thread. Similarly, if the new thread creates or opens a
resource, such as another file, that resource is available to the other threads
in the process.
ΓòÉΓòÉΓòÉ 5.4.1. Creating a Thread ΓòÉΓòÉΓòÉ
You use DosCreateThread to create a new thread for a process.
DosCreateThread requires the address of the code to execute and a variable to
receive the identifier of the thread. The address of the code is typically the
address of a function that is defined within the application.
You can pass one ULONG parameter to the thread when you start it. To pass more
information to the thread, pass the address of a data structure.
You specify how you want the thread to run when you call DosCreateThread. If
bit 1 of the flag parameter in the function call is 0, the thread starts
immediately. If bit 1 of the flag parameter is 1, the thread starts suspended
and will not run until the application calls DosResumeThread.
Each thread maintains its own stack. You specify the size of the stack when you
call DosCreateThread. The amount of space needed depends on a number of
factors, including the number of function calls the thread makes and the number
of parameters and local variables used by each function. If you plan to call
OS/2 functions, a reasonable stack size is 8192 bytes (8KB); 4096 bytes (4KB)
should be the absolute minimum. If bit 1 of the flag parameter is 0, the
operating system uses the default method for initializing the thread's stack.
If bit 1 of the flag parameter is 1, memory for the thread's entire stack is
pre-committed.
The following code fragment creates a thread:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#define HF_STDOUT 1 /* Standard output handle */
VOID main(VOID)
{
ULONG ulBeepLen;
TID tidThread;
ulBeepLen = 1000;
.
DosCreateThread(&tidThread, /* Thread ID returned by DosCreateThread */
ThreadFunc, /* Address of the thread function */
ulBeepLen, /* Parameter passed to thread */
0, /* Immediate execution, default stack */
/* initialization */
4096); /* Stack size */
.
.
.
DosExit(EXIT_PROCESS, 0);
}
VOID ThreadFunc(ULONG ulBeepLen)
{
DosBeep(750, ulBeepLen);
DosWrite(HF_STDOUT, "Message from new thread\r\n", 25, 0);
}
A thread continues to run until it calls DosExit, returns control to the
operating system, or is terminated by a DosKillThread call.
In the preceding example, the thread exits when the function implicitly returns
control at the end of the function.
ΓòÉΓòÉΓòÉ 5.4.2. Obtaining Information about a Thread ΓòÉΓòÉΓòÉ
The operating system creates and maintains a Thread Information Block for each
thread. An application can use DosGetInfoBlocks to access the Thread
Information Block. This function returns a pointer to a TIB data structure.
The following code fragment returns the address of the Thread Information Block
of the current thread. The calling thread can subsequently browse the TIB
control block.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
PTIB ptib; /* Address of pointer to Thread Information Block */
PPIB ppib; /* Address of pointer to Process Information Block */
APIRET rc; /* Return code */
rc = DosGetInfoBlocks(&ptib, &ppib);
DosGetInfoBlocks also returns the address of the Process Information Block of
the current process.
ΓòÉΓòÉΓòÉ 5.4.3. Changing the Priority of a Thread ΓòÉΓòÉΓòÉ
You can use DosSetPriority to change the execution priority of threads in a
process. The execution priority defines when or how often a thread receives an
execution time slice. Threads with higher priorities receive time slices before
those with lower priorities. When a thread that is higher in priority than the
currently running thread becomes ready to run, it immediately preempts the
lower priority thread (the lower priority thread does not get to complete its
time slice). Threads with equal priority receive time slices in a round-robin
order. If you raise the priority of a thread, the thread is executed more
frequently.
You can use DosSetPriority to set the priority for one thread in a process, for
all threads in a process (and thus the process itself), or for threads in a
child process.
A process can change the priority of any thread within itself. When a process
changes the priority of threads in a descendant process, however, only those
with default priorities are changed. The priority of any thread in a descendant
process that has already explicitly changed its priority from the default with
DosSetPriority is not changed.
In the following code fragment, DosSetPriority lowers the priority of a process
to be used as a background process:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
PTIB ptib; /* Thread Information Block */
PPIB ppib; /* Process Information Block */
DosGetInfoBlocks(&ptib, &ppib);
DosSetPriority(PRTYS_PROCESSTREE, PRTYC_IDLETIME, 0, ppib->pib_ulpid);
DosGetInfoBlocks retrieves the Process Information Blocks and Thread
Information Blocks. DosSetPriority then uses the process identifier to change
the priority to idle time (idle-time processes receive the least attention by
the operating system).
If you specify PRTYS_PROCESS when calling DosSetPriority, only the priority of
the specified process changes. The priorities of all child processes remain
unchanged.
If you specify PRTYS_THREAD in the call to DosSetPriority, you must specify a
thread identifier as the last parameter. The priority of the specified thread
changes, but the priorities of all other threads in the process remain
unchanged.
Whenever DosSetPriority is called with a class specification, but no value is
specified for priority-delta, the base priority level defaults to 0.
ΓòÉΓòÉΓòÉ 5.4.4. Suspending the Current Thread ΓòÉΓòÉΓòÉ
You can temporarily suspend the execution of the current thread for a set
amount of time by using DosSleep. This function suspends execution of the
thread for the specified number of milliseconds. DosSleep is useful when you
need to delay the execution of a task. For example, you can use DosSleep to
delay a response when the user presses a DIRECTION key. The delay provides the
user with enough time to observe the results and release the key.
The following code fragment uses DosSleep to suspend execution of a thread for
1000 milliseconds (1 second):
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
DosSleep(1000);
ΓòÉΓòÉΓòÉ 5.4.5. Suspending and Resuming Execution of a Thread ΓòÉΓòÉΓòÉ
DosSuspendThread and DosResumeThread are used to temporarily suspend the
execution of a thread when it is not needed and resume execution when the
thread is needed.
These functions are best used when it is necessary for a process to temporarily
suspend execution of a thread that is in the middle of a task. For example,
consider a thread that opens and reads files from a disk. If other threads in
the process do not require input from these files, the process can suspend
execution of the thread so that the operating system does not needlessly grant
control to it.
The specified thread might not be suspended immediately if it has some system
resources locked that must be freed first. However, the thread is not permitted
to execute further application program instructions until a corresponding
DosResumeThread is called.
A thread can only suspend another thread that is within its process.
DosResumeThread is used to enable the suspended thread to resume execution.
The following code fragment temporarily suspends the execution of another
thread within the same process. A subsequent call to DosResumeThread restarts
the suspended thread. Assume that the thread identifier of the target thread
has been placed int ThreadID already.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
TID ThreadID; /* Thread identifier */
APIRET rc; /* Return code */
rc = DosSuspendThread(ThreadID);
if (rc != 0) {
printf("DosSuspendThread error: return code = %ld", rc);
return;
}
rc = DosResumeThread(ThreadID);
if (rc != 0) {
printf("DosResumeThread error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 5.4.6. Entering Critical Sections ΓòÉΓòÉΓòÉ
A thread can prevent execution of any of the other threads in its process by
calling DosEnterCritSec.
This function temporarily prevents a thread from being preempted by other
threads within its process. The other threads in the process will not be
executed until the current thread calls DosExitCritSec. This enables the
calling thread to access a time-critical resource of the process.
The following code fragment enters a section that will not be preempted,
performs a simple task, and then exits quickly.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
BOOL flag; /* Program control flag */
APIRET rc; /* Return code */
rc = DosEnterCritSec();
if (rc != 0) {
printf("DosEnterCritSec error: return code = %ld", rc);
return;
}
flag = TRUE; /* Set the flag */
rc = DosExitCritSec();
if (rc != 0) {
printf("DosExitCritSec error: return code = %ld", rc);
return;
}
A count is maintained of the outstanding DosEnterCritSec requests. The count is
incremented when a DosEnterCritSec request is made, and decremented when a
DosExitCritSec request is made. A DosExitCritSec request will not cause normal
thread dispatching to be restored while the count is greater than 0.
This count is maintained in a WORD-sized variable. If overflow occurs, the
count is set to its maximum value, and an error is returned. The operation is
not performed when this occurs.
Threads that call DosEnterCritSec must not must not make dynamic link calls
within these critical sections. The dynamic link procedure could be using
semaphores to serialize a resource. If a thread entering the critical section
blocks another thread that already owns the resource which the dynamic link
function is about to request, a deadlock occurs.
For example, threads of an application are serializing their access to a queue
by means of a semaphore. A thread enters a critical section and makes a request
to read the queue while another thread already has the semaphore that controls
access to the queue. The thread that has the semaphore is now effectively
blocked by DosEnterCritSec, and the thread that has requested the queue waits
forever to access it.
Note: Thread 1 is the initial thread of execution. It handles all signals
(Ctrl+C, Ctrl+Break, and KillProcess). If a signal occurs while
DosEnterCritSec is active, thread 1 can begin execution to process the
signal. Thread 1 must not access the critical resource that is being
protected by the use of DosEnterCritSec.
ΓòÉΓòÉΓòÉ 5.4.7. Waiting for a Thread to Terminate ΓòÉΓòÉΓòÉ
An application might need to ensure that one thread has finished executing
before another thread continues with its own task. For example, one thread
might have to finish reading a disk file into memory before another thread can
use the information. You can use DosWaitThread to suspend a thread until
another thread has terminated.
DosWaitThread places the current thread into a wait state until another thread
in the current process has terminated. It then returns the thread identifier of
the terminating thread.
The following code fragment creates three threads. The thread identifier for
each thread is returned by DosCreateThread in the atid array. Using &atid[0] as
a parameter in the call to DosWaitThread causes the operating system to wait
until the thread with that identifier (the thread running Thread2Func)
terminates.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#define HF_STDOUT 1 /* Standard output handle */
TID atid[3];
ULONG cbWritten;
DosCreateThread(&atid[0], Thread2Func, 0, 0, 4096);
DosCreateThread(&atid[1], Thread3Func, 0, 0, 4096);
DosCreateThread(&atid[2], Thread4Func, 0, 0, 4096);
DosWaitThread(&atid[0], DCWW_WAIT);
DosWrite(HF_STDOUT, "The thread has terminated\r\n", 27, &cbWritten);
If you set the tid parameter to 0 in the call to DosWaitThread, the operating
system waits only until the next thread (any thread in the process) terminates.
The identifier for the terminated thread is then returned in the tid parameter.
After the threads are created as in the preceding example, the following code
fragment waits until one of the threads terminates, and then returns its thread
identifier:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
TID tid;
tid = 0;
DosWaitThread(&tid, DCWW_WAIT);
The thread identifier of the next thread to terminate after the DosWaitThread
call is returned in the tid parameter.
You can use DosWaitThread so that you can recover thread resources when the
thread terminates, or to synchronize the execution of a thread with the
execution of other threads.
ΓòÉΓòÉΓòÉ 5.4.8. Ending the Current Thread ΓòÉΓòÉΓòÉ
To end the execution of the current thread, call DosExit, specifying the action
code as 0. It is good practice to end each thread in the application
individually.
If the thread that is ending is the last thread in the process, or if the
request is to terminate all threads in the process, then the process also
terminates. All threads except one are terminated, and that thread executes
any routines in the list specified by DosExitList. When this is complete, the
resources of the process are released, and the result code that was specified
in the DosExit call is passed to any thread that calls DosWaitChild for this
process.
In the following code fragment, the main routine starts another program,
SIMPLE.EXE, and then expects a return code of 3 to be returned. SIMPLE.EXE sets
the return code with DosExit.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
#define START_PROGRAM "SIMPLE.EXE"
#define RETURN_OK 3
CHAR LoadError[100];
PSZ Args;
PSZ Envs;
RESULTCODES ReturnCodes;
APIRET rc;
rc = DosExecPgm(LoadError, /* Object name buffer */
sizeof(LoadError), /* Length of object name buffer */
EXEC_SYNC, /* Asynchronous/Trace flags */
Args, /* Argument string */
Envs, /* Environment string */
&ReturnCodes, /* Termination codes */
START_PROGRAM); /* Program file name */
if (ReturnCodes.codeResult == RETURN_OK) /* Check result code */
printf("Things are ok...");
else
printf("Something is wrong...");
----------------SIMPLE.EXE------------------
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
#define RETURN_CODE 3
main()
{
printf("Hello!\n");
DosExit(EXIT_THREAD, /* End thread/process */
RETURN_CODE); /* Result code */
}
When you specify DosExit for thread 1 (the initial thread of execution started
by the operating system for this process), all of the threads in the process
are terminated, and the process is ended.
ΓòÉΓòÉΓòÉ 5.4.9. Terminating a Thread ΓòÉΓòÉΓòÉ
DosKillThread terminates a thread in the current process. DosKillThread enables
a thread in a process to terminate any other thread in the process.
DosKillThread is used to force a thread within the current process to terminate
without causing the entire process to be terminated.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
TID tidThread; /* ThreadID of the thread to be terminated */
DosCreateThread(&tidThread, ThreadFunction, 0, 0, 4096);
.
.
.
DosKillThread(tidThread);
DosKillThread returns to the requestor without waiting for the target thread to
complete its termination processing.
It is an invalid operation to use DosKillThread to kill the current thread.
Terminating thread 1 will cause the entire process to terminate similar to
executing DosExit on thread 1. DosKillThread will not terminate a thread that
is suspended. Instead the suspended thread will be terminated when it resumes
execution. For this reason, you should not kill the main thread of an
application if there are any secondary threads that are suspended.
If the target thread is executing 16-bit code or was created by a 16-bit
requester, ERROR_BUSY is returned.
ΓòÉΓòÉΓòÉ 5.5. Using Sessions ΓòÉΓòÉΓòÉ
A session consists of at least one process and a virtual console (either full
screen, or Presentation Manager window, and buffers for keyboard and mouse
input). An application can manage its own child sessions by using
DosStartSession, DosStopSession, DosSelectSession, and DosSetSession.
ΓòÉΓòÉΓòÉ 5.5.1. Starting a Session ΓòÉΓòÉΓòÉ
DosStartSession is used to start new sessions and to specify the name of the
application to be started in the new session.
There are five types of sessions that you can start: full screen, text window,
Presentation Manager (PM), full screen DOS Session, and windowed DOS Session.
OS/2 applications running in any of the OS/2 session types-full screen, text
window, and PM-can start a session for any other application type, including
DOS Sessions. Applications running in DOS Sessions cannot start sessions.
DosStartSession can be used to start either a foreground or a background
session, but a new session can be started in the foreground only when the
session of the caller, or one of the descendant sessions of the caller, is
currently executing in the foreground.
A session can be started as an unrelated session or as a child session.
In the following code fragment, an unrelated, foreground session is created,
and the application, SIMON.EXE, is started in the new session:
#define INCL_DOSPROCESS /* Process and thread values */
#define INCL_DOSSESMGR
#include <os2.h>
#define HF_STDOUT 1 /* Standard output handle */
STARTDATA sd;
PID pidProcess;
CHAR szBuf[CCHMAXPATH];
ULONG ulSessionID, cbWritten;
APIRET rc;
CHAR szPgmName[] = "SIMON.EXE";
sd.Length = sizeof(sd); /* Length of the structure */
sd.Related = SSF_RELATED_INDEPENDENT; /* Unrelated session */
sd.FgBg = SSF_FGBG_FORE; /* In the foreground */
sd.TraceOpt = SSF_TRACEOPT_NONE; /* No tracing */
sd.PgmTitle = (PSZ) NULL; /* Title is PgmName */
sd.PgmName = szPgmName; /* Address of szPgmName */
sd.PgmInputs = (PBYTE) NULL; /* No command line args */
sd.TermQ = (PBYTE) NULL; /* No terminal queue */
sd.Environment = (PBYTE) NULL; /* Inherits environment */
sd.InheritOpt = SSF_INHERTOPT_PARENT; /* Uses parent environment */
sd.SessionType = SSF_TYPE_PM; /* PM session */
sd.IconFile = (PSZ) NULL; /* Uses default icon */
sd.PgmHandle = 0; /* Used by Win calls */
sd.PgmControl = SSF_CONTROL_MAXIMIZE; /* Starts app maximized */
sd.InitXPos = 0; /* Lower left corner */
sd.InitYPos = 0; /* Lower left corner */
sd.InitXSize = 0; /* Ignored for maximized */
sd.InitYSize = 0; /* Ignored for maximized */
sd.ObjectBuffer = szBuf; /* Fail-name buffer */
sd.ObjectBuffLen = sizeof(szBuf); /* Buffer length */
rc = DosStartSession(&sd, &ulSessionID, &pidProcess);
if (rc) {
DosBeep(750,250);
DosWrite(HF_STDOUT, "error starting new session\r\n", 28, &cbWritten);
DosExit(EXIT_PROCESS, rc);
}
Before calling DosStartSession, you must create a STARTDATA data structure that
defines the session to be started. Different lengths for the data structure are
supported to provide compatibility and various levels of application control.
DosStartSession uses the STARTDATA structure to specify the details of the new
session, such as the name of the application to start in the session, whether
the new session should be started in the foreground or background, and whether
the new session is unrelated or is a child session of the session calling
DosStartSession.
When a session is created, the title specified in STARTDATA, (or the
application title if no title is specified in STARTDATA) is added to the Window
List.
The Related field in the STARTDATA structure specifies whether the new session
is related to the session calling DosStartSession.
If the InheritOpt field in the STARTDATA data structure is set to 1, the new
session inherits the environment and open file handles of the calling process.
This applies for both unrelated and related sessions.
ΓòÉΓòÉΓòÉ 5.5.2. Controlling the Execution of Child Sessions ΓòÉΓòÉΓòÉ
Once a process has started a child session, it can use DosSelectSession to
control the child session.
A process calls DosSetSession to set the selectability and bonding of a child
session.
ΓòÉΓòÉΓòÉ 5.5.2.1. Setting User Selectability of a Child Session ΓòÉΓòÉΓòÉ
A process calls DosSetSession to set the selectability of a child session.
When a child session is selectable, the user can select it from the Window List
or by using Alt+Esc. When a child session is nonselectable, the user cannot
select the session from the Window List or move to it by using the Alt+Esc
keys.
In the following code fragment, DosSetSession makes a child session
nonselectable:
#define INCL_DOSPROCESS /* Process and thread values */
#define INCL_DOSSESMGR
#include <os2.h>
ULONG ulSessionID;
STATUSDATA stsdata;
stsdata.Length = sizeof(stsdata);
stsdata.SelectInd = SET_SESSION_NON_SELECTABLE; /* Non-selectable */
stsdata.BondInd = SET_SESSION_UNCHANGED; /* Leaves session bonding */
/* index unchanged */
DosSetSession(ulSessionID, &stsdata);
Once a child session is made nonselectable, the user cannot select the session
from the Window List or move to it by using the Alt+Esc keys. However, the
parent session can still bring the child session to the foreground by using
DosSelectSession. If the session contains a Presentation Manager application or
is a windowed session, the user will still be able to select it with a mouse.
The parent session can make a nonselectable child session selectable by setting
the SelectInd field to SET_SESSION_SELECTABLE in the STATUSDATA structure.
DosSetSession can be called only by a parent session and only for a child
session. That is, the calling process must be the process that started the
child session using DosStartSession. Neither the parent session itself nor any
grandchild, nor any other descendant session beyond a child session can be the
target of this call.
Additionally, DosSetSession cannot be used to change the status of a session
that was started as an unrelated session. The Related field in the STARTDATA
structure must have been set to 1 when the session was started.
ΓòÉΓòÉΓòÉ 5.5.2.2. Binding Child Sessions to Parent Sessions ΓòÉΓòÉΓòÉ
An application can use DosSetSession to establish a bond between a parent
session and one of its child sessions. When the two sessions are bound, the
operating system brings the child session to the foreground when the user
selects the parent session.
In the following code fragment, a parent session is bound to the child session
specified by the ulSessionID parameter:
#define INCL_DOSPROCESS /* Process and thread values */
#define INCL_DOSSESMGR
#include <os2.h>
ULONG ulSessionID;
STATUSDATA stsdata;
stsdata.Length = sizeof(stsdata);
stsdata.SelectInd = SET_SESSION_UNCHANGED; /* Leaves select setting alone */
stsdata.BondInd = SET_SESSION_BOND; /* Binds parent and child */
DosSetSession(ulSessionID, &stsdata);
When the application uses DosSetSession to establish a parent-child bond, any
bond the parent has with another child session is broken. The application can
remove the parent-child bond by calling DosSetSession with the BondInd field
(in the STATUSDATA structure) set to SET_SESSION_NO_BOND.
A parent session can be executing in either the foreground or the background
when it calls DosSetSession.
ΓòÉΓòÉΓòÉ 5.5.2.3. Switching a Session to the Foreground ΓòÉΓòÉΓòÉ
An application can bring a session to the foreground, or select the session, by
calling DosSelectSession.
DosSelectSession can only be used to select the current session or one of the
current session's child sessions. It cannot be used to select a grandchild
session, or any other descendant session beyond a child session, or any
sessions that were started as unrelated sessions.
The session making the call, or one of its child sessions, must be executing in
the foreground at the time the function is called. A process can call
DosSelectSession with its own session identifier to switch itself to the
foreground when one of its descendants is executing in the foreground.
The following code fragment uses DosSelectSession to switch the child session
specified by the ulSessionID parameter to the foreground for five seconds. The
application then switches the parent session back to the foreground:
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
ULONG ulSessionID;
DosSelectSession(ulSessionID); /* Switches child to foreground */
DosSleep(5000); /* Sleeps for 5 seconds */
DosSelectSession(0); /* Switches parent back */
ΓòÉΓòÉΓòÉ 5.5.3. Terminating a Session ΓòÉΓòÉΓòÉ
DosStopSession can be used by a parent session to stop one or all of its child
sessions. If the child session specified in the call to DosStopSession has
related sessions, the related sessions are also terminated. The parent session
can be running in the foreground or the background when it calls
DosStopSession. If the child session is running in the foreground when it is
terminated, the parent session becomes the foreground session.
DosStopSession can only be called by a parent session for a child session.
Neither the parent session itself, nor any grandchild, nor any other descendant
session beyond a child session, nor any unrelated session, can be the target of
this call.
In the following code fragment, the child session specified by the ulSessionID
parameter is terminated:
#define INCL_DOSPROCESS /* Process and thread values */
#define INCL_DOSSESMGR
#include <os2.h>
ULONG ulSessionID;
DosStopSession(STOP_SESSION_SPECIFIED, ulSessionID);
An application can terminate all its child sessions by setting the first
parameter to STOP_SESSION_ALL in the call to DosStopSession. If this is
specified, the second parameter is ignored.
A process running in a child session can ignore the request to terminate. If
the process has set up its own exception handler, it might not terminate
immediately after the call to DosStopSession. The only way the parent process
can be certain that the child session has terminated is to wait for
notification through the termination queue specified in the call to
DosStartSession that started the session. When the child session terminates,
the operating system writes a data element into the termination queue,
specifying the child process identifier and the termination status.
If the process in the session specified by DosStopSession has not ended, then
DosStopSession still returns a normal return code. You can ensure that a
process in a session has ended by waiting for notification from the termination
queue specified with DosStartSession.
ΓòÉΓòÉΓòÉ 6. Queues ΓòÉΓòÉΓòÉ
Communication between processes is valuable in a multitasking operating system
to enable concurrent processes to work together. Queues are one of three forms
of interprocess communication (IPC), the other forms of IPC being semaphores
and pipes.
This chapter describes how to create and use queues. Queues enable one or more
processes to transfer data to a specific target process.
Note: The queues used for interprocess communication should not to be confused
with the message queues used for communication between Presentation
Manager (PM) and PM applications, nor with the printer queues used by
the print spooler in managing print jobs.
The following topics are related to the information in this chapter:
o Memory (Shared Memory)
o Program Execution and Control
o Semaphores
o Pipes
ΓòÉΓòÉΓòÉ 6.1. About Queues ΓòÉΓòÉΓòÉ
A queue is a named, ordered list of elements that is used to pass information
between threads of the same (related) process or between different (unrelated)
processes.
Processes pass information to a queue in the form of elements. An element is a
32-bit unit of information. Queue elements can be values, flags, pointers to
shared memory regions, anything that can fit into 32 bits. The format of a
queue element depends entirely on the process that creates the queue (the queue
owner). Only the queue owner can read elements from the queue; other processes
can only write to the queue. Reading an element automatically removes it from
the queue.
The process that creates the queue is known as the server process of the queue.
The other processes that access the queue are known as client processes.
The owner of the queue (the server process) can choose the order in which to
read incoming information and can examine queue elements without removing them
from the queue. Queue elements can be added and accessed in First-In-First-Out
(FIFO), Last-In-First-Out (LIFO), or priority-based order.
Any process that has the name of a queue can open the queue and write to it.
The processes writing elements to the queue must use the format determined by
the queue owner.
Queues are very efficient. They pass only 32-bit sized elements, rather than
large data structures. However, queues can be used only for one-way
communication, because a client process can write to a queue but cannot read
from one.
Typically, processes use queues to transfer information about the contents of a
shared memory. The elements in the queue could contain the address and length
of data areas in shared memory objects. The sending process allocates a shared
memory object and gives access to the shared memory to the queue owner. The
sending process can free the shared memory after writing the elements to the
queue because the shared memory will not be deallocated until the queue owner
frees it.
Any thread in the process that owns the queue can examine queue elements
without removing them. This is called peeking at the queue.
The operating system supplies the process identifier of the process that writes
an element to the queue, so that a process reading from or peeking at the queue
can determine the origin of the element. The process identifier is returned as
part of a REQUESTDATA data structure. Threads can use the ulData field of the
REQUESTDATA data structure to pass additional information about the queue
element.
If the queue is empty when a process attempts to read from it, the process can
either wait for an element to become available or continue executing without
reading from the queue. Semaphores can be used to indicate when an element is
in the queue.
ΓòÉΓòÉΓòÉ 6.1.1. Queues and Semaphores ΓòÉΓòÉΓòÉ
If a process manages only one queue, it typically waits for an element to
become available. However, if a process manages several queues, waiting for one
queue means that other queues cannot be read. To avoid wasting time while
waiting, a process can supply an event semaphore when it calls DosReadQueue or
DosPeekQueue. The process can then continue to execute without actually reading
an element from the queue, because DosWriteQueue will post the semaphore only
when an element is ready. The semaphore remains posted until someone resets it;
usually the queue owner process resets the semaphore after it reads all the
available information from the queue.
If a process uses a unique semaphore for each queue, it can use
DosWaitMuxWaitSem to wait for the first queue to receive an element.
Only one semaphore is permitted per queue.
ΓòÉΓòÉΓòÉ 6.1.2. Queue Servers and Clients ΓòÉΓòÉΓòÉ
The server process and its threads have certain queue-managing privileges. Only
the server process and its threads can:
o Examine queue elements without removing them (DosPeekQueue)
o Remove elements from the queue (DosReadQueue)
o Purge all the elements in a queue (DosPurgeQueue)
o Write to the queue without opening it first (DosWriteQueue)
o Delete the queue (DosCloseQueue).
Both server and client processes can query the number of elements in the queue
using DosQueryQueue.
Client processes can query the queue (DosQueryQueue) and add elements to it
(DosWriteQueue), but they must first gain access to the queue by calling
DosOpenQueue. When a client process is finished with a queue, it ends its
access to the queue by calling DosCloseQueue. (Note that, unlike the server
process and its threads, a client process cannot use DosCloseQueue to delete a
queue.)
When a queue is opened by a client process, an access count is set to 1. Each
client process has its own access count. The access count is incremented
whenever a thread in a process opens the queue and decremented whenever a
thread in the process closes the queue. Access to the queue by the client
process ends when the access count for the process reaches 0. When the server
process closes the queue, the queue is terminated and removed from the system.
ΓòÉΓòÉΓòÉ 6.1.3. Queue Element Order ΓòÉΓòÉΓòÉ
DosReadQueue reads either a specified element or the first element in the
queue. The first element in the queue depends on the queue type, which is
specified when the queue is created. A queue can have FIFO, LIFO, or priority
ordering.
Priority values range from 0 (lowest priority) through 15 (highest priority).
The writing process assigns a priority to a queue element when the element is
written to the queue. DosReadQueue reads elements from the queue in descending
order of priority, regardless of the order in which DosWriteQueue placed the
elements in the queue. Elements with equal priority are read in FIFO order.
ΓòÉΓòÉΓòÉ 6.1.4. Obtaining Information about Queues and Queue Elements ΓòÉΓòÉΓòÉ
Any thread in the process that owns the queue can use DosPeekQueue to examine
the elements in the queue to determine which one to actually read. Each call to
DosPeekQueue returns the identifier of the next element in the queue, so the
function can be called repeatedly to move through the queue. The identifier of
the desired element can then be supplied to DosReadQueue.
Any process that has opened a queue can use DosQueryQueue to determine the
number of elements in the queue. This function also returns an error value if
the queue owner has closed the queue.
ΓòÉΓòÉΓòÉ 6.2. Using Queues ΓòÉΓòÉΓòÉ
Queues are useful for a process to manage input from other processes. The
examples in the following sections show how to create and use queues.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 6.2.1. Creating a Queue ΓòÉΓòÉΓòÉ
A thread creates a queue by using DosCreateQueue and specifying a queue name
and the queue type as arguments. The queue name must be unique and have the
following form:
\QUEUES\QueName
The "\QUEUES\" is required, though it need not be uppercase. It is not a
subdirectory.
The QueName parameter must conform to the rules for OS/2 file names, although
no actual file is created for the queue.
The process that creates the queue is known as the server process of the queue.
The other processes that access the queue are known as client processes.
The following code fragment creates a FIFO queue named \queues\sample.que:
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
HQUEUE hq;
DosCreateQueue(&hq, QUE_FIFO | QUE_CONVERT_ADDRESS,
"\\queues\\sample.que");
When the server process creates the queue, it determines whether the ordering
of queue elements is based on arrival (FIFO or LIFO) or priority. If the
ordering is based on priority, then priority values must be assigned whenever
data is added to the queue.
The server must also specify whether the operating system is to convert 16-bit
addresses of elements placed in the queue by 16-bit processes to 32-bit
addresses.
After a process has created a queue, any thread in that process can access the
queue with equal authority.
ΓòÉΓòÉΓòÉ 6.2.2. Allocating Memory for Queue Data ΓòÉΓòÉΓòÉ
When queues are used only to pass the addresses to data rather than the data
itself, processes must allocate shared memory objects for storing queue data.
The two most common methods of storing queue data are:
o Using a named shared memory object - for related processes
o Using unnamed shared memory objects - for unrelated processes
ΓòÉΓòÉΓòÉ 6.2.2.1. Named Shared Memory Objects ΓòÉΓòÉΓòÉ
Related processes generally use a single named shared memory object for storing
queue data. The server process allocates the memory object by calling
DosAllocSharedMem. Care must be taken to ensure that the memory object is large
enough to meet application requirements.
The name of the shared memory object is established by agreement among the
server and the client processes. For simplicity, the name can be the same as
the queue name, except that the prefix \SHAREMEM\ must be used instead of
\QUEUES\.
A client process accesses the named shared memory object by calling
DosGetNamedSharedMem. It must then call DosOpenQueue to gain access to the
queue of the server.
Before the server process ends, it releases the memory object by calling
DosFreeMem.
ΓòÉΓòÉΓòÉ 6.2.2.2. Unnamed Shared Memory Objects ΓòÉΓòÉΓòÉ
Unrelated processes generally use unnamed shared memory objects for storing
queue data. This makes it possible for a client process to store data in a
shared memory object without knowing its name. To use unnamed shared memory
objects for storing queue data, the server process must take the following
steps whenever it is called by a client:
1. Save the process identification (PID) of the client process.
2. Allocate an unnamed shared memory object for the data of the client
process by calling DosAllocSharedMem.
3. Give the client process the capability of accessing the memory object by
calling DosGiveSharedMem with the client's PID.
The client process must then call DosOpenQueue to gain access to the server's
queue.
After each client completes its queue requests or ends, the server calls
DosFreeMem to release the client's memory object.
ΓòÉΓòÉΓòÉ 6.2.3. Opening a Queue ΓòÉΓòÉΓòÉ
Once the queue is created, the server process of the queue and the threads of
the server process have immediate access to the queue and can proceed to access
the queue. A client process must request access to a queue by calling
DosOpenQueue. Once the queue is open, the client process can add an element to
the queue with DosWriteQueue, and it can query the number of elements in the
queue with DosQueryQueue.
DosOpenQueue retrieves the queue handle and the process identifier of the queue
owner. The function also increments the queue's access count.
The following code fragment shows how another process would open the queue
created with DosCreateQueue.
#define INCL_DOSQUEUES
#include<os2.h>
#define HF_STDOUT 1 /* Standard output handle */
HQUEUE hq;
PID pidOwner;
ULONG cbWritten;
APIRET rc;
rc = DosOpenQueue(&pidOwner, &hq, "\\queues\\sample.que");
if (rc) {
DosWrite(HF_STDOUT, "\r\n Queue open failed. \r\n", 24, &cbWritten);
DosExit(EXIT_PROCESS, 1);
}
else {
DosWrite(HF_STDOUT, "\r\n Queue opened. \r\n", 19, &cbWritten);
}
When it is finished with the queue, a thread in the client process ends its
access by calling DosCloseQueue. DosCloseQueue decrements the access count for
the process each time it is called. When the access count reaches 0, the
connection between the client process and the queue is terminated.
After a process has opened a queue, any thread in that process can access the
queue with equal authority.
Note: If a queue was created by a call to the 16-bit DosCreateQueue, then it
is not accessible to 32-bit DosOpenQueue requests, and
ERROR_QUE_PROC_NO_ACCESS will be returned.
ΓòÉΓòÉΓòÉ 6.2.4. Writing to a Queue ΓòÉΓòÉΓòÉ
The server process and any of its threads can add an element to a queue simply
by calling DosWriteQueue. A client process, however, must first request access
to the queue by calling DosOpenQueue.
Processes that communicate by passing the addresses of shared memory objects
through the queue must have a shared memory object that they each have access
to. Once a process opens the queue, it can allocate shared memory by using
DosAllocMem with the OBJ_GIVEABLE attribute and then give the shared memory to
the queue owner with DosGiveSharedMem.
A process that has opened a queue can write to the queue by using
DosWriteQueue. The writing process must create elements in a form that the
queue owner can read.
The following code fragment adds an element to a queue. Assume that the caller
has placed the handle of the queue into QueueHandle already. Assume also that
DataBuffer has been set to point to a data element in shared memory, and that
DataLength has been set to contain the length of the data element in shared
memory.
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#include <stdio.h>
HQUEUE QueueHandle; /* Queue handle */
ULONG Request; /* Request-identification data */
ULONG DataLength; /* Length of element being added */
PVOID DataBuffer; /* Element being added */
ULONG ElemPriority; /* Priority of element being added */
APIRET rc; /* Return code */
Request = 0; /* Assume that no special data is being */
/* sent along with this write request */
ElemPriority = 0; /* For priority-based queues: add the */
/* new queue element at the logical end */
/* of the queue */
rc = DosWriteQueue(QueueHandle, Request, DataLength,
DataBuffer, ElemPriority);
if (rc != 0) {
printf("DosWriteQueue error: return code = %ld", rc);
return;
}
Once the process has written to the queue, it frees the shared memory. However,
the memory will not be freed until the queue owner also frees it.
If the queue was created as a priority-based queue (as specified in the
QueueFlags parameter of DosCreateQueue), then the priority of the element that
is being added must be specified.
If the server process has ended, or if it has closed the queue before
DosWriteQueue is called, then ERROR_QUE_INVALID_HANDLE is returned.
ΓòÉΓòÉΓòÉ 6.2.5. Reading from a Queue ΓòÉΓòÉΓòÉ
The queue owner (server process) and its threads can read an element from the
queue by using DosReadQueue. The owner can read the first element in the queue
by specifying 0 as the element number. Alternatively, the owner can read a
particular element in the queue by specifying an element code returned from
DosPeekQueue. This function is not available to client processes.
DosReadQueue can either remove queue elements in the order that was specified
when the queue was created (FIFO, LIFO, or priority), or it can use an element
identifier from DosPeekQueue as input to remove a previously examined element.
The following code fragment reads an element from the queue. Assume that the
caller has placed the handle of the queue into QueueHandle already and that the
identifier of the process that owns the queue has been placed into OwningPID
already.
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#include <stdio.h>
HQUEUE QueueHandle; /* Queue handle */
REQUESTDATA Request; /* Request-identification data */
ULONG DataLength; /* Length of element received */
PULONG DataAddress; /* Address of element received */
ULONG ElementCode; /* Request a particular element */
BOOL32 NoWait; /* No wait if queue is empty */
BYTE ElemPriority; /* Priority of element received */
HEV SemHandle; /* Semaphore handle */
PID OwningPID; /* PID of queue owner */
APIRET rc; /* Return code */
Request.pid = OwningPID; /* Set request data block to indicate */
/* queue owner */
ElementCode = 0; /* Indicate that the read should start */
/* at the front of the queue */
NoWait = 0; /* Indicate that the read should wait */
/* if the queue is currently empty */
SemHandle = 0; /* Unused since this is a call that */
/* waits synchronously */
rc = DosReadQueue(QueueHandle, &Request, &DataLength,
(PVOID *) &DataAddress, ElementCode, NoWait,
&ElemPriority, SemHandle);
if (rc != 0) {
printf("DosReadQueue error: return code = %ld", rc);
return;
}
On successful return, DataLength contains the size of the element on the queue
that is pointed to by the pointer within DataAddress, ElemPriority has been
updated to contain the priority of the queue element pointed to by DataAddress,
and Request.ulData contains any special data that the DosWriteQueue caller
placed into the queue.
If the queue is empty and NoWait is set to DCWW_WAIT (0), the calling thread
waits until an element is placed in the queue. If the queue is empty and NoWait
is set to DCWW_NOWAIT (1), DosReadQueue returns immediately with
ERROR_QUE_EMPTY.
If NoWait is set to DCWW_NOWAIT, an event semaphore must be provided so that
the calling thread can determine when an element has been placed in the queue.
The semaphore is created by calling DosCreateEventSem, and its handle is
supplied as a DosReadQueue parameter. The first time an event semaphore handle
is supplied in a DosReadQueue or DosPeekQueue request for which DCWW_NOWAIT has
been specified for a particular queue, the handle is saved by the system. The
same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue
requests that are called for that queue; if a different handle is supplied,
ERROR_INVALID_PARAMETER is returned.
When a client process adds an element to the queue, the system automatically
opens the semaphore (if necessary) and posts it. The server can either call
DosQueryEventSem periodically to determine whether the semaphore has been
posted, or it can call DosWaitEventSem. DosWaitEventSem causes the calling
thread to block until the semaphore is posted.
After the event semaphore has been posted, the calling thread must call
DosReadQueue again to remove the newly added queue element.
If QUE_CONVERT_ADDRESS is specified in the call to DosCreateQueue, the
operating system will automatically convert 16-bit addresses to 32-bit
addresses.
ΓòÉΓòÉΓòÉ 6.2.6. Peeking at a Queue ΓòÉΓòÉΓòÉ
The server process and its threads can examine a queue element by calling
DosPeekQueue. This function is not available to client processes.
Unlike DosReadQueue, DosPeekQueue does not remove the element from the queue.
DosPeekQueue can either examine elements in the order that was specified when
the queue was created (FIFO, LIFO, or priority), or it can examine the next
element in the queue after a previous DosPeekQueue request has been called. By
making multiple DosPeekQueue requests, the server process can search through a
queue, examining each element in turn. When it locates the element it is
searching for, the server process can remove the element from the queue by
calling DosReadQueue.
If several threads are using the same queue, the process writing to the queue
can use the ulData field of the REQUESTDATA data structure to indicate that an
element is directed to a particular thread. The thread can peek at the queue
whenever data is available and read any elements containing the appropriate
value in the ulData field.
The following code fragment shows how a thread can use DosPeekQueue to examine
the elements in a queue. Assume that a previous call to DosOpenQueue provided
the queue handle that is contained in QueueHandle. Assume that the identifier
of the process that owns the queue has been placed into OwningPID already.
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#include <stdio.h>
HQUEUE QueueHandle; /* Queue handle */
REQUESTDATA Request; /* Request-identification data */
ULONG DataLength; /* Length of examined element */
PVOID DataAddress; /* Address of examined element */
ULONG ElementCode; /* Indicator of examined element */
BOOL32 NoWait; /* No wait if queue is empty */
BYTE ElemPriority; /* Priority of examined element */
HEV SemHandle; /* Semaphore handle */
PID OwningPID; /* PID of queue owner */
APIRET rc; /* Return code */
Request.pid = OwningPID; /* Set request data block to indicate */
/* queue owner */
ElementCode = 0; /* Indicate that the peek should start */
/* at the front of the queue */
NoWait = DCWW_WAIT /* Indicate that the peek call should */
/* wait if the queue is currently empty */
SemHandle = 0; /* Unused since this is a call that */
/* synchronously waits */
rc = DosPeekQueue(QueueHandle, &Request, &DataLength,
&DataAddress, &ElementCode, NoWait,
&ElemPriority, SemHandle);
if (rc != 0) {
printf("DosPeekQueue error: return code = %ld", rc);
return;
}
On successful return, DataLength contains the size of the element on the queue
that is pointed to by the pointer within DataAddress, ElementCode has been
updated to indicate the next queue element, ElemPriority has been updated to
contain the priority of the queue element pointed to by DataAddress, and
Request.ulData contains any special data that the DosWriteQueue caller placed
into the queue.
If the queue is empty and NoWait is set to DCWW_WAIT (0), the calling thread
waits until an element is placed in the queue. If the queue is empty and NoWait
is set to DCWW_NOWAIT (1), DosPeekQueue returns immediately with
ERROR_QUE_EMPTY.
If NoWait is set to DCWW_NOWAIT, an event semaphore must be provided so that
the calling thread can determine when an element has been placed in the queue.
The semaphore is created by calling DosCreateEventSem, and its handle is
supplied as a DosPeekQueue parameter. The first time an event semaphore handle
is supplied in a DosPeekQueue or DosReadQueue request for which DCWW_NOWAIT has
been specified for a particular queue, the handle is saved by the system. The
same handle must be supplied in all subsequent DosPeekQueue and DosReadQueue
requests that are called for that queue; if a different handle is supplied,
ERROR_INVALID_PARAMETER is returned.
When a client process adds an element to the queue, the system automatically
opens the semaphore (if necessary) and posts it. The server can either call
DosQueryEventSem periodically to determine whether the semaphore has been
posted, or it can call DosWaitEventSem. DosWaitEventSem causes the calling
thread to block until the semaphore is posted.
After the event semaphore has been posted, the calling thread must call
DosPeekQueue again to examine the newly added queue element.
If QUE_CONVERT_ADDRESS is specified in the call to DosCreateQueue, the
operating system will automatically convert 16-bit addresses to 32-bit
addresses.
ΓòÉΓòÉΓòÉ 6.2.7. Purging a Queue ΓòÉΓòÉΓòÉ
The server process or any of its threads can empty a queue of all its elements
by calling DosPurgeQueue. This function is not available to client processes.
Warning: This is an unconditional purge of all elements in the queue.
The following code fragment shows how the owner of a queue can empty the queue
of all data elements. Assume that the owner of the queue has saved the queue's
handle (obtained in a previous call to DosCreateQueue) in QueueHandle.
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#include <stdio.h>
HQUEUE QueueHandle; /* Queue handle */
APIRET rc; /* Return code */
rc = DosPurgeQueue(QueueHandle);
if (rc != 0) {
printf("DosPurgeQueue error: return code = %ld", rc);
return;
}
ΓòÉΓòÉΓòÉ 6.2.8. Closing a Queue ΓòÉΓòÉΓòÉ
DosCloseQueue can be used both to end access to a queue and to delete a queue.
The action taken as a result of a DosCloseQueue request depends on:
o Whether the requesting process is the server process or a client process
o The value of the access count, which is maintained for each client
process by the operating system. The access count for a client process is
incremented whenever DosOpenQueue is called, and decremented whenever
DosCloseQueue is called.
If the requesting process is a client, and the access count equals 0,
DosCloseQueue ends the client's access to the queue, but the queue itself is
not affected. If the access count does not equal 0, the count is decremented,
but the process retains access to the queue.
If the requesting process is the server, DosCloseQueue purges any outstanding
elements from the queue and deletes the queue regardless of the access count;
client processes that still have the queue open receive
ERROR_QUE_INVALID_HANDLE on their next request.
ΓòÉΓòÉΓòÉ 7. Semaphores ΓòÉΓòÉΓòÉ
Communication between processes is valuable in a multitasking operating system
to enable concurrent processes to work together. Semaphores are one of three
forms of interprocess communication (IPC), the other forms of IPC being pipes
and queues.
This chapter describes how to create and use semaphores. Semaphores enable an
application to signal the completion of tasks and control access to resources
that are shared between more than one thread or process.
The following topics are related to the information in this chapter:
o Memory (Shared Memory)
o Program Execution and Control
o Pipes
o Queues
ΓòÉΓòÉΓòÉ 7.1. About Semaphores ΓòÉΓòÉΓòÉ
Semaphores signal the beginning or ending of an operation and provide mutually
exclusive ownership of resources. Typically, semaphores are used to prevent
more than one process or thread within a process from accessing a resource,
such as shared memory, at the same time.
Semaphores are defined by the operating system and reside in an internal memory
buffer. They are divided into three types, according to the functionality they
provide:
o Event semaphores enable a thread to notify waiting threads that an event
has occurred. The waiting threads then resume execution, performing
operations that are dependent on the completion of the signaled event.
o Mutual exclusion (mutex) semaphores enable threads to serialize their
access to shared resources. That is, ownership of a mutex semaphore is
used by cooperating threads as a prerequisite for performing operations
on a resource. (Threads cooperate by using the mutex semaphore functions
to ensure that access to the resource is mutually exclusive.)
o Multiple Wait (muxwait) semaphores enable threads to wait either for
multiple events to occur, or for multiple resources to become available.
Alternatively, a flag can be set so that a thread waits for any one of
multiple events to occur, or for any one of multiple resources to become
available.
ΓòÉΓòÉΓòÉ 7.1.1. Event Semaphores ΓòÉΓòÉΓòÉ
An event semaphore provides a signaling mechanism among threads or processes,
ensuring that events occur in the desired sequence. Event semaphores are used
by one thread to signal other threads that an event has occurred. An
application can use this type of semaphore to block a thread or process until
the event has occurred.
An event semaphore has two states, reset and posted. When an event semaphore is
in the reset state, the operating system blocks any thread or process that is
waiting on the semaphore. When an event semaphore is in the posted state, all
threads or processes waiting on the semaphore resume execution.
For example, assume thread 1 is allocating a shared memory object and threads 2
and 3 must wait for the memory to be allocated before they attempt to examine
its contents. Before thread 1 allocates the memory, it creates an event
semaphore, specifying the initial state of the semaphore as reset. (If the
event semaphore has already been created, thread 1 simply resets the
semaphore.) Threads 2 and 3 use DosWaitEventSem to wait for the semaphore to
signal that the event, in this case the allocation and preparation of the
shared memory object, has been completed. Because the semaphore was reset by
thread 1, threads 2 and 3 are blocked when they call DosWaitEventSem. After
thread 1 has finished allocating and placing data in the shared memory object,
it signals the completion of its task by posting the event semaphore. The
posting of the event semaphore unblocks threads 2 and 3, enabling them to
resume execution. They can then proceed to examine the contents of the
allocated memory.
In the example above, one thread controls the resetting and posting of the
event semaphore, while other threads merely wait on the semaphore. Another
approach could be for an application or thread to reset an event semaphore,
then block itself on that semaphore. At a later time, another application or
thread would post the event semaphore, unblocking the first thread.
ΓòÉΓòÉΓòÉ 7.1.2. Mutual Exclusion (Mutex) Semaphores ΓòÉΓòÉΓòÉ
A mutual exclusion (mutex) semaphore protects resources (such as files, data in
memory, and peripheral devices) from simultaneous access by several processes.
Mutex semaphores enable threads to serialize their access to resources. It does
so by preventing the processes from concurrently executing the sections of code
through which access is made. These sections of code are called critical
sections. For example, a mutex semaphore could be used to prevent two or more
threads from simultaneously writing to the same file on a disk.
Before a thread can execute a mutex-protected critical section, it must request
and receive ownership of the mutex semaphore. Only the thread that has gained
ownership of the mutex semaphore is permitted to perform operations on the
protected resource. Only one thread at a time can own the mutex semaphore, and
the owner thread retains ownership until it finishes executing its critical
section. When finished, the owner thread releases the mutex semaphore, enabling
another thread to become the owner.
When a thread requests ownership of a mutex semaphore that is already owned,
the operating system blocks the thread. When more than one thread requests
ownership of the same semaphore, the operating system queues the requests and
grants subsequent ownership based on the thread's priority and the order in
which the requests were received.
If more than one thread is blocked on a DosRequestMutexSem request, then
ownership is given to the thread that has the highest priority level. If more
than one of the waiting threads have the same priority level, then FIFO
ordering is used to determine which thread is unblocked and given ownership of
the semaphore.
For example, both thread 1 and thread 2 must write information to the same disk
file. Thread 1 claims ownership of an agreed-upon mutex semaphore and starts
writing its information to the file. If thread 2 also requests ownership of the
semaphore, it will be blocked. When thread 1 has finished writing to the file,
it releases the semaphore. The operating system then unblocks thread 2 and
designates it as the new owner of the semaphore so that it can write to the
file.
During process termination, after delivery of process-termination exceptions
and unwind exceptions, if any threads in the process aside from Thread 1 (the
main thread) own a mutex semaphore, ownership of the semaphore (and therefore,
the shared resource) passes to Thread 1. This gives Thread 1 a last chance to
clean up the semaphore and the shared resource before the process ends. If
Thread 1 ends without releasing the semaphore, all threads that are currently
waiting on ownership of the semaphore will be unblocked with the SEM_OWNER_DIED
return code. Any thread that attempts to open it or request ownership of the
semaphore will receive a SEM_OWNER_DIED return code.
The recommended way to clean up semaphores, and other resources, is for each
thread, especially Thread 1, to have an exception handler to handle clean up
during process termination (the XCPT_PROCESS_TERMINATE or
XCPT_ASYNC_PROCESS_TERMINATE exceptions). When it is not possible to register
an exception handler for a thread, (a DLL, for example, must de-register its
exception handlers when it returns control to the thread that called it), you
should add a clean up routine to the exit list of the process.
ΓòÉΓòÉΓòÉ 7.1.3. Multiple Wait (Muxwait) Semaphores ΓòÉΓòÉΓòÉ
A multiple wait (muxwait) semaphore enables a thread to wait on several event
or mutex semaphores simultaneously. A muxwait semaphore is a compound semaphore
that consists of a list of up to 64 event semaphores or mutex semaphores (the
two types cannot be mixed).
A flag is set when the muxwait semaphore is created to enable threads to use
the semaphore in either of two ways:
o Threads can wait for all of the mutex semaphores to be released, or for
all of the event semaphores to be posted.
o Threads can wait for any one of the mutex semaphores in the list to be
released, or for any one of the event semaphores in the list to be
posted.
Depending on the value of the flag, a muxwait semaphore is said to have
cleared when either any or all of the semaphores in the muxwait list have been
posted or released.
For example, suppose a thread requires access to several regions of shared
memory at the same time. The operating system blocks the thread until the
thread acquires ownership of all the mutex semaphores protecting the shared
regions. The thread can then access all the memory regions. Meanwhile, the
operating system prevents access by other threads.
ΓòÉΓòÉΓòÉ 7.1.4. Named and Anonymous Semaphores ΓòÉΓòÉΓòÉ
A semaphore can be either named or anonymous. A named semaphore is always
shared; that is, it is always available to any process that knows the name. An
anonymous semaphore can be either private to a process or shared among
processes, depending on whether the application includes the DC_SEM_SHARED flag
in the function that creates the semaphore. A semaphore intended for use solely
among threads of the same process can be anonymous and private.
The operating system creates a named semaphore when an application specifies a
name in the function that creates the semaphore. The name must have the
following form:
\SEM32\SemName
The "\SEM32\" is required, though it need not be uppercase. The semaphore name
must conform to the rules for OS/2 file names, although no actual file is
created for the semaphore. If the application does not specify a name in the
function that creates the semaphore, the operating system creates an anonymous
semaphore.
The OS/2 operating system permits a system-wide maximum of 65536 (64K) shared
semaphores. In addition, each process can use up to 65536 (64K) private
semaphores.
A shared muxwait semaphore must contain either all shared event semaphores or
all shared mutex semaphores. However, a private muxwait semaphore can contain a
combination of shared and private event or mutex semaphores. The operating
system generates a unique handle when it creates a semaphore. Processes must
obtain this handle before they can access the semaphore. A semaphore's handle
is always available to the process that created the semaphore. A process can
obtain the handle of a named semaphore created in another process by using the
appropriate semaphore-opening function. A process that requires access to an
anonymous shared semaphore that was created in another process must obtain the
handle of the semaphore through some other form of interprocess communication,
such as a pipe or a queue.
ΓòÉΓòÉΓòÉ 7.1.5. Semaphore Management ΓòÉΓòÉΓòÉ
After one process creates a semaphore, threads in other processes must open the
semaphore before they can access it. (Creating a semaphore automatically opens
it for the creating process.) The open operation ensures that the process is a
valid user of the semaphore. The operating system keeps track of the number of
open operations that each process performs on a semaphore. A process can have
up to 65535 (64K - 1) open operations performed on a semaphore at any one time.
If a process finishes using a semaphore and will not use it again, the process
should close the semaphore so that the operating system can free the memory the
semaphore is using. The operating system returns the ERROR_SEM_BUSY error value
if a thread tries to close a semaphore that has another thread in the same
process still waiting for it.
If a process terminates with open semaphores, the operating system
automatically closes the semaphores for that process.
Semaphores reside in a memory buffer rather than a disk file. Therefore, when
the last process that has a semaphore open exits or closes that semaphore, the
operating system frees the associated handle or name.
When an application calls a function that causes a thread to wait on a
semaphore, the application can specify the amount of time for the thread to
wait. When the interval elapses without the semaphore being posted or released,
the function returns the ERROR_TIMEOUT error value and the thread continues
running. The application can provide a specific time-out value in milliseconds,
or it can specify either the SEM_INDEFINITE_WAIT or the SEM_IMMEDIATE_RETURN
flag. If a thread is interrupted while it is waiting on a semaphore, the
ERROR_INTERRUPT error value is returned to the caller.
ΓòÉΓòÉΓòÉ 7.2. Using Event Semaphores ΓòÉΓòÉΓòÉ
An application can use an event semaphore to trigger execution of other
processes. This is useful if, for example, one process provides data to many
other processes. Using an event semaphore frees the other process from the
trouble of polling to determine when new data is available.
Note: In the example code fragments that follow, error checking was left out
to conserve space. Applications should always check the return code that
the functions return. Control Program functions return an APIRET value.
A return code of 0 indicates success. If a non-zero value is returned,
an error occurred.
ΓòÉΓòÉΓòÉ 7.2.1. Creating an Event Semaphore ΓòÉΓòÉΓòÉ
Processes create an event semaphore by using DosCreateEventSem. The process
that controls the event or resource is usually the one that creates the
semaphore, but it does not have to be.
Threads in the process that creates the semaphore do not have to open the
semaphore before using it. DosCreateEventSem obtains access to the semaphore
for the calling process and its threads. Threads in other processes must call
DosOpenEventSem to open the semaphore before they can use it.
Event semaphores can be defined as either private or shared:
o Private semaphores are always unnamed and are therefore always identified
by their handles. They can be used only by threads within a single
process.
o Shared semaphores can be either named or unnamed. If named, they can be
opened using either the name or the handle. The handle returned by
DosOpenEventSem is then used to identify the semaphore for all other
functions. Semaphore names must include the prefix \SEM32\ and must
conform to file system naming conventions. Shared semaphores can be used
by threads in multiple processes.
In the following code fragment, the controlling process creates a named event
semaphore and posts the semaphore after writing data to a shared file:
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
HEV hevWriteEvent;
DosCreateEventSem("\\sem32\\wrtevent", /* Named-shared semaphore */
&hevWriteEvent, 0, FALSE); /* Initially reset */
.
.
/* Write data to shared file. */
.
.
DosPostEventSem(hevWriteEvent); /* Posts the event */
.
. /* Continue execution. */
.
There is a system-wide limit of 65536 (64K) shared semaphores (including
mutex, event, and muxwait semaphores); in addition, each process can have up
to 65536 (64K) private semaphores.
When an event semaphore is created, a flag is used to specify the initial
state of the event semaphore, either reset or posted. If the initial state is
reset, a thread that calls DosWaitEventSem will be blocked until a process
that has access to the semaphore uses DosPostEventSem to post the event
semaphore. If the initial state is posted, then a thread that calls
DosWaitEventSem will return immediately to continue its execution. If the
thread calling DosWaitEventSem is not in the process that created the
semaphore, the thread must open the semaphore with DosOpenEventSem before
calling DosWaitEventSem.
The operating system maintains a usage count for each semaphore.
DosCreateEventSem initializes the usage count to 1. Thereafter, each call to
DosOpenEventSem increments the count, and each call to DosCloseEventSem
decrements it.
ΓòÉΓòÉΓòÉ 7.2.2. Opening an Event Semaphore ΓòÉΓòÉΓòÉ
When a process creates an event semaphore, all of the threads that belong to
the process have immediate access to the semaphore.
Threads in other processes must open the semaphore by calling DosOpenEventSem
before they can use the semaphore in any other event semaphore function.
The following code fragment shows how processes can open an event semaphore
that was created in a different process and then wait for the event to be
posted:
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
HEV hevEventHandle = 0; /* Must be 0 because we are opening */
/* the semaphore by name */
DosOpenEventSem("\\sem32\\wrtevent", &hevEventHandle);
DosWaitEventSem(hevEventHandle,
SEM_INDEFINITE_WAIT); /* Waits until event is posted */
.
. /* Read from file when event is posted. */
.
Applications can open an event semaphore by name or by handle. If the name is
used to open the semaphore, as in the code fragment above, the handle parameter
must be 0. If the handle is used to open the semaphore, the name parameter must
be NULL.
Access to semaphores is on a per-process basis. Therefore, a semaphore that has
been opened by one thread in a process is open to all other threads in that
process as well.
DosOpenEventSem merely provides access to an event semaphore. In order to wait
for an event semaphore to be posted, a thread must call DosWaitEventSem. In
order to post or reset an open event semaphore, a thread uses DosPostEventSem
or DosResetEventSem respectively.
When a process no longer requires access to an event semaphore, it closes the
semaphore by calling DosCloseEventSem. If a process ends without closing an
open semaphore, the semaphore is closed by the operating system.
Each call to DosOpenEventSem increments the usage count of the semaphore. This
count is initialized to 1 when the semaphore is created and is decremented by
each call to DosCloseEventSem. When the usage count reaches 0, the semaphore is
deleted by the operating system.
Calls to DosOpenEventSem and DosCloseEventSem can be nested, but the usage
count for a semaphore cannot exceed 65535. If an attempt is made to exceed this
number, ERROR_TOO_MANY_OPENS is returned.
ΓòÉΓòÉΓòÉ 7.2.3. Closing an Event Semaphore ΓòÉΓòÉΓòÉ
When a process no longer requires access to an event semaphore, it closes the
semaphore by calling DosCloseEventSem.
The following code fragment closes an event semaphore. Assume that the handle
of the semaphore has been placed into HEV already.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HEV hev; /* Event semaphore handle */
APIRET rc; /* Return code */
rc = DosCloseEventSem(hev);
if (rc != 0) {
printf("DosCloseEventSem error: return code = %ld", rc);
return;
}
Calls to DosOpenEventSem and DosCloseEventSem can be nested, but the usage
count for a semaphore cannot exceed 65535. If an attempt is made to exceed this
number, ERROR_TOO_MANY_OPENS is returned.
If a process ends without closing an open semaphore, the semaphore is closed by
the operating system.
Each call to DosCloseEventSem decrements the usage count of the semaphore. This
count is initialized to 1 when the semaphore is created and is incremented by
each call to DosOpenEventSem. When the usage count reaches 0, the semaphore is
deleted from the operating system. The call to DosCloseEventSem that decrements
the usage count to 0 and causes the semaphore to be deleted is referred to as
the final close. If a thread attempts to perform the final close for a
semaphore while another thread in the same process is still waiting for it,
ERROR_SEM_BUSY is returned.
ΓòÉΓòÉΓòÉ 7.2.4. Resetting an Event Semaphore ΓòÉΓòÉΓòÉ
DosResetEventSem resets an event semaphore if it is not already reset, and
returns the number of times the semaphore was posted since it was last reset.
All threads that subsequently call DosWaitEventSem for this semaphore will be
blocked.
Any thread belonging to the process that created the event semaphore can change
the state of the semaphore to reset by calling DosResetEventSem. Threads in
other processes can also call DosResetEventSem, but they must first gain access
to the semaphore by calling DosOpenEventSem.
When an event semaphore is in the reset state, any thread that calls
DosWaitEventSem to wait for the semaphore will be blocked. When the event
semaphore is posted, all of the threads that are waiting for the semaphore are
released to continue execution.
The following code fragment resets an event semaphore. Assume that the handle
of the semaphore has been placed into HEV already.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HEV hev; /* Event semaphore handle */
ULONG ulPostCt; /* Post count for the event semaphore (returned) */
APIRET rc; /* Return code */
rc = DosResetEventSem(hev, &ulPostCt);
if (rc != 0) {
printf("DosResetEventSem error: return code = %ld", rc);
return;
}
DosResetEventSem returns the post count of the event semaphore and resets the
post count to 0. The post count is the number of times the semaphore has been
posted (using DosPostEventSem) since the last time the semaphore was in the
reset state. (An event semaphore can be reset when it is created, as well as by
calling DosResetEventSem.) The post count can also be obtained by calling
DosQueryEventSem.
If the event semaphore is already reset when DosResetEventSem is called,
ERROR_ALREADY_RESET is returned, along with a post count of 0. The semaphore is
not reset a second time.
ΓòÉΓòÉΓòÉ 7.2.5. Posting an Event Semaphore ΓòÉΓòÉΓòÉ
DosPostEventSem posts the semaphore, if it is not already posted, and
increments the post count. All threads that have called DosWaitEventSem for
this semaphore are unblocked and resume execution. Threads that call
DosWaitEventSem after the event semaphore has been posted and before the next
time it is reset, will return immediately from a call to DosWaitEventSem and
continue execution. If the semaphore is subsequently reset, threads that call
DosWaitEventSem will again be blocked.
Any thread in the process that created an event semaphore can post the
semaphore by calling DosPostEventSem. Threads in other processes can also call
DosPostEventSem, but they must first gain access to the semaphore by calling
DosOpenEventSem.
The following code fragment posts a system event semaphore. Assume that the
handle of the semaphore has been placed into HEV already.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HEV hev; /* Event semaphore handle */
APIRET rc; /* Return code */
rc = DosPostEventSem(hev);
if (rc != 0) {
printf("DosPostEventSem error: return code = %ld", rc);
return;
}
The operating system maintains a post count for each event semaphore. The post
count is the number of times the semaphore has been posted (with
DosPostEventSem) since the last time the semaphore was in the reset state.
If the event semaphore is reset when DosPostEventSem is called, the semaphore
is posted and the post count is set to 1. If the event semaphore is already
posted when DosPostEventSem is called, the post count is incremented, and
ERROR_ALREADY_POSTED is returned to the calling thread.
The post count is returned as output by DosResetEventSem; it can also be
obtained by calling DosQueryEventSem.
The maximum number of times an event semaphore can be posted is 65535. The
value of the post count cannot exceed 65535. If an attempt is made to exceed
this number, DosPostEventSem returns ERROR_TOO_MANY_POSTS.
ΓòÉΓòÉΓòÉ 7.2.6. Waiting for an Event Semaphore ΓòÉΓòÉΓòÉ
Any thread in the process that created an event semaphore can wait for the
semaphore to be posted by calling DosWaitEventSem. Threads in other processes
can also call DosWaitEventSem, but they must first gain access to the semaphore
by calling DosOpenEventSem.
If the semaphore is already posted when DosWaitEventSem is called, the function
returns immediately, and the thread continues to run. Otherwise, the thread is
blocked until the semaphore is posted.
The following code fragment causes the calling thread to wait until the
specified event semaphore is posted. Assume that the handle of the semaphore
has been placed into HEV already. ulTimeout is the number of milliseconds that
the calling thread will wait for the event semaphore to be posted. If the
specified event semaphore is not posted during this time interval, the request
times out.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HEV hev; /* Event semaphore handle */
ULONG ulTimeout; /* Number of milliseconds to wait */
APIRET rc; /* Return code */
ulTimeout = 60000; /* Wait for a maximum of 1 minute */
rc = DosWaitEventSem(hev, ulTimeout);
if (rc == ERROR_TIMEOUT) {
printf("DosWaitEventSem call timed out");
return;
}
if (rc == ERROR_INTERRUPT) {
printf("DosWaitEventSem call was interrupted");
return;
}
if (rc != 0) {
printf("DosWaitEventSem error: return code = %ld", rc);
return;
}
If the time limit specified in ulTimeout is reached before the semaphore is
posted, ERROR_TIMEOUT is returned. If the waiting period is interrupted for
some reason before the semaphore is posted, ERROR_INTERRUPT is returned. If
SEM_IMMEDIATE_RETURN is specified for the time limit, DosWaitEventSem returns
to the calling thread immediately. If SEM_INDEFINITE_WAIT is specified for the
time limit, the thread waits indefinitely.
Unlike multiple event semaphores in a muxwait list, which are level-triggered,
single event semaphores are edge-triggered. This means that if an event
semaphore is posted and then reset before a waiting thread gets a chance to
run, the semaphore is considered to be posted for the rest of that thread's
waiting period; the thread does not have to wait for the semaphore to be posted
again.
ΓòÉΓòÉΓòÉ 7.2.7. Querying an Event Semaphore ΓòÉΓòÉΓòÉ
DosQueryEventSem returns the current post count of a semaphore. The post count
is the number of times that the semaphore has been posted (with
DosPostEventSem) since the last time the semaphore was reset. A count of 0
indicates that the semaphore is in the reset state; therefore, the operating
system will block any threads that call DosWaitEventSem to wait on the
semaphore.
Any thread in the process that created an event semaphore can obtain the post
count for the semaphore by calling DosQueryEventSem. Threads in other processes
can also call DosQueryEventSem, but they must first gain access to the
semaphore by calling DosOpenEventSem.
The following code fragment retrieves the post count for an event semaphore.
Assume that the handle of the semaphore has been placed into HEV already.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HEV hev; /* Event semaphore handle */
ULONG ulPostCt; /* Current post count for the semaphore (returned) */
APIRET rc; /* Return code */
rc = DosQueryEventSem(hev, &ulPostCt);
if (rc != 0) {
printf("DosQueryEventSem error: return code = %ld", rc);
return;
}
If the specified event semaphore does not exist, ERROR_INVALID_HANDLE is
returned.
ΓòÉΓòÉΓòÉ 7.3. Using Mutex Semaphores ΓòÉΓòÉΓòÉ
An application can use a mutual exclusion (mutex) semaphore to protect a shared
resource from simultaneous access by multiple threads or processes. For
example, if several processes must write to the same disk file, the mutex
semaphore ensures that only one process at a time writes to the file.
ΓòÉΓòÉΓòÉ 7.3.1. Creating a Mutex Semaphore ΓòÉΓòÉΓòÉ
Mutex semaphores are created by calling DosCreateMutexSem. This function also
opens the semaphore for the calling process and its threads.
When a mutex semaphore is created, a flag is set to specify the initial state
of the semaphore, owned or unowned. If the semaphore is owned by a thread,
other threads requesting the semaphore are blocked. If the semaphore is
unowned-not owned by any thread- then any thread requesting ownership will be
granted ownership immediately.
If the calling thread sets the initial state to owned, it owns the semaphore as
soon as the operating system creates the semaphore and can proceed to access
the resource that the semaphore was created to protect.
If the semaphore is unowned, any thread in the creating process can
subsequently request ownership of the semaphore by calling DosRequestMutexSem.
Threads in other processes can gain ownership of the semaphore, but they must
call DosOpenMutexSem to acquire access to the semaphore before they can call
DosRequestMutexSem.
Mutex semaphores can be defined as either private or shared.
o Private semaphores are always unnamed and are therefore identified by
their handles. They can be used only by threads within a single process.
o Shared semaphores can be either named or unnamed. If named, they can be
opened using either the name or the handle. The handle returned by
DosOpenMutexSem is then used to identify the semaphore for all other
functions. Semaphore names must include the prefix \SEM32\ and must
conform to file system naming conventions. Shared semaphores can be used
by threads in multiple processes.
The following code fragment creates a mutex semaphore:
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
HMTX hmtxProtFile;
DosCreateMutexSem("\\sem32\\ProtFile", /* Named-shared semaphore */
&hmtxProtFile, 0, FALSE); /* Initially unowned */
.
. /* Get data to write to shared file. */
.
There is a system-wide limit of 65536 shared semaphores (including mutex,
event, and muxwait semaphores); in addition, each process can have up to 65536
private semaphores.
The operating system maintains a usage count for each semaphore.
DosCreateMutexSem initializes the usage count to 1. Thereafter, each call to
DosOpenMutexSem increments the count, and each call to DosCloseMutexSem
decrements it.
ΓòÉΓòÉΓòÉ 7.3.2. Opening a Mutex Semaphore ΓòÉΓòÉΓòÉ
All of the threads belonging to the process that creates a mutex semaphore have
immediate access to the semaphore. Threads in other processes must request
access to the semaphore by calling DosOpenMutexSem before they can use the
semaphore in other mutex semaphore functions.
Access to system resources is granted on a per-process basis. Therefore, a
semaphore that has been opened by one thread in a process is open to all other
threads in that process as well.
DosOpenMutexSem merely provides access to a mutex semaphore. To request
ownership of a mutex semaphore, a thread must call DosRequestMutexSem.
When a process no longer requires access to a mutex semaphore, it should close
the semaphore by calling DosCloseMutexSem. However, if a process ends without
closing an open semaphore, the semaphore is closed by the operating system.
Each call to DosOpenMutexSem. increments the usage count of the semaphore. This
count is initialized to 1 when the semaphore is created and is decremented by
each call to DosCloseMutexSem. When the usage count reaches 0, the semaphore is
deleted by the system.
Calls to DosOpenMutexSem and DosCloseMutexSem. can be nested, but the usage
count for a semaphore cannot exceed 65535. If an attempt is made to exceed this
number, ERROR_TOO_MANY_OPENS is returned.
If a process ends without releasing a mutex semaphore that it owns, any other
thread that subsequently tries to open the semaphore will receive
ERROR_SEM_OWNER_DIED. This return code indicates that the owning process ended
abnormally, leaving the protected resource in an indeterminate state. However,
the semaphore is still opened for the calling thread, enabling the thread to
call DosQueryMutexSem to find out which process ended without releasing the
semaphore. The thread can then take appropriate action concerning the semaphore
and the protected resource.
ΓòÉΓòÉΓòÉ 7.3.3. Requesting a Mutex Semaphore ΓòÉΓòÉΓòÉ
In order to access a shared resource, a process must own the mutex semaphore
that is protecting the shared resource. Ownership is obtained by first opening
the mutex semaphore with DosOpenMutexSem, then using DosRequestMutexSem to
request ownership of the semaphore. If another process already owns the
semaphore, the requesting process is blocked. If the semaphore is not owned,
the operating system grants ownership to the requesting process and the process
can access the shared resource. When the process is finished using the shared
resource, it uses DosReleaseMutexSem to relinquish its ownership of the
semaphore, thereby enabling another process to gain ownership.
A process can gain ownership of a mutex semaphore in three ways:
1. The thread that creates a mutex semaphore can designate itself as the
owner by setting a flag when it calls DosCreateMutexSem.
2. Any thread in the process that created the semaphore can request
ownership by calling DosRequestMutexSem.
3. A thread in another process must request access to the semaphore with
DosOpenMutexSem before it can call DosRequestMutexSem.
Note that ownership of a mutex semaphore is given only to the requesting
thread; it is not shared by other threads in the same process.
If a mutex semaphore is unowned, DosRequestMutexSem sets it as owned and
returns immediately to the caller. If the semaphore is already owned, the
calling thread is blocked until either the owning thread calls
DosReleaseMutexSem to release the semaphore, or a specified time limit is
reached.
The following code fragment shows how a process opens a mutex semaphore,
requests it, and, after writing to the shared file, releases and closes the
semaphore:
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
HMTX hmtxProtFile;
DosOpenMutexSem("\\sem32\\ProtFile",
&hmtxProtFile); /* Opens for this process */
DosRequestMutexSem(hmtxProtFile, 5000); /* Returns in 5 seconds if */
. /* Ownership not obtained */
. /* Write data to shared file. */
.
DosReleaseMutexSem(hmtxProtFile); /* Releases ownership */
.
. /* Continue execution. */
.
DosCloseMutexSem(hmtxProtFile); /* Finished with shared file */
If more than one thread is blocked on a DosRequestMutexSem request, the thread
with the highest priority level is the first to be unblocked and given
ownership of the semaphore. If more than 1 of the waiting threads have the
same priority level, then FIFO ordering is used to determine which thread is
unblocked and given ownership.
The time-out parameter (5000 milliseconds in the example above) places a limit
on the amount of time a thread blocks on a DosRequestMutexSem request. If the
time limit is reached before the thread gains ownership of the semaphore,
ERROR_TIMEOUT is returned. If SEM_IMMEDIATE_RETURN is specified for the time
limit, DosRequestMutexSem returns without blocking the thread. The thread can
then perform other operations and call DosRequestMutexSem again later if it
still requires access to the protected resource. If SEM_INDEFINITE_WAIT is
specified for the time limit, the thread waits indefinitely. If the thread is
unblocked by an external event while it is waiting for the mutex semaphore (as
when a No Wait I/O request has just been completed), ERROR_INTERRUPT is
returned to the caller.
In addition to the usage count that the operating system maintains for all
semaphores, the operating system maintains a request count for each mutex
semaphore. Each call to DosRequestMutexSem increments the count, and each call
to DosReleaseMutexSem decrements it.
Calls to DosRequestMutexSem and DosReleaseMutexSem can be nested, but the
request count for a semaphore cannot exceed 65535. If an attempt is made to
exceed this number, ERROR_TOO_MANY_SEM_REQUESTS is returned. When calls to
DosRequestMutexSem and DosReleaseMutexSem are nested, a call to
DosReleaseMutexSem merely decrements the request count for the semaphore; the
semaphore is not actually released to another thread until its request count
is 0. If a process ends while it owns a mutex semaphore, all of the currently
blocked DosRequestMutexSem requests, as well as any future requests for the
semaphore, return ERROR_SEM_OWNER_DIED. This return code indicates that the
owning process ended abnormally, leaving the protected resource in an
indeterminate state. An application that receives this error should close the
mutex semaphore (so that it can be deleted from the operating system), because
it is no longer valid. Appropriate action should also be taken concerning the
protected resource.
ΓòÉΓòÉΓòÉ 7.3.4. Releasing a Mutex Semaphore ΓòÉΓòÉΓòÉ
A thread can release ownership of a mutex semaphore by calling
DosReleaseMutexSem. Each call to DosReleaseMutexSem decrements the request
count that is maintained for the semaphore by the operating system. Each call
to DosRequestMutexSem increments the count.
The following code fragment relinquishes ownership of a mutex semaphore. Assume
that the handle of the semaphore has been placed into hmtx already.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HMTX hmtx; /* Mutex semaphore handle */
APIRET rc; /* Return code */
rc = DosReleaseMutexSem(hmtx);
if (rc != 0) {
printf("DosReleaseMutexSem error: return code = %ld", rc);
return;
}
Calls to DosRequestMutexSem and DosReleaseMutexSem can be nested, but the
request count cannot exceed 65535. If an attempt is made to exceed this number,
ERROR_TOO_MANY_SEM_REQUESTS is returned. When calls to DosRequestMutexSem and
DosReleaseMutexSem are nested, a call to DosReleaseMutexSem merely decrements
the request count for the semaphore; the semaphore is not actually released to
another thread until its request count is 0.
ΓòÉΓòÉΓòÉ 7.3.5. Closing a Mutex Semaphore ΓòÉΓòÉΓòÉ
When a process no longer requires access to a mutex semaphore, it can close the
semaphore by calling DosCloseMutexSem. However, if a process ends without
closing an open semaphore, the semaphore is closed by the operating system.
The following code fragment closes a mutex semaphore. Assume that the handle of
the semaphore has been placed into hmtx already.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HMTX hmtx; /* Mutex semaphore handle */
APIRET rc; /* Return code */
rc = DosCloseMutexSem(hmtx);
if (rc != 0) {
printf("DosCloseMutexSem error: return code = %ld", rc);
return;
}
Each call to DosCloseMutexSem decrements the usage count of the semaphore. This
count is initialized to 1 when the semaphore is created and is incremented by
each call to DosOpenMutexSem. When the usage count reaches 0, the semaphore is
deleted by the operating system.
The call to DosCloseMutexSem that decrements the usage count to 0 and causes
the semaphore to be deleted is referred to as the final close. The final close
will not succeed if either of the following conditions exists:
o The semaphore is owned by another thread in the same process.
o Another thread in the same process is still blocked on a
DosRequestMutexSem request for the semaphore.
For both conditions, ERROR_SEM_BUSY is returned.
ERROR_SEM_BUSY is also returned if a thread tries to close a mutex semaphore
that it still owns. The thread must first relinquish ownership of the
semaphore by calling DosReleaseMutexSem.
Calls to DosOpenMutexSem and DosCloseMutexSem can be nested, but the usage
count for a semaphore cannot exceed 65535. If an attempt is made to exceed
this number, ERROR_TOO_MANY_OPENS is returned.
ΓòÉΓòÉΓòÉ 7.3.6. Querying a Mutex Semaphore ΓòÉΓòÉΓòÉ
An application can use DosQueryMutexSem to determine the current owner of a
mutex semaphore and to obtain a count of the number of requests on it. If the
mutex semaphore is not owned, the request count is 0.
Any thread in the process that created a mutex semaphore can obtain information
about the semaphore by calling DosQueryMutexSem. Threads in other processes can
also call DosQueryMutexSem, but they must first gain access to the semaphore by
calling DosOpenMutexSem.
If the mutex semaphore exists and is owned, DosQueryMutexSem returns the
process and thread identifications of the owner, as well as the request count
for the semaphore. The request count is the number of DosRequestMutexSem calls
minus the number of DosReleaseMutexSem calls that have been made for the
semaphore by the owning thread.
If DosQueryMutexSem returns a request count of 0, the mutex semaphore is
unowned.
If the owning process ended without calling DosCloseMutexSem, then
ERROR_SEM_OWNER_DIED is returned, and the output parameters contain information
about the ended owning process.
ΓòÉΓòÉΓòÉ 7.4. Using Muxwait Semaphores ΓòÉΓòÉΓòÉ
A process that requires exclusive use of several shared resources at once can
use a multiple wait (muxwait) semaphore to obtain ownership of all the mutex
semaphores protecting the shared resources. A process can also use a muxwait
semaphore to wait on a group of event semaphores so that the process continues
running whenever events of interest occur.
A muxwait semaphore can refer to up to 64 event or mutex semaphores. An
application cannot refer to event and mutex semaphores in a single muxwait
semaphore, or include a muxwait semaphore in another muxwait semaphore.
ΓòÉΓòÉΓòÉ 7.4.1. Creating a Muxwait Semaphore ΓòÉΓòÉΓòÉ
DosCreateMuxWaitSem is used to create muxwait semaphores. This function also
opens (obtains access to) the semaphore for the calling process and its
threads. Threads in other processes must call DosOpenMuxWaitSem to open the
semaphore before they can use it in any other muxwait semaphore function.
All the semaphores in the muxwait list must be created and opened before the
muxwait list can be created.
The following code fragment creates five event semaphores and a corresponding
array of semaphore records. The array is used to specify the semaphores
included in the muxwait semaphore in the subsequent call to
DosCreateMuxWaitSem.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
ULONG ulLoop, ulSem;
HMUX hmuxHandAny;
SEMRECORD apsr[5];
/* Create event semaphores and fill semaphore-record array. */
for (ulLoop = 0; ulLoop < 5; ulLoop++) { /* Create 5 private events */
DosCreateEventSem((PSZ) NULL,
(PHEV) &apsr[ulLoop].hsemCur,
0,
FALSE);
apsr[ulLoop].ulUser = ulLoop; /* User-assigned data */
}
.
.
.
DosCreateMuxWaitSem((PSZ) NULL,
&hmuxHandAny, /* Creates the muxwait semaphore */
sizeof(apsr),
apsr, /* Specifies semrecord array */
DCMW_WAIT_ANY);
DosWaitMuxWaitSem(hmuxHandAny, /* Waits until one is posted */
SEM_INDEFINITE_WAIT, &ulSem);
.
. /* Execution will continue when any event is posted. */
.
Muxwait semaphores can be defined as either private or shared:
o Private semaphores are always unnamed and are therefore always identified
by their handles. They can be used only by threads within a single
process.
o Shared semaphores can be either named or unnamed. If named, they can be
opened using either the name or the handle. The handle returned by
DosOpenMuxWaitSem is then used to identify the semaphore for all other
functions. Semaphore names must include the prefix \SEM32\ and must
conform to file system naming conventions. Shared semaphores can be used
by threads in multiple processes.
There is a system-wide limit of 65536 (64K) shared semaphores (including
mutex, event, and muxwait semaphores); in addition, each process can have up
to 65536 (64K) private semaphores.
The following conditions apply to the kinds of semaphores that can be included
in a muxwait-semaphore list:
o The list must contain either mutex semaphores or event semaphores. It
cannot contain both at the same time and it cannot contain other muxwait
semaphores.
o If the muxwait semaphore is shared, then all the semaphores in the list
must also be shared.
o If the muxwait semaphore is private, then the semaphores in its list can
be either private or shared.
If any of these conditions is violated, ERROR_WRONG_TYPE is returned.
The muxwait list can contain a maximum of 64 event semaphores or mutex
semaphores. If an attempt is made to exceed this maximum,
ERROR_TOO_MANY_SEMAPHORES is returned.
If the owners of any of the mutex semaphores in the muxwait semaphore list
have ended without releasing them, ERROR_SEM_OWNER_DIED is returned. The
thread should call DosQueryMutexSem for each mutex semaphore in the
muxwait-semaphore list so that it can determine which semaphores are in the
Owner Died state.
Each mutex semaphore that returns ERROR_SEM_OWNER_DIED from the query should
be closed by calling DosCloseMutexSem. Also, because semaphore handles can be
reused, the mutex semaphores that are closed must be deleted from the
muxwait-semaphore list by calling DosDeleteMuxWaitSem.
The operating system maintains a usage count for each semaphore.
DosCreateMuxWaitSem initializes the usage count to 1. Thereafter, each call to
DosOpenMuxWaitSem increments the count, and each call to DosCloseMuxWaitSem
decrements it.
One parameter of this function is a pointer to an array of SEMRECORD data
structures. Each data structure contains one semaphore record for each of the
semaphores to be included in the muxwait semaphore. A semaphore record
contains the handle and a programmer-defined identifier for that semaphore.
ΓòÉΓòÉΓòÉ 7.4.2. Opening a Muxwait Semaphore ΓòÉΓòÉΓòÉ
Processes other than the semaphore-creating process must use DosOpenMuxWaitSem
to gain access to the muxwait semaphore before they can use the semaphore in
any other muxwait semaphore function. All of the threads that belong to the
process that creates the muxwait semaphore have immediate access to the
semaphore.
The following code fragment opens a system muxwait semaphore.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
UCHAR Name[40]; /* Semaphore name */
HMUX hmux; /* Muxwait semaphore handle */
APIRET rc; /* Return code */
strcpy(Name, "\\SEM32\\MUXWAIT1"); /* Name of the system muxwait semaphore */
rc = DosOpenMuxWaitSem(Name, &hmux);
if (rc != 0) {
printf("DosOpenMuxWaitSem error: return code = %ld", rc);
return;
}
On successful return, hmux contains the handle of the system muxwait semaphore.
Opening a muxwait semaphore does not open the semaphores in its muxwait list. A
process must open each of the semaphores included in a muxwait semaphore before
it opens the muxwait semaphore. Otherwise, DosOpenMuxWaitSem returns the
ERROR_INVALID_HANDLE error value to the calling function.
Access to semaphores is on a per-process basis. Therefore, a semaphore that has
been opened by one thread in a process is open to all other threads in that
process as well.
Note that DosOpenMuxWaitSem merely provides access to a muxwait semaphore. In
order to wait for a muxwait semaphore to clear, a thread must call
DosWaitMuxWaitSem.
When a process no longer requires access to a muxwait semaphore, it closes the
semaphore by calling DosCloseMuxWaitSem. However, if a process ends without
closing an open semaphore, the semaphore is closed by the operating system.
Each call to DosOpenMuxWaitSem increments the usage count of the semaphore.
This count is initialized to 1 when the semaphore is created and is decremented
by each call to DosCloseMuxWaitSem. When the usage count reaches 0, the
semaphore is deleted by the operating system.
Calls to DosOpenMuxWaitSem and DosCloseMuxWaitSem can be nested, but the usage
count for a semaphore cannot exceed 65535. If an attempt is made to exceed this
number, ERROR_TOO_MANY_OPENS is returned.
Even if the owner of a mutex semaphore in a muxwait-semaphore list has ended
without releasing the semaphore, the muxwait semaphore is still opened.
Subsequent calls to the muxwait semaphore will return ERROR_SEM_OWNER_DIED. But
because the process has opened the semaphore, it can then call
DosQueryMuxWaitSem to identify all the mutex semaphores in the muxwait list.
Next, the process can call DosQueryMutexSem for each mutex semaphore in the
list to find out which ones are in the Owner Died state. Each mutex semaphore
that returns ERROR_SEM_OWNER_DIED from the query should be closed by calling
DosCloseMutexSem. Also, because semaphore handles can be reused, the mutex
semaphores that are closed should be deleted from the muxwait-semaphore list by
calling DosDeleteMuxWaitSem.
ΓòÉΓòÉΓòÉ 7.4.3. Closing a Muxwait Semaphore ΓòÉΓòÉΓòÉ
When a process no longer requires access to a muxwait semaphore, it closes the
semaphore by calling DosCloseMuxWaitSem. However, if a process ends without
closing an open semaphore, the semaphore is closed by the operating system.
Each call to DosCloseMuxWaitSem decrements the usage count of the semaphore.
This count is initialized to 1 when the semaphore is created and is incremented
by each call to DosOpenMuxWaitSem. When the usage count reaches 0, the
semaphore is deleted by the operating system.
The call to DosCloseMuxWaitSem that decrements the usage count to 0 and causes
the semaphore to be deleted is referred to as the final close. If a thread
attempts to perform the final close for a semaphore while another thread in the
same process is still waiting for it, ERROR_SEM_BUSY is returned.
Calls to DosOpenMuxWaitSem and DosCloseMuxWaitSem can be nested, but the usage
count for a semaphore cannot exceed 65535. If an attempt is made to exceed this
number, ERROR_TOO_MANY_OPENS is returned.
ΓòÉΓòÉΓòÉ 7.4.4. Waiting for a Muxwait Semaphore ΓòÉΓòÉΓòÉ
A thread can wait on a muxwait semaphore by using DosWaitMuxWaitSem.
Any thread in the process that created a muxwait semaphore can wait for the
semaphore to clear by calling DosWaitMuxWaitSem. Threads in other processes can
also call DosWaitMuxWaitSem, but they must first gain access to the semaphore
by calling DosOpenMuxWaitSem.
The following code fragment waits for a muxwait semaphore to clear. Assume that
the handle of the semaphore has been placed into hmux already. ulTimeout is the
number of milliseconds that the calling thread will wait for the muxwait
semaphore to clear. If the specified muxwait semaphore is not cleared during
this time interval, the request times out.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
HMUX hmux; /* Muxwait semaphore handle */
ULONG ulTimeout; /* Number of milliseconds to wait */
ULONG ulUser; /* User field for the semaphore that was */
/* posted or released (returned) */
APIRET rc; /* Return code */
ulTimeout = 60000; /* Wait for a maximum of 1 minute */
rc = DosWaitMuxWaitSem(hmux, ulTimeout, &ulUser);
if (rc == ERROR_TIMEOUT) {
printf("DosWaitMuxWaitSem call timed out");
return;
}
if (rc == ERROR_INTERRUPT) {
printf("DosWaitMuxWaitSem call was interrupted");
return;
}
if (rc != 0) {
printf("DosWaitMuxWaitSem error: return code = %ld", rc);
return;
}
On successful return, the ulUser variable contains the user identifier of the
semaphore that caused the wait to terminate. If the caller had to wait for all
the semaphores within the muxwait semaphore to clear, then the value
corresponds to the last semaphore within the muxwait semaphore to clear. If the
caller had to wait for any semaphore with the muxwait semaphore to clear, then
the value corresponds to that semaphore.
An application can use the DCMW_WAIT_ANY flag in DosCreateMuxWaitSem to block a
thread until any one of the event or mutex semaphores included in the muxwait
semaphore is posted or released. If the muxwait semaphore refers to mutex
semaphores, the thread only gains ownership of the one mutex semaphore that was
released.
An application can use the DCMW_WAIT_ALL flag in DosCreateMuxWaitSem to block a
thread until all of the event or mutex semaphores included in the muxwait
semaphore are posted or released. If the muxwait semaphore refers to mutex
semaphores, the thread does not gain ownership of any of the mutex semaphores
until they are all released. When all are released, the thread becomes owner of
all the mutex semaphores included in the muxwait semaphore. If the muxwait
semaphore refers to event semaphores, the thread will not run until all of the
event semaphores are in the posted state at the same time. This is because
event semaphores in a muxwait list are level-triggered, unlike individual event
semaphores, which are edge-triggered.
For example, suppose that a thread is waiting for five event semaphores in a
muxwait list to be posted. The first semaphore is posted and then reset. Next,
the remaining semaphores are all posted, and they remain in the posted state.
The thread that is waiting for the muxwait semaphore will not run until the
first semaphore is posted again.
If an application specifies the DCMW_WAIT_ANY flag when the semaphore is
created, DosWaitMuxWaitSem returns the programmer-defined identifier of the
semaphore that is subsequently posted or released. If an application specifies
the DCMW_WAIT_ALL flag, DosWaitMuxWaitSem returns the programmer-defined
identifier of the last semaphore that was posted or released.
The ulTimeout parameter places a limit on the amount of time a thread blocks on
a DosWaitMuxWaitSem request. If the time limit is reached before the semaphore
has cleared, ERROR_TIMEOUT is returned. If SEM_IMMEDIATE_RETURN is specified as
the time limit, DosWaitMuxWaitSem returns without blocking the thread. The
thread can then go on to perform other operations and call DosWaitMuxWaitSem
again later to wait for the event or mutex semaphores in the muxwait list to be
posted or released. If a time limit of SEM_INDEFINITE_WAIT is specified, the
thread waits (is blocked) indefinitely. If the thread is unblocked by an
external event while it is waiting for the muxwait semaphore (as when a "no
wait" I/O request has just been completed), DosWaitMuxWaitSem returns
ERROR_INTERRUPT.
When a thread is waiting for any one of the semaphores in a muxwait list to be
posted or released, the semaphores are checked in the order in which they are
defined in the list.
Waiting for Multiple Event Semaphores
The following information pertains only to muxwait semaphores that consist of
multiple event semaphores:
Unlike individual event semaphores, which are edge-triggered, event semaphores
in a muxwait list are level-triggered. This means that if a thread is waiting
for all of the event semaphores in the muxwait list, it will not run until all
of the event semaphores are in the posted state at the same time.
For example, a thread is waiting for five event semaphores in a muxwait list to
be posted. The first semaphore is posted and then reset. Next, the remaining
semaphores are all posted, and they remain in the posted state. The thread that
is waiting for the muxwait semaphore will not run until the first semaphore is
posted again.
Waiting for Multiple Mutex Semaphores
The following information pertains only to muxwait semaphores that consist of
multiple mutex semaphores:
o If a thread is waiting for all of the mutex semaphores in a muxwait list
to be released, it does not receive ownership of any of the semaphores
until all of the semaphores have been released.
o If a thread is waiting for any one of the mutex semaphores in a muxwait
list, then the thread gains ownership only of the first mutex semaphore
that is released. The ownership of all other mutex semaphores in the
muxwait list remains unchanged.
o If two threads have the same priority, then a thread that is waiting for
a mutex semaphore in a muxwait list takes precedence over a thread that
has requested ownership of only the individual semaphore, provided all
other mutex semaphores in the muxwait list have been released. For
example, a mutex semaphore that is part of a muxwait semaphore is
released. One thread has requested ownership of that single mutex
semaphore, and another thread with the same priority is waiting for the
muxwait semaphore that contains the same mutex semaphore. If all of the
other mutex semaphores in the muxwait list are unowned and ready to be
given to the muxwait semaphore, then the thread that is waiting for the
muxwait semaphore will run first.
o If the owners of any of the mutex semaphores in the muxwait semaphore
list have ended without releasing them, ERROR_SEM_OWNER_DIED is returned.
The thread must then call DosQueryMuxWaitSem to obtain the records of all
the semaphores in the muxwait list. Next, the thread must call
DosQueryMutexSem for each mutex semaphore in the muxwait-semaphore list
so that it can determine which semaphores are in the Owner Died state.
Each mutex semaphore that returns ERROR_SEM_OWNER_DIED from the query
should be closed by calling DosCloseMutexSem. Also, because semaphore
handles can be reused, the mutex semaphores that are closed should be
deleted from the muxwait-semaphore list by calling DosDeleteMuxWaitSem.
o If any of the mutex semaphores in the muxwait list are owned by the
calling thread, ERROR_MUTEX_OWNED is returned.
ΓòÉΓòÉΓòÉ 7.4.5. Adding a Semaphore to a Muxwait List ΓòÉΓòÉΓòÉ
An application uses DosAddMuxWaitSem to add semaphores to a muxwait semaphore
that has already been created, even while threads are waiting on the muxwait
semaphore.
Any thread in the process that created a muxwait semaphore can add a mutex
semaphore or an event semaphore to the muxwait list by calling
DosAddMuxWaitSem. Threads in other processes can also use this function, but
they must first gain access to the semaphore by calling DosOpenMuxWaitSem.
A maximum of 64 semaphores can be included in a muxwait-semaphore list. If an
attempt is made to exceed this maximum, ERROR_TOO_MANY_SEMAPHORES is returned.
All of the semaphores in a muxwait-semaphore list must be of the same type.
That is, if a mutex semaphore is being added, then the other semaphores in the
list must be mutex semaphores. If an event semaphore is being added, then the
other semaphores in the list must be event semaphores. A shared muxwait
semaphore can contain only shared semaphores in its list. A private muxwait
semaphore can contain both private and shared semaphores. If any of these
conditions is violated, ERROR_WRONG_TYPE is returned.
If the semaphore is successfully added to the muxwait list, DosAddMuxWaitSem
checks to see whether each thread that is waiting for the muxwait semaphore has
the newly added semaphore open in its process. The muxwait semaphore is invalid
for any waiting threads that do not have the newly added semaphore open in
their process; these threads are unblocked with a return code of
ERROR_INVALID_HANDLE. Any processes that opened the muxwait semaphore before
the add operation and that do not have the new semaphore open, will have to
open the new semaphore before making any further use of the muxwait semaphore.
Any future calls concerning the muxwait semaphore by processes that do not have
the new semaphore open will have ERROR_INVALID_HANDLE returned until the new
semaphore is opened.
A thread that receives a return code of ERROR_INVALID_HANDLE can take the
following corrective action:
1. First, the thread can obtain the records of all the semaphores in the
muxwait list by calling DosQueryMuxWaitSem.
2. Next, it can query each semaphore in the muxwait list, using
DosQueryMutexSem or DosQueryEventSem, to find out which semaphore is not
open to its process.
3. Finally, it can open the semaphores that are not open by calling
DosOpenMutexSem or DosOpenEventSem.
As soon as this semaphore is opened, the muxwait semaphore becomes valid again
for the process, as long as no other changes have been made to the muxwait
list to make it invalid. However, in order to successfully wait for the
muxwait semaphore, the process must call DosWaitMuxWaitSem again.
A semaphore must be open for a process before the process can add that
semaphore to a muxwait semaphore. If it is not open and a thread is waiting on
the muxwait semaphore, DosAddMuxWaitSem returns ERROR_INVALID_HANDLE to the
process adding the new semaphore, and the waiting thread continues waiting.
ΓòÉΓòÉΓòÉ 7.4.6. Deleting a Semaphore from a Muxwait List ΓòÉΓòÉΓòÉ
An application can delete semaphores from a muxwait semaphore by using
DosDeleteMuxWaitSem.
Any thread in the process that created a muxwait semaphore can delete a mutex
or event semaphore from the muxwait list by calling DosDeleteMuxWaitSem.
Threads in other processes can also use this function, but they must first gain
access to the semaphore by calling DosOpenMuxWaitSem.
Semaphores can be deleted from the muxwait list even while threads are
currently waiting for the semaphore. If the deleted semaphore is the only one
in the muxwait list that has not yet been posted or released, then threads that
are waiting for the muxwait semaphore are unblocked. Also, if the deleted
semaphore happens to be the last one that a particular thread was waiting for,
that thread is unblocked. Also, if the deleted semaphore is the last one in the
muxwait list (that is, if the list is now empty), then all the threads that are
waiting for the muxwait semaphore are unblocked.
ΓòÉΓòÉΓòÉ 7.4.7. Querying a Muxwait Semaphore ΓòÉΓòÉΓòÉ
Processes use DosQueryMuxWaitSem to obtain the semaph ore records for each of
the semaphores included in the muxwait semaphore.
Any thread in the process that created a muxwait semaphore can obtain
information about the semaphores in the muxwait list by calling
DosQueryMuxWaitSem. Threads in other processes can also use this function, but
they must first gain access to the semaphore by calling DosOpenMuxWaitSem.
An application must provide this function with an array in which to store the
semaphore records. If the array is not large enough to hold all of the
semaphore records that are in the muxwait list, then ERROR_PARAM_TOO_SMALL is
returned, and the record-counting parameter of DosQueryMuxWaitSem will contain
the number of semaphore records that are in the muxwait list. The calling
thread can then allocate the correct amount of space and call
DosQueryMuxWaitSem again with the correct amount of space for the list of
records.
If the owner of any mutex semaphore in the muxwait-semaphore list has ended
without releasing the semaphore, the records of all the semaphores in the list
are still returned, but DosQueryMuxWaitSem also returns ERROR_SEM_OWNER_DIED.
The calling thread can call DosQueryMutexSem for each mutex semaphore in the
muxwait-semaphore list so that it can determine which semaphores are in the
Owner Died state. The process can then close the unowned mutex semaphores.
Each mutex semaphore that returns ERROR_SEM_OWNER_DIED from the query should be
closed by calling DosCloseMutexSem. Also, because semaphore handles can be
reused, the mutex semaphores that are closed should be deleted from the
muxwait-semaphore list by calling DosDeleteMuxWaitSem.
If the specified muxwait semaphore does not exist, ERROR_INVALID_HANDLE is
returned.
ΓòÉΓòÉΓòÉ 8. Glossary ΓòÉΓòÉΓòÉ
This glossary defines many of the terms used in this book. It includes terms
and definitions from the IBM Dictionary of Computing, as well as terms specific
to the OS/2 operating system and the Presentation Manager. It is not a complete
glossary for the entire OS/2 operating system; nor is it a complete dictionary
of computer terms.
Other primary sources for these definitions are:
o The American National Standard Dictionary for Information Systems, ANSI
X3.172-1990, copyrighted 1990 by the American National Standards
Institute, 11 West 42nd Street, New York, New York 10036. These
definitions are identified by the symbol (A) after the definition.
o The Information Technology Vocabulary, developed by Subcommittee 1, Joint
Technical Committee 1, of the International Organization for
Standardization and the International Electrotechnical Commission
(ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are
identified by the symbol (I) after the definition; definitions taken from
draft international standards, committee drafts, and working papers being
developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the
definition, indicating that final agreement has not yet been reached
among the participating National Bodies of SC1.
ΓòÉΓòÉΓòÉ 8.1. Glossary Listing ΓòÉΓòÉΓòÉ
Select a starting letter of glossary terms:
A N
B O
C P
D Q
E R
F S
G T
H U
I V
J W
K X
L Y
M Z
ΓòÉΓòÉΓòÉ <hidden> Glossary - A ΓòÉΓòÉΓòÉ
accelerator - In SAA Common User Access architecture, a key or combination of
keys that invokes an application-defined function.
accelerator table - A table used to define which key strokes are treated as
accelerators and the commands they are translated into.
access mode - The manner in which an application gains access to a file it has
opened. Examples of access modes are read-only, write-only, and read/write.
access permission - All access rights that a user has regarding an object. (I)
action - One of a set of defined tasks that a computer performs. Users request
the application to perform an action in several ways, such as typing a
command, pressing a function key, or selecting the action name from an
action bar or menu.
action bar - In SAA Common User Access architecture, the area at the top of a
window that contains choices that give a user access to actions available in
that window.
action point - The current position on the screen at which the pointer is
pointing. Contrast with hot spot and input focus.
active program - A program currently running on the computer. An active
program can be interactive (running and receiving input from the user) or
noninteractive (running but not receiving input from the user). See also
interactive program and noninteractive program.
active window - The window with which the user is currently interacting.
address space - (1) The range of addresses available to a program. (A) (2)
The area of virtual storage available for a particular job.
alphanumeric video output - Output to the logical video buffer when the video
adapter is in text mode and the logical video buffer is addressed by an
application as a rectangular array of character cells.
American National Standard Code for Information Interchange - The standard
code, using a coded character set consisting of 7-bit coded characters (8
bits including parity check), that is used for information interchange among
data processing systems, data communication systems, and associated
equipment. The ASCII set consists of control characters and graphic
characters. (A)
Note: IBM has defined an extension to ASCII code (characters 128-255).
anchor - A window procedure that handles Presentation Manager* message
conversions between an icon procedure and an application.
anchor block - An area of Presentation-Manager-internal resources to allocated
process or thread that calls WinInitialize.
anchor point - A point in a window used by a program designer or by a window
manager to position a subsequently appearing window.
ANSI - American National Standards Institute.
APA - All points addressable.
API - Application programming interface.
application - A collection of software components used to perform specific
types of work on a computer; for example, a payroll application, an airline
reservation application, a network application.
application object - In SAA Advanced Common User Access architecture, a form
that an application provides for a user; for example, a spreadsheet form.
Contrast with user object.
application programming interface (API) - A functional interface supplied by
the operating system or by a separately orderable licensed program that
allows an application program written in a high-level language to use
specific data or functions of the operating system or the licensed program.
application-modal - Pertaining to a message box or dialog box for which
processing must be completed before further interaction with any other
window owned by the same application may take place.
area - In computer graphics, a filled shape such as a solid rectangle.
ASCII - American National Standard Code for Information Interchange.
ASCIIZ - A string of ASCII characters that is terminated with a byte
containing the value 0.
aspect ratio - In computer graphics, the width-to-height ratio of an area,
symbol, or shape.
asynchronous (ASYNC) - (1) Pertaining to two or more processes that do not
depend upon the occurrence of specific events such as common timing
signals. (T) (2) Without regular time relationship; unexpected or
unpredictable with respect to the execution of program instructions. See
also synchronous.
atom - A constant that represents a string. As soon as a string has been
defined as an atom, the atom can be used in place of the string to save
space. Strings are associated with their respective atoms in an atom table.
See also integer atom.
atom table - A table used to relate atoms with the strings that they
represent. Also in the table is the mechanism by which the presence of a
string can be checked.
atomic operation - An operation that completes its work on an object before
another operation can be performed on the same object.
attribute - A characteristic or property that can be controlled, usually to
obtain a required appearance; for example, the color of a line. See also
graphics attributes and segment attributes.
automatic link - In Information Presentation Facility (IPF), a link that
begins a chain reaction at the primary window. When the user selects the
primary window, an automatic link is activated to display secondary windows.
AVIO - Advanced Video Input/Output.
ΓòÉΓòÉΓòÉ <hidden> Glossary - B ΓòÉΓòÉΓòÉ
BВzier curve - (1) A mathematical technique of specifying smooth continous
lines and surfaces, which require a starting point and a finishing point
with several intermediate points that influence or control the path of the
linking curve. Named after Dr. P. BВzier. (2) (D of C) In the AIX Graphics
Library, a cubic spline approximation to a set of four control points that
passes through the first and fourth control points and that has a continuous
slope where two spline segments meet. Named after Dr. P. BВzier.
background - (1) In multiprogramming, the conditions under which low-priority
programs are executed. Contrast with foreground. (2) An active session that
is not currently displayed on the screen.
background color - The color in which the background of a graphic primitive is
drawn.
background mix - An attribute that determines how the background of a graphic
primitive is combined with the existing color of the graphics presentation
space. Contrast with mix.
background program - In multiprogramming, a program that executes with a low
priority. Contrast with foreground program.
bit map - A representation in memory of the data displayed on an APA device,
usually the screen.
block - (1) A string of data elements recorded or transmitted as a unit. The
elements may be characters, words, or logical records. (T) (2) To record
data in a block. (3) A collection of contiguous records recorded as a unit.
Blocks are separated by interblock gaps and each block may contain one or
more records. (A)
block device - A storage device that performs I/O operations on blocks of data
called sectors. Data on block devices can be randomly accessed. Block
devices are designated by a drive letter (for example, C:).
blocking mode - A condition set by an application that determines when its
threads might block. For example, an application might set the Pipemode
parameter for the DosCreateNPipe function so that its threads perform I/O
operations to the named pipe block when no data is available.
border - A visual indication (for example, a separator line or a background
color) of the boundaries of a window.
boundary determination - An operation used to compute the size of the smallest
rectangle that encloses a graphics object on the screen.
breakpoint - (1) A point in a computer program where execution may be halted.
A breakpoint is usually at the beginning of an instruction where halts,
caused by external intervention, are convenient for resuming
execution. (T) (2) A place in a program, specified by a command or a
condition, where the system halts execution and gives control to the
workstation user or to a specified program.
broken pipe - When all of the handles that access one end of a pipe have been
closed.
bucket - One or more fields in which the result of an operation is kept.
buffer - (1) A portion of storage used to hold input or output data
temporarily. (2) To allocate and schedule the use of buffers. (A)
button - A mechanism used to request or initiate an action. See also barrel
buttons, bezel buttons, mouse button, push button, and radio button.
byte pipe - Pipes that handle data as byte streams. All unnamed pipes are byte
pipes. Named pipes can be byte pipes or message pipes. See byte stream.
byte stream - Data that consists of an unbroken stream of bytes.
ΓòÉΓòÉΓòÉ <hidden> Glossary - C ΓòÉΓòÉΓòÉ
cache - A high-speed buffer storage that contains frequently accessed
instructions and data; it is used to reduce access time.
cached micro presentation space - A presentation space from a
Presentation-Manager-owned store of micro presentation spaces. It can be
used for drawing to a window only, and must be returned to the store when
the task is complete.
CAD - Computer-Aided Design.
call - (1) The action of bringing a computer program, a routine, or a
subroutine into effect, usually by specifying the entry conditions and
jumping to an entry point. (I) (A) (2) To transfer control to a procedure,
program, routine, or subroutine.
calling sequence - A sequence of instructions together with any associated
data necessary to execute a call. (T)
Cancel - An action that removes the current window or menu without processing
it, and returns the previous window.
cascaded menu - In the OS/2 operating system, a menu that appears when the
arrow to the right of a cascading choice is selected. It contains a set of
choices that are related to the cascading choice. Cascaded menus are used to
reduce the length of a menu. See also cascading choice.
cascading choice - In SAA Common User Access architecture, a choice in a menu
that, when selected, produces a cascaded menu containing other choices. An
arrow () appears to the right of the cascading choice.
CASE statement - In PM programming, provides the body of a window procedure.
There is usually one CASE statement for each message type supported by an
application.
CGA - Color graphics adapter.
chained list - A list in which the data elements may be dispersed but in which
each data element contains information for locating the
next. (T)Synonymous with linked list.
character - A letter, digit, or other symbol.
character box - In computer graphics, the boundary that defines, in world
coordinates, the horizontal and vertical space occupied by a single
character from a character set. See also character mode. Contrast with
character cell.
character cell - The physical, rectangular space in which any single character
is displayed on a screen or printer device. Position is addressed by row and
column coordinates. Contrast with character box.
character code - The means of addressing a character in a character set,
sometimes called code point.
character device - A device that performs I/O operations on one character at a
time. Because character devices view data as a stream of bytes,
character-device data cannot be randomly accessed. Character devices include
the keyboard, mouse, and printer, and are referred to by name.
character mode - A mode that, in conjunction with the font type, determines
the extent to which graphics characters are affected by the character box,
shear, and angle attributes.
character set - (1) An ordered set of unique representations called
characters; for example, the 26 letters of English alphabet, Boolean 0 and
1, the set of symbols in the Morse code, and the 128 ASCII
characters. (A) (2) All the valid characters for a programming language or
for a computer system. (3) A group of characters used for a specific reason;
for example, the set of characters a printer can print.
check box - In SAA Advanced Common User Access architecture, a square box with
associated text that represents a choice. When a user selects a choice, an X
appears in the check box to indicate that the choice is in effect. The user
can clear the check box by selecting the choice again. Contrast with radio
button.
check mark - (1) (D of C) In SAA Advanced Common User Access architecture, a
symbol that shows that a choice is currently in effect. (2) The symbol that
is used to indicate a selected item on a pull-down menu.
child process - In the OS/2 operating system, a process started by another
process, which is called the parent process. Contrast with parent process.
child window - A window that appears within the border of its parent window
(either a primary window or another child window). When the parent window is
resized, moved, or destroyed, the child window also is resized, moved, or
destroyed; however, the child window can be moved or resized independently
from the parent window, within the boundaries of the parent window. Contrast
with parent window.
choice - (1) An option that can be selected. The choice can be presented as
text, as a symbol (number or letter), or as an icon (a pictorial symbol).
(2) (D of C) In SAA Common User Access architecture, an item that a user can
select.
chord - (1) To press more than one button on a pointing device while the
pointer is within the limits that the user has specified for the operating
environment. (2) (D of C) In graphics, a short line segment whose end points
lie on a circle. Chords are a means for producing a circular image from
straight lines. The higher the number of chords per circle, the smoother the
circular image.
class - In object-oriented design or programming, a group of objects that
share a common definition and that therefore share common properties,
operations, and behavior. Members of the group are called instances of the
class.
class method - In System Object Model, an action that can be performed on a
class object. Synonymous with factory method.
class object - In System Object Model, the run-time implementation of a class.
class style - The set of properties that apply to every window in a window
class.
client - (1) A functional unit that receives shared services from a
server. (T) (2) A user, as in a client process that uses a named pipe or
queue that is created and owned by a server process.
client area - The part of the window, inside the border, that is below the
menu bar. It is the user's work space, where a user types information and
selects choices from selection fields. In primary windows, it is where an
application programmer presents the objects that a user works on.
client program - An application that creates and manipulates instances of
classes.
client window - The window in which the application displays output and
receives input. This window is located inside the frame window, under the
window title bar and any menu bar, and within any scroll bars.
clip limits - The area of the paper that can be reached by a printer or
plotter.
clipboard - In SAA Common User Access architecture, an area of computer
memory, or storage, that temporarily holds data. Data in the clipboard is
available to other applications.
clipping - In computer graphics, removing those parts of a display image that
lie outside a given boundary. (I) (A)
clipping area - The area in which the window can paint.
clipping path - A clipping boundary in world-coordinate space.
clock tick - The minimum unit of time that the system tracks. If the system
timer currently counts at a rate of X Hz, the system tracks the time every
1/X of a second. Also known as time tick.
CLOCK$ - Character-device name reserved for the system clock.
code page - An assignment of graphic characters and control-function meanings
to all code points.
code point - (1) Synonym for character code. (2) (D of C) A 1-byte code
representing one of 256 potential characters.
code segment - An executable section of programming code within a load module.
color dithering - See dithering.
color graphics adapter (CGA) - An adapter that simultaneously provides four
colors and is supported by all IBM Personal Computer and Personal System/2
models.
command - The name and parameters associated with an action that a program can
perform.
command area - An area composed of a command field prompt and a command entry
field.
command entry field - An entry field in which users type commands.
command line - On a display screen, a display line, sometimes at the bottom of
the screen, in which only commands can be entered.
command mode - A state of a system or device in which the user can enter
commands.
command prompt - A field prompt showing the location of the command entry
field in a panel.
Common Programming Interface (CPI) - Definitions of those application
development languages and services that have, or are intended to have,
implementations on and a high degree of commonality across the SAA
environments. One of the three SAA architectural areas. See also Common User
Access architecture.
Common User Access (CUA) architecture - Guidelines for the dialog between a
human and a workstation or terminal. One of the three SAA architectural
areas. See also Common Programming Interface.
compile - To translate a program written in a higher-level programming
language into a machine language program.
composite window - A window composed of other windows (such as a frame window,
frame-control windows, and a client window) that are kept together as a unit
and that interact with each other.
computer-aided design (CAD) - The use of a computer to design or change a
product, tool, or machine, such as using a computer for drafting or
illustrating.
COM1, COM2, COM3 - Character-device names reserved for serial ports 1 through
3.
CON - Character-device name reserved for the console keyboard and screen.
conditional cascaded menu - A pull-down menu associated with a menu item that
has a cascade mini-push button beside it in an object's pop-up menu. The
conditional cascaded menu is displayed when the user selects the mini-push
button.
container - In SAA Common User Access architecture, an object that holds other
objects. A folder is an example of a container object. See also folder and
object.
contextual help - In SAA Common User Access Architecture, help that gives
specific information about the item the cursor is on. The help is contextual
because it provides information about a specific item as it is currently
being used. Contrast with extended help.
contiguous - Touching or joining at a common edge or boundary, for example, an
unbroken consecutive series of storage locations.
control - In SAA Advanced Common User Access architecture, a component of the
user interface that allows a user to select choices or type information; for
example, a check box, an entry field, a radio button.
control area - A storage area used by a computer program to hold control information. (I) (A)
Control Panel - In the Presentation Manager, a program used to set up user
preferences that act globally across the system.
Control Program - (1) The basic functions of the operating system, including
DOS emulation and the support for keyboard, mouse, and video input/output.
(2) A computer program designed to schedule and to supervise the execution
of programs of a computer system. (I) (A)
control window - A window that is used as part of a composite window to
perform simple input and output tasks. Radio buttons and check boxes are
examples.
control word - An instruction within a document that identifies its parts or
indicates how to format the document.
coordinate space - A two-dimensional set of points used to generate output on
a video display of printer.
Copy - A choice that places onto the clipboard, a copy of what the user has
selected. See also Cut and Paste.
correlation - The action of determining which element or object within a
picture is at a given position on the display. This follows a pick
operation.
coverpage window - A window in which the application's help information is
displayed.
CPI - Common Programming Interface.
critical extended attribute - An extended attribute that is necessary for the
correct operation of the system or a particular application.
critical section - (1) In programming languages, a part of an asynchronous
procedure that cannot be executed simultaneously with a certain part of
another asynchronous procedure. (I)
Note: Part of the other asynchronous procedure also is a critical section.
(2) A section of code that is not reentrant; that is, code that can be
executed by only one thread at a time.
CUA architecture - Common User Access architecture.
current position - In computer graphics, the position, in user coordinates,
that becomes the starting point for the next graphics routine, if that
routine does not explicitly specify a starting point.
cursor - A symbol displayed on the screen and associated with an input device.
The cursor indicates where input from the device will be placed. Types of
cursors include text cursors, graphics cursors, and selection cursors.
Contrast with pointer and input focus.
Cut - In SAA Common User Access architecture, a choice that removes a selected
object, or a part of an object, to the clipboard, usually compressing the
space it occupied in a window. See also Copy and Paste.
ΓòÉΓòÉΓòÉ <hidden> Glossary - D ΓòÉΓòÉΓòÉ
daisy chain - A method of device interconnection for determining interrupt
priority by connecting the interrupt sources serially.
data segment - A nonexecutable section of a program module; that is, a section
of a program that contains data definitions.
data structure - The syntactic structure of symbolic expressions and their
storage-allocation characteristics. (T)
data transfer - The movement of data from one object to another by way of the
clipboard or by direct manipulation.
DBCS - Double-byte character set.
DDE - Dynamic data exchange.
deadlock - (1) Unresolved contention for the use of a resource. (2) An error
condition in which processing cannot continue because each of two elements
of the process is waiting for an action by, or a response from, the other.
(3) An impasse that occurs when multiple processes are waiting for the
availability of a resource that will not become available because it is
being held by another process that is in a similar wait state.
debug - To detect, diagnose, and eliminate errors in programs. (T)
decipoint - In printing, one tenth of a point. There are 72 points in an
inch.
default procedure - A function provided by the Presentation Manager Interface
that may be used to process standard messages from dialogs or windows.
default value - A value assumed when no value has been specified. Synonymous
with assumed value. For example, in the graphics programming interface, the
default line-type is `solid'.
definition list - A type of list that pairs a term and its description.
delta - An application-defined threshold, or number of container items, from
either end of the list.
descendant - See child process.
descriptive text - Text used in addition to a field prompt to give more
information about a field.
Deselect all - A choice that cancels the selection of all of the objects that
have been selected in that window.
Desktop Manager - In the Presentation Manager, a window that displays a list
of groups of programs, each of which can be started or stopped.
desktop window - The window, corresponding to the physical device, against
which all other types of windows are established.
detached process - A background process that runs independent of the parent
process.
detent - A point on a slider that represents an exact value to which a user
can move the slider arm.
device context - A logical description of a data destination such as memory,
metafile, display, printer, or plotter. See also direct device context,
information device context, memory device context, metafile device context,
queued device context, and screen device context.
device driver - A file that contains the code needed to attach and use a
device such as a display, printer, or plotter.
device space - (1) Coordinate space in which graphics are assembled after all
GPI transformations have been applied. Device space is defined in
device-specific units. (2) (D of C) In computer graphics, a space defined by
the complete set of addressable points of a display device. (A)
dialog - The interchange of information between a computer and its user
through a sequence of requests by the user and the presentation of responses
by the computer.
dialog box - In SAA Advanced Common User Access architecture, a movable
window, fixed in size, containing controls that a user uses to provide
information required by an application so that it can continue to process a
user request. See also message box, primary window, secondary window. Also
known as a pop-up window.
Dialog Box Editor - A WYSIWYG editor that creates dialog boxes for
communicating with the application user.
dialog item - A component (for example, a menu or a button) of a dialog box.
Dialog items are also used when creating dialog templates.
dialog procedure - A dialog window that is controlled by a window procedure.
It is responsible for responding to all messages sent to the dialog window.
dialog tag language - A markup language used by the DTL compiler to create
dialog objects.
dialog template - The definition of a dialog box, which contains details of
its position, appearance, and window ID, and the window ID of each of its
child windows.
direct device context - A logical description of a data destination that is a
device other than the screen (for example, a printer or plotter), and where
the output is not to go through the spooler. Its purpose is to satisfy
queries. See also device context.
direct manipulation - The user's ability to interact with an object by using
the mouse, typically by dragging an object around on the Desktop and
dropping it on other objects.
direct memory access (DMA) - A technique for moving data directly between main
storage and peripheral equipment without requiring processing of the data by
the processing unit.(T)
directory - A type of file containing the names and controlling information
for other files or other directories.
display point - Synonym for pel.
dithering - (1) The process used in color displays whereby every other pel is
set to one color, and the intermediate pels are set to another. Together
they produce the effect of a third color at normal viewing distances. This
process can only be used on solid areas of color; it does not work, for
example, on narrow lines. (2) (D of C ) In computer graphics, a technique of
interleaving dark and light pixels so that the resulting image looks
smoothly shaded when viewed from a distance.
DMA - Direct memory access.
DOS Protect Mode Interface (DPMI) - An interface between protect mode and real
mode programs.
double-byte character set (DBCS) - A set of characters in which each character
is represented by two bytes. Languages such as Japanese, Chinese, and
Korean, which contain more characters than can be represented by 256 code
points, require double-byte character sets. Since each character requires
two bytes, the entering, displaying, and printing of DBCS characters
requires hardware and software that can support DBCS.
doubleword - A contiguous sequence of bits or characters that comprises two
computer words and is capable of being addressed as a unit. (A)
DPMI - DOS Protect Mode Interface.
drag - In SAA Common User Access, to use a pointing device to move an object;
for example, clicking on a window border, and dragging it to make the window
larger.
dragging - (1) In computer graphics, moving an object on the display screen as
if it were attached to the pointer. (2) (D of C) In computer graphics,
moving one or more segments on a display surface by translating. (I) (A)
drawing chain - See segment chain.
drop - To fix the position of an object that is being dragged, by releasing
the select button of the pointing device.
drop - To fix the position of an object that is being dragged, by releasing
the select button of the pointing device. See also drag.
DTL - Dialog tag language.
dual-boot function - A feature of the OS/2 operating system that allows the
user to start DOS from within the operating system, or an OS/2 session from
within DOS.
duplex - Pertaining to communication in which data can be sent and received at
the same time. Synonymous with full duplex.
dynamic data exchange (DDE) - A message protocol used to communicate between
applications that share data. The protocol uses shared memory as the means
of exchanging data between applications.
dynamic data formatting - A formatting procedure that enables you to
incorporate text, bit maps or metafiles in an IPF window at execution time.
dynamic link library - A collection of executable programming code and data
that is bound to an application at load time or run time, rather than during
linking. The programming code and data in a dynamic link library can be
shared by several applications simultaneously.
dynamic linking - The process of resolving external references in a program
module at load time or run time rather than during linking.
dynamic segments - Graphics segments drawn in exclusive-OR mix mode so that
they can be moved from one screen position to another without affecting the
rest of the displayed picture.
dynamic storage - (1) A device that stores data in a manner that permits the
data to move or vary with time such that the specified data is not always
available for recovery. (A) (2) A storage in which the cells require
repetitive application of control signals in order to retain stored data.
Such repetitive application of the control signals is called a refresh
operation. A dynamic storage may use static addressing or sensing
circuits. (A) (3) See also static storage.
dynamic time slicing - Varies the size of the time slice depending on system
load and paging activity.
dynamic-link module - A module that is linked at load time or run time.
ΓòÉΓòÉΓòÉ <hidden> Glossary - E ΓòÉΓòÉΓòÉ
EBCDIC - Extended binary-coded decimal interchange code. A coded character set
consisting of 8-bit coded characters (9 bits including parity check), used
for information interchange among data processing systems, data
communications systems, and associated equipment.
edge-triggered - Pertaining to an event semaphore that is posted then reset
before a waiting thread gets a chance to run. The semaphore is considered to
be posted for the rest of that thread's waiting period; the thread does not
have to wait for the semaphore to be posted again.
EGA - Extended graphics adapter.
element - An entry in a graphics segment that comprises one or more graphics
orders and that is addressed by the element pointer.
EMS - Expanded Memory Specification.
encapsulation - Hiding an object's implementation, that is, its private,
internal data and methods. Private variables and methods are accessible only
to the object that contains them.
entry field - In SAA Common User Access architecture, an area where a user
types information. Its boundaries are usually indicated. See also selection
field.
entry panel - A defined panel type containing one or more entry fields and
protected information such as headings, prompts, and explanatory text.
entry-field control - The component of a user interface that provides the
means by which the application receives data entered by the user in an entry
field. When it has the input focus, the entry field displays a flashing
pointer at the position where the next typed character will go.
environment segment - The list of environment variables and their values for a
process.
environment strings - ASCII text strings that define the value of environment
variables.
environment variables - Variables that describe the execution environment of a
process. These variables are named by the operating system or by the
application. Environment variables named by the operating system are PATH,
DPATH, INCLUDE, INIT, LIB, PROMPT, and TEMP. The values of environment
variables are defined by the user in the CONFIG.SYS file, or by using the
SET command at the OS/2 command prompt.
error message - An indication that an error has been detected. (A)
event semaphore - A semaphore that enables a thread to signal a waiting thread
or threads that an event has occurred or that a task has been completed. The
waiting threads can then perform an action that is dependent on the
completion of the signaled event.
exception - An abnormal condition such as an I/O error encountered in
processing a data set or a file.
exclusive system semaphore - A system semaphore that can be modified only by
threads within the same process.
executable file - (1) A file that contains programs or commands that perform
operations or actions to be taken. (2) A collection of related data records
that execute programs.
exit - To execute an instruction within a portion of a computer program in
order to terminate the execution of that portion. Such portions of computer
programs include loops, subroutines, modules, and so on. (T) Repeated exit
requests return the user to the point from which all functions provided to
the system are accessible. Contrast with cancel.
expanded memory specification (EMS) - Enables DOS applications to access
memory above the 1MB real mode addressing limit.
extended attribute - An additional piece of information about a file object,
such as its data format or category. It consists of a name and a value. A
file object may have more than one extended attribute associated with it.
extended help - In SAA Common User Access architecture, a help action that
provides information about the contents of the application window from which
a user requested help. Contrast with contextual help.
extended-choice selection - A mode that allows the user to select more than
one item from a window. Not all windows allow extended choice selection.
Contrast with multiple-choice selection.
extent - Continuous space on a disk or diskette that is occupied by or
reserved for a particular data set, data space, or file.
external link - In Information Presentation Facility, a link that connects
external online document files.
ΓòÉΓòÉΓòÉ <hidden> Glossary - F ΓòÉΓòÉΓòÉ
family-mode application - An application program that can run in the OS/2
environment and in the DOS environment; however, it cannot take advantage of
many of the OS/2-mode facilities, such as multitasking, interprocess
communication, and dynamic linking.
FAT - File allocation table.
FEA - Full extended attribute.
field-level help - Information specific to the field on which the cursor is
positioned. This help function is "contextual" because it provides
information about a specific item as it is currently used; the information
is dependent upon the context within the work session.
FIFO - First-in-first-out. (A)
file - A named set of records stored or processed as a unit. (T)
file allocation table (FAT) - In IBM personal computers, a table used by the
operating system to allocate space on a disk for a file, and to locate and
chain together parts of the file that may be scattered on different sectors
so that the file can be used in a random or sequential manner.
file attribute - Any of the attributes that describe the characteristics of a
file.
File Manager - In the Presentation Manager, a program that displays
directories and files, and allows various actions on them.
file specification - The full identifier for a file, which includes its drive
designation, path, file name, and extension.
file system - The combination of software and hardware that supports storing
information on a storage device.
file system driver (FSD) - A program that manages file I\O and controls the
format of information on the storage media.
fillet - A curve that is tangential to the end points of two adjoining lines.
See also polyfillet.
filtering - An application process that changes the order of data in a queue.
first-in-first-out (FIFO) - A queuing technique in which the next item to be
retrieved is the item that has been in the queue for the longest time. (A)
flag - (1) An indicator or parameter that shows the setting of a switch. (2) A
character that signals the occurrence of some condition, such as the end of
a word. (A) (3) (D of C) A characteristic of a file or directory that
enables it to be used in certain ways. See also archive flag, hidden flag,
and read-only flag.
focus - See input focus.
folder - A container used to organize objects.
font - A particular size and style of typeface that contains definitions of
character sets, marker sets, and pattern sets.
Font Editor - A utility program provided with the IBM Developers Toolkit that
enables the design and creation of new fonts.
foreground program - (1) The program with which the user is currently
interacting. Also known as interactive program. Contrast with background
program. (2) (D of C) In multiprogramming, a high-priority program.
frame - The part of a window that can contain several different visual
elements specified by the application, but drawn and controlled by the
Presentation Manager. The frame encloses the client area.
frame styles - Standard window layouts provided by the Presentation Manager.
FSD - File system driver.
full-duplex - Synonym for duplex.
full-screen application - An application that has complete control of the
screen.
function - (1) In a programming language, a block, with or without formal
parameters, whose execution is invoked by means of a call. (2) A set of
related control statements that cause one or more programs to be performed.
function key - A key that causes a specified sequence of operations to be
performed when it is pressed, for example, F1 and Alt-K.
function key area - The area at the bottom of a window that contains function
key assignments such as F1=Help.
ΓòÉΓòÉΓòÉ <hidden> Glossary - G ΓòÉΓòÉΓòÉ
GDT - Global Descriptor Table.
general protection fault - An exception condition that occurs when a process
attempts to use storage or a module that has some level of protection
assigned to it, such as I/O privilege level. See also IOPL code segment.
Global Descriptor Table (GDT) - A table that defines code and data segments
available to all tasks in an application.
global dynamic-link module - A dynamic-link module that can be shared by all
processes in the system that refer to the module name.
global file-name character - Either a question mark (?) or an asterisk (*)
used as a variable in a file name or file name extension when referring to a
particular file or group of files.
glyph - A graphic symbol whose appearance conveys information.
GPI - Graphics programming interface.
graphic primitive - In computer graphics, a basic element, such as an arc or a
line, that is not made up of smaller parts and that is used to create
diagrams and pictures. See also graphics segment.
graphics - (1) A picture defined in terms of graphic primitives and graphics
attributes. (2) (D of C) The making of charts and pictures. (3) Pertaining
to charts, tables, and their creation. (4) See computer graphics, coordinate
graphics, fixed-image graphics, interactive graphics, passive graphics,
raster graphics.
graphics attributes - Attributes that apply to graphic primitives. Examples
are color, line type, and shading-pattern definition. See also segment
attributes.
graphics field - The clipping boundary that defines the visible part of the
presentation-page contents.
graphics mode - One of several states of a display. The mode determines the
resolution and color content of the screen.
graphics model space - The conceptual coordinate space in which a picture is
constructed after any model transforms have been applied. Also known as
model space.
Graphics programming interface - The formally defined programming language
that is between an IBM graphics program and the user of the program.
graphics segment - A sequence of related graphic primitives and graphics
attributes. See also graphic primitive.
graying - The indication that a choice on a pull-down is unavailable.
group - A collection of logically connected controls. For example, the buttons
controlling paper size for a printer could be called a group. See also
program group.
ΓòÉΓòÉΓòÉ <hidden> Glossary - H ΓòÉΓòÉΓòÉ
handle - (1) An identifier that represents an object, such as a device or
window, to the Presentation Interface. (2) (D of C) In the Advanced DOS and
OS/2 operating systems, a binary value created by the system that identifies
a drive, directory, and file so that the file can be found and opened.
hard error - An error condition on a network that requires either that the
system be reconfigured or that the source of the error be removed before the
system can resume reliable operation.
header - (1) System-defined control information that precedes user data. (2)
The portion of a message that contains control information for the message,
such as one or more destination fields, name of the originating station,
input sequence number, character string indicating the type of message, and
priority level for the message.
heading tags - A document element that enables information to be displayed in
windows, and that controls entries in the contents window controls placement
of push buttons in a window, and defines the shape and size of windows.
heap - An area of free storage available for dynamic allocation by an
application. Its size varies according to the storage requirements of the
application.
help function - (1) A function that provides information about a specific
field, an application panel, or information about the help facility. (2) (D
of C) One or more display images that describe how to use application
software or how to do a system operation.
Help index - In SAA Common User Access architecture, a help action that
provides an index of the help information available for an application.
help panel - A panel with information to assist users that is displayed in
response to a help request from the user.
help window - A Common-User-Access-defined secondary window that displays
information when the user requests help.
hidden file - An operating system file that is not displayed by a directory
listing.
hide button - In the OS/2 operating system, a small, square button located in
the right-hand corner of the title bar of a window that, when selected,
removes from the screen all the windows associated with that window.
Contrast with maximize button. See also restore button.
hierarchical inheritance - The relationship between parent and child classes.
An object that is lower in the inheritance hierarchy than another object,
inherits all the characteristics and behaviors of the objects above it in
the hierarchy.
hierarchy - A tree of segments beginning with the root segment and proceeding
downward to dependent segment types.
high-performance file system (HPFS) - In the OS/2 operating system, an
installable file system that uses high-speed buffer storage, known as a
cache, to provide fast access to large disk volumes. The file system also
supports the coexistence of multiple, active file systems on a single
personal computer, with the capability of multiple and different storage
devices. File names used with the HPFS can have as many as 254 characters.
hit testing - The means of identifying which window is associated with which
input device event.
hook - A point in a system-defined function where an application can supply
additional code that the system processes as though it were part of the
function.
hook chain - A sequence of hook procedures that are "chained" together so that
each event is passed, in turn, to each procedure in the chain.
hot spot - The part of the pointer that must touch an object before it can be
selected. This is usually the tip of the pointer. Contrast with action
point.
HPFS - high-performance file system.
hypergraphic link - A connection between one piece of information and another
through the use of graphics.
hypertext - A way of presenting information online with connections between
one piece of information and another, called hypertext links. See also
hypertext link.
hypertext link - A connection between one piece of information and another.
ΓòÉΓòÉΓòÉ <hidden> Glossary - I ΓòÉΓòÉΓòÉ
I/O operation - An input operation to, or output operation from a device
attached to a computer.
I-beam pointer - A pointer that indicates an area, such as an entry field in
which text can be edited.
icon - In SAA Advanced Common User Access architecture, a graphical
representation of an object, consisting of an image, image background, and a
label. Icons can represent items (such as a document file) that the user
wants to work on, and actions that the user wants to perform. In the
Presentation Manager, icons are used for data objects, system actions, and
minimized programs.
icon area - In the Presentation Manager, the area at the bottom of the screen
that is normally used to display the icons for minimized programs.
Icon Editor - The Presentation Manager-provided tool for creating icons.
IDL - Interface Definition Language.
image font - A set of symbols, each of which is described in a rectangular
array of pels. Some of the pels in the array are set to produce the image of
one of the symbols. Contrast with outline font.
implied metaclass - Subclassing the metaclass of a parent class without a
separate CSC for the resultant metaclass.
indirect manipulation - Interaction with an object through choices and
controls.
information device context - A logical description of a data destination other
than the screen (for example, a printer or plotter), but where no output
will occur. Its purpose is to satisfy queries. See also device context.
information panel - A defined panel type characterized by a body containing
only protected information.
Information Presentation Facility (IPF) - A facility provided by the OS/2
operating system, by which application developers can produce online
documentation and context-sensitive online help panels for their
applications.
inheritance - The derivation of new (child) classes from existing (parent)
classes. The new class inherits all the data and methods of the parent class
without having to redefine them.
input focus - (1) The area of a window where user interaction is possible
using an input device, such as a mouse or the keyboard. (2) The position in
the active window where a user's normal interaction with the keyboard will
appear.
input router - An internal OS/2 process that removes messages from the system
queue.
input/output control - A device-specific command that requests a function of a
device driver.
installable file system (IFS) - A file system in which software is installed
when the operating system is started.
instance - A single occurrence of an object class that has a particular
behavior.
instruction pointer - In system/38, a pointer that provides addressability for
a machine interface instruction in a program.
integer atom - An atom that represents a predefined system constant and
carries no storage overhead. For example, names of window classes provided
by Presentation Manager are expressed as integer atoms.
interactive graphics - Graphics that can be moved or manipulated by a user at
a terminal.
interactive program - (1) A program that is running (active) and is ready to
receive (or is receiving) input from a user. (2) A running program that can
receive input from the keyboard or another input device. Compare with active
program and contrast with noninteractive program.
Also known as a foreground program.
interchange file - A file containing data that can be sent from one
Presentation Manager interface application to another.
Interface Definition Language (IDL) - Language-neutral interface specification
for a SOM class.
interpreter - A program that translates and executes each instruction of a
high-level programming language before it translates and executes.
interprocess communication (IPC) - In the OS/2 operating system, the exchange
of information between processes or threads through semaphores, pipes,
queues, and shared memory.
interval timer - (1) A timer that provides program interruptions on a
program-controlled basis. (2) An electronic counter that counts intervals of
time under program control.
IOCtl - Input/output control.
IOPL - Input/output privilege level.
IOPL code segment - An IOPL executable section of programming code that
enables an application to directly manipulate hardware interrupts and ports
without replacing the device driver. See also privilege level.
IPC - Interprocess communication.
IPF - Information Presentation Facility.
IPF compiler - A text compiler that interpret tags in a source file and
converts the information into the specified format.
IPF tag language - A markup language that provides the instructions for
displaying online information.
item - A data object that can be passed in a DDE transaction.
ΓòÉΓòÉΓòÉ <hidden> Glossary - J ΓòÉΓòÉΓòÉ
journal - A special-purpose file that is used to record changes made in the
system.
ΓòÉΓòÉΓòÉ <hidden> Glossary - K ΓòÉΓòÉΓòÉ
Kanji - A graphic character set used in Japanese ideographic alphabets.
KBD$ - Character-device name reserved for the keyboard.
kernel - The part of an operating system that performs basic functions, such
as allocating hardware resources.
kerning - The design of graphics characters so that their character boxes
overlap. Used to space text proportionally.
keyboard accelerator - A keystroke that generates a command message for an
application.
keyboard augmentation - A function that enables a user to press a keyboard key
while pressing a mouse button.
keyboard focus - A temporary attribute of a window. The window that has a
keyboard focus receives all keyboard input until the focus changes to a
different window.
Keys help - In SAA Common User Access architecture, a help action that
provides a listing of the application keys and their assigned functions.
ΓòÉΓòÉΓòÉ <hidden> Glossary - L ΓòÉΓòÉΓòÉ
label - In a graphics segment, an identifier of one or more elements that is
used when editing the segment.
LAN - local area network.
language support procedure - A function provided by the Presentation Manager
Interface for applications that do not, or cannot (as in the case of COBOL
and FORTRAN programs), provide their own dialog or window procedures.
lazy drag - See pickup and drop.
lazy drag set - See pickup set.
LDT - In the OS/2 operating system, Local Descriptor Table.
LIFO stack - A stack from which data is retrieved in last-in, first-out order.
linear address - A unique value that identifies the memory object.
linked list - Synonym for chained list.
list box - In SAA Advanced Common User Access architecture, a control that
contains scrollable choices from which a user can select one choice.
Note: In CUA architecture, this is a programmer term. The end user term is
selection list.
list button - A button labeled with an underlined down-arrow that presents a
list of valid objects or choices that can be selected for that field.
list panel - A defined panel type that displays a list of items from which
users can select one or more choices and then specify one or more actions to
work on those choices.
load time - The point in time at which a program module is loaded into main
storage for execution.
load-on-call - A function of a linkage editor that allows selected segments of
the module to be disk resident while other segments are executing. Disk
resident segments are loaded for execution and given control when any entry
point that they contain is called.
local area network (LAN) - (1) A computer network located on a user's premises
within a limited geographical area. Communication within a local area
network is not subject to external regulations; however, communication
across the LAN boundary may be subject to some form of regulation. (T)
Note: A LAN does not use store and forward techniques. (2) A network
inwhich a set of devices are connected to one another for communication and
that can be connected to a larger network.
Local Descriptor Table (LDT) - Defines code and data segments specific to a
single task.
lock - A serialization mechanism by means of which a resource is restricted
for use by the holder of the lock.
logical storage device - A device that the user can map to a physical (actual)
device.
LPT1, LPT2, LPT3 - Character-device names reserved for parallel printers 1
through 3.
ΓòÉΓòÉΓòÉ <hidden> Glossary - M ΓòÉΓòÉΓòÉ
main window - The window that is positioned relative to the desktop window.
manipulation button - The button on a pointing device a user presses to
directly manipulate an object.
map - (1) A set of values having a defined correspondence with the quantities
or values of another set. (I) (A) (2) To establish a set of values having
a defined correspondence with the quantities or values of another set. (I)
marker box - In computer graphics, the boundary that defines, in world
coordinates, the horizontal and vertical space occupied by a single marker
from a marker set.
marker symbol - A symbol centered on a point. Graphs and charts can use marker
symbols to indicate the plotted points.
marquee box - The rectangle that appears during a selection technique in which
a user selects objects by drawing a box around them with a pointing device.
Master Help Index - In the OS/2 operating system, an alphabetic list of help
topics related to using the operating system.
maximize - To enlarge a window to its largest possible size.
media window - The part of the physical device (display, printer, or plotter)
on which a picture is presented.
memory block - Part memory within a heap.
memory device context - A logical description of a data destination that is a
memory bit map. See also device context.
memory management - A feature of the operating system for allocating, sharing,
and freeing main storage.
memory object - Logical unit of memory requested by an application, which
forms the granular unit of memory manipulation from the application
viewpoint.
menu - In SAA Advanced Common User Access architecture, an extension of the
menu bar that displays a list of choices available for a selected choice in
the menu bar. After a user selects a choice in menu bar, the corresponding
menu appears. Additional pop-up windows can appear from menu choices.
menu bar - In SAA Advanced Common User Access architecture, the area near the
top of a window, below the title bar and above the rest of the window, that
contains choices that provide access to other menus.
menu button - The button on a pointing device that a user presses to view a
pop-up menu associated with an object.
message - (1) In the Presentation Manager, a packet of data used for
communication between the Presentation Manager interface and Presentation
Manager applications (2) In a user interface, information not requested by
users but presented to users by the computer in response to a user action or
internal process.
message box - (1) A dialog window predefined by the system and used as a
simple interface for applications, without the necessity of creating
dialog-template resources or dialog procedures. (2) (D of C) In SAA Advanced
Common User Access architecture, a type of window that shows messages to
users. See also dialog box, primary window, secondary window.
message filter - The means of selecting which messages from a specific window
will be handled by the application.
message queue - A sequenced collection of messages to be read by the
application.
message stream mode - A method of operation in which data is treated as a
stream of messages. Contrast with byte stream.
metacharacter - See global file-name character.
metaclass - The conjunction of an object and its class information; that is,
the information pertaining to the class as a whole, rather than to a single
instance of the class. Each class is itself an object, which is an instance
of the metaclass.
metafile - A file containing a series of attributes that set color, shape and
size, usually of a picture or a drawing. Using a program that can interpret
these attributes, a user can view the assembled image.
metafile device context - A logical description of a data destination that is
a metafile, which is used for graphics interchange. See also device context.
metalanguage - A language used to specify another language. For example, data
types can be described using a metalanguage so as to make the descriptions
independent of any one computer language.
method - A function that defines a behavior for a class or object.
method override - The replacement, by a child class, of the implementation of
a method inherited from a parent and an ancestor class.
mickey - A unit of measurement for physical mouse motion whose value depends
on the mouse device driver currently loaded.
micro presentation space - A graphics presentation space in which a restricted
set of the GPI function calls is available.
minimize - To remove from the screen all windows associated with an
application and replace them with an icon that represents the application.
mix - An attribute that determines how the foreground of a graphic primitive
is combined with the existing color of graphics output. Also known as
foreground mix. Contrast with background mix.
mixed character string - A string containing a mixture of one-byte and Kanji
or Hangeul (two-byte) characters.
mnemonic - (1) A method of selecting an item on a pull-down by means of typing
the highlighted letter in the menu item. (2) (D of C) In SAA Advanced Common
User Access architecture, usually a single character, within the text of a
choice, identified by an underscore beneath the character. If all characters
in a choice already serve as mnemonics for other choices, another character,
placed in parentheses immediately following the choice, can be used. When a
user types the mnemonic for a choice, the choice is either selected or the
cursor is moved to that choice.
modal dialog box - In SAA Advanced Common User Access architecture, a type of
movable window, fixed in size, that requires a user to enter information
before continuing to work in the application window from which it was
displayed. Contrast with modeless dialog box. Also known as a serial dialog
box. Contrast with parallel dialog box.
Note: In CUA architecture, this is a programmer term. The end user term is
pop-up window.
model space - See graphics model space.
modeless dialog box - In SAA Advanced Common User Access architecture, a type
of movable window, fixed in size, that allows users to continue their dialog
with the application without entering information in the dialog box. Also
known as a parallel dialog box. Contrast with modal dialog box.
Note: In CUA architecture, this is a programmer term. The end user term is
pop-up window.
module definition file - A file that describes the code segments within a load
module. For example, it indicates whether a code segment is loadable before
module execution begins (preload), or loadable only when referred to at run
time (load-on-call).
mouse - In SAA usage, a device that a user moves on a flat surface to position
a pointer on the screen. It allows a user to select a choice o function to
be performed or to perform operations on the screen, such as dragging or
drawing lines from one position to another.
MOUSE$ - Character-device name reserved for a mouse.
multiple-choice selection - In SAA Basic Common User Access architecture, a
type of field from which a user can select one or more choices or select
none. See also check box. Contrast with extended-choice selection.
multiple-line entry field - In SAA Advanced Common User Access architecture, a
control into which a user types more than one line of information. See also
single-line entry field.
multitasking - The concurrent processing of applications or parts of
applications. A running application and its data are protected from other
concurrently running applications.
mutex semaphore - (Mutual exclusion semaphore). A semaphore that enables
threads to serialize their access to resources. Only the thread that
currently owns the mutex semaphore can gain access to the resource, thus
preventing one thread from interrupting operations being performed by
another.
muxwait semaphore - (Multiple wait semaphore). A semaphore that enables a
thread to wait either for multiple event semaphores to be posted or for
multiple mutex semaphores to be released. Alternatively, a muxwait semaphore
can be set to enable a thread to wait for any ONE of the event or mutex
semaphores in the muxwait semaphore's list to be posted or released.
ΓòÉΓòÉΓòÉ <hidden> Glossary - N ΓòÉΓòÉΓòÉ
named pipe - A named buffer that provides client-to-server, server-to-client,
or full duplex communication between unrelated processes. Contrast with
unnamed pipe.
national language support (NLS) - The modification or conversion of a United
States English product to conform to the requirements of another language or
country. This can include the enabling or retrofitting of a product and the
translation of nomenclature, MRI, or documentation of a product.
nested list - A list that is contained within another list.
NLS - national language support.
non-8.3 file-name format - A file-naming convention in which file names can
consist of up to 255 characters. See also 8.3 file-name format.
noncritical extended attribute - An extended attribute that is not necessary
for the function of an application.
nondestructive read - Reading that does not erase the data in the source
location. (T)
noninteractive program - A running program that cannot receive input from the
keyboard or other input device. Compare with active program, and contrast
with interactive program.
nonretained graphics - Graphic primitives that are not remembered by the
Presentation Manager interface when they have been drawn. Contrast with
retained graphics.
null character (NUL) - (1) Character-device name reserved for a nonexistent
(dummy) device. (2) (D of C) A control character that is used to accomplish
media-fill or time-fill and that may be inserted into or removed from a
sequence of characters without affecting the meaning of the sequence;
however, the control of equipment or the format may be affected by this
character. (I) (A)
null-terminated string - A string of (n+1) characters where the (n+1)th
character is the `null' character (0x00) Also known as `zero-terminated'
string and 'ASCIIZ' string.
ΓòÉΓòÉΓòÉ <hidden> Glossary - O ΓòÉΓòÉΓòÉ
object - A set of data and actions that can be performed on that data.
Object Interface Definition Language (OIDL) - Specification language used in
SOM Version 1 for defining classes. Replaced by Interface Definition
Language (IDL).
object window - A window that does not have a parent but which might have
child windows. An object window cannot be presented on a device.
OIDL - Object Interface Definition Language.
open - To start working with a file, directory, or other object.
ordered list - Vertical arrangements of items, with each item in the list
preceded by a number or letter.
outline font - A set of symbols, each of which is created as a series of lines
and curves. Synonymous with vector font. Contrast with image font.
output area - An area of storage reserved for output. (A)
owner window - A window into which specific events that occur in another
(owned) window are reported.
ownership - The determination of how windows communicate using messages.
owning process - The process that owns the resources that might be shared with
other processes.
ΓòÉΓòÉΓòÉ <hidden> Glossary - P ΓòÉΓòÉΓòÉ
page - (1) A 4KB segment of contiguous physical memory. (2) (D of C) A defined
unit of space on a storage medium.
page viewport - A boundary in device coordinates that defines the area of the
output device in which graphics are to be displayed. The presentation-page
contents are transformed automatically to the page viewport in device space.
paint - (1) The action of drawing or redrawing the contents of a window. (2)
In computer graphics, to shade an area of a display image; for example,
with crosshatching or color.
panel - In SAA Basic Common User Access architecture, a particular arrangement
of information that is presented in a window or pop-up. If some of the
information is not visible, a user can scroll through the information.
panel area - An area within a panel that contains related information. The
three major Common User Access-defined panel areas are the action bar, the
function key area, and the panel body.
panel area separator - In SAA Basic Common User Access architecture, a solid,
dashed, or blank line that provides a visual distinction between two
adjacent areas of a panel.
panel body - The portion of a panel not occupied by the action bar, function
key area, title or scroll bars. The panel body can contain protected
information, selection fields, and entry fields. The layout and content of
the panel body determine the panel type.
panel body area - See client area.
panel definition - A description of the contents and characteristics of a
panel. A panel definition is the application developer's mechanism for
predefining the format to be presented to users in a window.
panel ID - In SAA Basic Common User Access architecture, a panel identifier,
located in the upper-left corner of a panel. A user can choose whether to
display the panel ID.
panel title - In SAA Basic Common User Access architecture, a particular
arrangement of information that is presented in a window or pop-up. If some
of the information is not visible, a user can scroll through the
information.
paper size - The size of paper, defined in either standard U.S. or European
names (for example, A, B, A4), and measured in inches or millimeters
respectively.
parallel dialog box - See modeless dialog box.
parameter list - A list of values that provides a means of associating
addressability of data defined in a called program with data in the calling
program. It contains parameter names and the order in which they are to be
associated in the calling and called program.
parent process - In the OS/2 operating system, a process that creates other
processes. Contrast with child process.
parent window - In the OS/2 operating system, a window that creates a child
window. The child window is drawn within the parent window. If the parent
window is moved, resized, or destroyed, the child window also will be moved,
resized, or destroyed. However, the child window can be moved and resized
independently from the parent window, within the boundaries of the parent
window. Contrast with child window.
partition - (1) A fixed-size division of storage. (2) On an IBM personal
computer fixed disk, one of four possible storage areas of variable size;
one may be accessed by DOS, and each of the others may be assigned to
another operating system.
Paste - A choice in the Edit pull-down that a user selects to move the
contents of the clipboard into a preselected location. See also Copy and
Cut.
path - The route used to locate files; the storage location of a file. A fully
qualified path lists the drive identifier, directory name, subdirectory name
(if any), and file name with the associated extension.
PDD - Physical device driver.
peeking - An action taken by any thread in the process that owns the queue to
examine queue elements without removing them.
pel - (1) The smallest area of a display screen capable of being addressed and
switched between visible and invisible states. Synonym for display point,
pixel, and picture element. (2) (D of C) Picture element.
persistent object - An object whose instance data and state are preserved
between system shutdown and system startup.
physical device driver (PDD) - A system interface that handles hardware
interrupts and supports a set of input and output functions.
pick - To select part of a displayed object using the pointer.
pickup - To add an object or set of objects to the pickup set.
pickup and drop - A drag operation that does not require the direct
manipulation button to be pressed for the duration of the drag.
pickup set - The set of objects that have been picked up as part of a pickup
and drop operation.
picture chain - See segment chain.
picture element - (1) Synonym for pel. (2) (D of C) In computer graphics, the
smallest element of a display surface that can be independently assigned
color and intensity. (T) . (3) The area of the finest detail that can be
reproduced effectively on the recording medium.
PID - Process identification.
pipe - (1) A named or unnamed buffer used to pass data between processes. A
process reads from or writes to a pipe as if the pipe were a standard-input
or standard-output file. See also named pipe and unnamed pipe. (2) (D of C)
To direct data so that the output from one process becomes the input to
another process. The standard output of one command can be connected to the
standard input of another with the pipe operator (|).
pixel - (1) Synonym for pel. (2) (D of C) Picture element.
plotter - An output unit that directly produces a hardcopy record of data on a
removable medium, in the form of a two-dimensional graphic representation. (T)
PM - Presentation Manager.
pointer - (1) The symbol displayed on the screen that is moved by a pointing
device, such as a mouse. The pointer is used to point at items that users
can select. Contrast with cursor. (2) A data element that indicates the
location of another data element. (T)
POINTER$ - Character-device name reserved for a pointer device (mouse screen
support).
pointing device - In SAA Advanced Common User Access architecture, an
instrument, such as a mouse, trackball, or joystick, used to move a pointer
on the screen.
pointings - Pairs of x-y coordinates produced by an operator defining
positions on a screen with a pointing device, such as a mouse.
polyfillet - A curve based on a sequence of lines. The curve is tangential to
the end points of the first and last lines, and tangential also to the
midpoints of all other lines. See also fillet.
polygon - One or more closed figures that can be drawn filled, outlined, or
filled and outlined.
polyline - A sequence of adjoining lines.
polymorphism - The ability to have different implementations of the same
method for two or more classes of objects.
pop - To retrieve an item from a last-in-first-out stack of items. Contrast
with push.
pop-up menu - A menu that lists the actions that a user can perform on an
object. The contents of the pop-up menu can vary depending on the context,
or state, of the object.
pop-up window - (1) A window that appears on top of another window in a
dialog. Each pop-up window must be completed before returning to the
underlying window. (2) (D of C) In SAA Advanced Common User Access
architecture, a movable window, fixed in size, in which a user provides
information required by an application so that it can continue to process a
user request.
presentation drivers - Special purpose I/O routines that handle field
device-independent I/O requests from the PM and its applications.
Presentation Manager (PM) - The interface of the OS/2 operating system that
presents, in windows a graphics-based interface to applications and files
installed and running under the OS/2 operating system.
presentation page - The coordinate space in which a picture is assembled for
display.
presentation space (PS) - (1) Contains the device-independent definition of a
picture. (2) (D of C) The display space on a display device.
primary window - In SAA Common User Access architecture, the window in which
the main interaction between the user and the application takes place. In a
multiprogramming environment, each application starts in its own primary
window. The primary window remains for the duration of the application,
although the panel displayed will change as the user's dialog moves forward.
See also secondary window.
primitive - In computer graphics, one of several simple functions for drawing
on the screen, including, for example, the rectangle, line, ellipse,
polygon, and so on.
primitive attribute - A specifiable characteristic of a graphic primitive. See
graphics attributes.
print job - The result of sending a document or picture to be printed.
Print Manager - In the Presentation Manager, the part of the spooler that
manages the spooling process. It also allows users to view print queues and
to manipulate print jobs.
privilege level - A protection level imposed by the hardware architecture of
the IBM personal computer. There are four privilege levels (number 0
through 3). Only certain types of programs are allowed to execute at each
privilege level. See also IOPL code segment.
procedure call - In programming languages, a language construct for invoking
execution of a procedure.
process - An instance of an executing application and the resources it is
using.
program - A sequence of instructions that a computer can interpret and
execute.
program details - Information about a program that is specified in the Program
Manager window and is used when the program is started.
program group - In the Presentation Manager, several programs that can be
acted upon as a single entity.
program name - The full file specification of a program. Contrast with program
title.
program title - The name of a program as it is listed in the Program Manager
window. Contrast with program name.
prompt - A displayed symbol or message that requests input from the user or
gives operational information; for example, on the display screen of an IBM
personal computer, the DOS A> prompt. The user must respond to the prompt in
order to proceed.
protect mode - A method of program operation that limits or prevents access to
certain instructions or areas of storage. Contrast with real mode.
protocol - A set of semantic and syntactic rules that determines the behavior
of functional units in achieving communication. (I)
pseudocode - An artificial language used to describe computer program
algorithms without using the syntax of any particular programming language. (A)
pull-down - (1) An action bar extension that displays a list of choices
available for a selected action bar choice. After users select an action bar
choice, the pull-down appears with the list of choices. Additional pop-up
windows may appear from pull-down choices to further extend the actions
available to users. (2) (D of C) In SAA Common User Access architecture,
pertaining to a choice in an action bar pull-down.
push - To add an item to a last-in-first-out stack of items. Contrast with
pop.
push button - In SAA Advanced Common User Access architecture, a rectangle
with text inside. Push buttons are used in windows for actions that occur
immediately when the push button is selected.
putback - To remove an object or set of objects from the lazy drag set. This
has the effect of undoing the pickup operation for those objects
putdown - To drop the objects in the lazy drag set on the target object.
ΓòÉΓòÉΓòÉ <hidden> Glossary - Q ΓòÉΓòÉΓòÉ
queue - (1) A linked list of elements waiting to be processed in FIFO order.
For example, a queue may be a list of print jobs waiting to be printed. (2)
(D of C) A line or list of items waiting to be processed; for example, work
to be performed or messages to be displayed.
queued device context - A logical description of a data destination (for
example, a printer or plotter) where the output is to go through the
spooler. See also device context.
ΓòÉΓòÉΓòÉ <hidden> Glossary - R ΓòÉΓòÉΓòÉ
radio button - (1) A control window, shaped like a round button on the screen,
that can be in a checked or unchecked state. It is used to select a single
item from a list. Contrast with check box. (2) In SAA Advanced Common User
Access architecture, a circle with text beside it. Radio buttons are
combined to show a user a fixed set of choices from which only one can be
selected. The circle is partially filled when a choice is selected.
RAS - Reliability, availability, and serviceability.
raster - (1) In computer graphics, a predetermined pattern of lines that
provides uniform coverage of a display space. (T) (2) The coordinate grid
that divides the display area of a display device. (A)
read-only file - A file that can be read from but not written to.
real mode - A method of program operation that does not limit or prevent
access to any instructions or areas of storage. The operating system loads
the entire program into storage and gives the program access to all system
resources. Contrast with protect mode.
realize - To cause the system to ensure, wherever possible, that the physical
color table of a device is set to the closest possible match in the logical
color table.
recursive routine - A routine that can call itself, or be called by another
routine that was called by the recursive routine.
reentrant - The attribute of a program or routine that allows the same copy of
the program or routine to be used concurrently by two or more tasks.
reference phrase - (1) A word or phrase that is emphasized in a
device-dependent manner to inform the user that additional information for
the word or phrase is available. (2) (D of C) In hypertext, text that is
highlighted and preceded by a single-character input field used to signify
the existence of a hypertext link.
reference phrase help - In SAA Common User Access architecture, highlighted
words or phrases within help information that a user selects to get
additional information.
refresh - To update a window, with changed information, to its current status.
region - A clipping boundary in device space.
register - A part of internal storage having a specified storage capacity and
usually intended for a specific purpose. (T)
remote file system - A file-system driver that gains access to a remote system
without a block device driver.
resource - The means of providing extra information used in the definition of
a window. A resource can contain definitions of fonts, templates,
accelerators, and mnemonics; the definitions are held in a resource file.
resource file - A file containing information used in the definition of a
window. Definitions can be of fonts, templates, accelerators, and mnemonics.
restore - To return a window to its original size or position following a
sizing or moving action.
retained graphics - Graphic primitives that are remembered by the Presentation
Manager interface after they have been drawn. Contrast with nonretained
graphics.
return code - (1) A value returned to a program to indicate the results of an
operation requested by that program. (2) A code used to influence the
execution of succeeding instructions.(A)
reverse video - (1) A form of highlighting a character, field, or cursor by
reversing the color of the character, field, or cursor with its background;
for example, changing a red character on a black background to a black
character on a red background. (2) In SAA Basic Common User Access
architecture, a screen emphasis feature that interchanges the foreground and
background colors of an item.
REXX Language - Restructured Extended Executor. A procedural language that
provides batch language functions along with structured programming
constructs such as loops; conditional testing and subroutines.
RGB - (1) Color coding in which the brightness of the additive primary colors
of light, red, green, and blue, are specified as three distinct values of
white light. (2) Pertaining to a color display that accepts signals
representing red, green, and blue.
roman - Relating to a type style with upright characters.
root segment - In a hierarchical database, the highest segment in the tree
structure.
round-robin scheduling - A process that allows each thread to run for a
specified amount of time.
run time - (1) Any instant at which the execution of a particular computer
program takes place. (T) (2) The amount of time needed for the execution of
a particular computer program. (T) (3) The time during which an instruction
in an instruction register is decoded and performed. Synonym for execution
time.
ΓòÉΓòÉΓòÉ <hidden> Glossary - S ΓòÉΓòÉΓòÉ
SAA - Systems Application Architecture.
SBCS - Single-byte character set.
scheduler - A computer program designed to perform functions such as
scheduling, initiation, and termination of jobs.
screen - In SAA Basic Common User Access architecture, the physical surface of
a display device upon which information is shown to a user.
screen device context - A logical description of a data destination that is a
particular window on the screen. See also device context.
SCREEN$ - Character-device name reserved for the display screen.
scroll bar - In SAA Advanced Common User Access architecture, a part of a
window, associated with a scrollable area, that a user interacts with to see
information that is not currently allows visible.
scrollable entry field - An entry field larger than the visible field.
scrollable selection field - A selection field that contains more choices than
are visible.
scrolling - Moving a display image vertically or horizontally in a manner such
that new data appears at one edge, as existing data disappears at the
opposite edge.
secondary window - A window that contains information that is dependent on
information in a primary window and is used to supplement the interaction in
the primary window.
sector - On disk or diskette storage, an addressable subdivision of a track
used to record one block of a program or data.
segment - See graphics segment.
segment attributes - Attributes that apply to the segment as an entity, as
opposed to the individual primitives within the segment. For example, the
visibility or detectability of a segment.
segment chain - All segments in a graphics presentation space that are defined
with the `chained' attribute. Synonym for picture chain.
segment priority - The order in which segments are drawn.
segment store - An area in a normal graphics presentation space where retained
graphics segments are stored.
select - To mark or choose an item. Note that select means to mark or type in
a choice on the screen; enter means to send all selected choices to the
computer for processing.
select button - The button on a pointing device, such as a mouse, that is
pressed to select a menu choice. Also known as button 1.
selection cursor - In SAA Advanced Common User Access architecture, a visual
indication that a user has selected a choice. It is represented by outlining
the choice with a dotted box. See also text cursor.
selection field - (1) In SAA Advanced Common User Access architecture, a set
of related choices. See also entry field. (2) In SAA Basic Common User
Access architecture, an area of a panel that cannot be scrolled and contains
a fixed number of choices.
semantics - The relationships between symbols and their meanings.
semaphore - An object used by applications for signalling purposes and for
controlling access to serially reusable resources.
separator - In SAA Advanced Common User Access architecture, a line or color
boundary that provides a visual distinction between two adjacent areas.
serial dialog box - See modal dialog box.
serialization - The consecutive ordering of items.
serialize - To ensure that one or more events occur in a specified sequence.
serially reusable resource (SRR) - A logical resource or object that can be
accessed by only one task at a time.
session - (1) A routing mechanism for user interaction via the console; a
complete environment that determines how an application runs and how users
interact with the application. OS/2 can manage more than one session at a
time, and more than one process can run in a session. Each session has its
own set of environment variables that determine where OS/2 looks for
dynamic-link libraries and other important files. (2) (D of C) In the OS/2
operating system, one instance of a started program or command prompt. Each
session is separate from all other sessions that might be running on the
computer. The operating system is responsible for coordinating the resources
that each session uses, such as computer memory, allocation of processor
time, and windows on the screen.
Settings Notebook - A control window that is used to display the settings for
an object and to enable the user to change them.
shadow - An object that refers to another object. A shadow is not a copy of
another object, but is another representation of the object.
shadow box - The area on the screen that follows mouse movements and shows
what shape the window will take if the mouse button is released.
shared data - Data that is used by two or more programs.
shared memory - In the OS/2 operating system, a segment that can be used by
more than one program.
shear - In computer graphics, the forward or backward slant of a graphics
symbol or string of such symbols relative to a line perpendicular to the
baseline of the symbol.
shell - (1) A software interface between a user and the operating system of a
computer. Shell programs interpret commands and user interactions on devices
such as keyboards, pointing devices, and touch-sensitive screens, and
communicate them to the operating system. (2) Software that allows a kernel
program to run under different operating-system environments.
shutdown - The process of ending operation of a system or a subsystem,
following a defined procedure.
sibling processes - Child processes that have the same parent process.
sibling windows - Child windows that have the same parent window.
simple list - A list of like values; for example, a list of user names.
Contrast with mixed list.
single-byte character set (SBCS) - A character set in which each character is
represented by a one-byte code. Contrast with double-byte character set.
slider box - In SAA Advanced Common User Access architecture: a part of the
scroll bar that shows the position and size of the visible information in a
window relative to the total amount of information available. Also known as
thumb mark.
SOM - System Object Model.
source file - A file that contains source statements for items such as
high-level language programs and data description specifications.
source statement - A statement written in a programming language.
specific dynamic-link module - A dynamic-link module created for the exclusive
use of an application.
spin button - In SAA Advanced Common User Access architecture, a type of entry
field that shows a scrollable ring of choices from which a user can select a
choice. After the last choice is displayed, the first choice is displayed
again. A user can also type a choice from the scrollable ring into the
entry field without interacting with the spin button.
spline - A sequence of one or more BВzier curves.
spooler - A program that intercepts the data going to printer devices and
writes it to disk. The data is printed or plotted when it is complete and
the required device is available. The spooler prevents output from
different sources from being intermixed.
stack - A list constructed and maintained so that the next data element to be
retrieved is the most recently stored. This method is characterized as
last-in-first-out (LIFO).
standard window - A collection of window elements that form a panel. The
standard window can include one or more of the following window elements:
sizing borders, system menu icon, title bar, maximize/minimize/restore
icons, action bar and pull-downs, scroll bars, and client area.
static control - The means by which the application presents descriptive
information (for example, headings and descriptors) to the user. The user
cannot change this information.
static storage - (1) A read/write storage unit in which data is retained in
the absence of control signals. (A) Static storage may use dynamic
addressing or sensing circuits. (2) Storage other than dynamic storage. (A)
style - See window style.
subclass - A class that is a child of another class. See also Inheritance.
subdirectory - In an IBM personal computer, a file referred to in a root
directory that contains the names of other files stored on the diskette or
fixed disk.
swapping - (1) A process that interchanges the contents of an area of real
storage with the contents of an area in auxiliary storage. (I) (A) (2) In
a system with virtual storage, a paging technique that writes the active
pages of a job to auxiliary storage and reads pages of another job from
auxiliary storage into real storage. (3) The process of temporarily removing
an active job from main storage, saving it on disk, and processing another
job in the area of main storage formerly occupied by the first job.
switch - (1) In SAA usage, to move the cursor from one point of interest to
another; for example, to move from one screen or window to another or from
a place within a displayed image to another place on the same displayed
image. (2) In a computer program, a conditional instruction and an indicator
to be interrogated by that instruction. (3) A device or programming
technique for making a selection, for example, a toggle, a conditional jump.
switch list - See Task List.
symbolic identifier - A text string that equates to an integer value in an
include file, which is used to identify a programming object.
symbols - In Information Presentation Facility, a document element used to
produce characters that cannot be entered from the keyboard.
synchronous - Pertaining to two or more processes that depend upon the
occurrence of specific events such as common timing signals. (T) See also
asynchronous.
System Menu - In the Presentation Manager, the pull-down in the top left
corner of a window that allows it to be moved and sized with the keyboard.
System Object Model (SOM) - A mechanism for language-neutral, object-oriented
programming in the OS/2 environment.
system queue - The master queue for all pointer device or keyboard events.
system-defined messages - Messages that control the operations of applications
and provides input an other information for applications to process.
Systems Application Architecture (SAA) - A set of IBM software interfaces,
conventions, and protocols that provide a framework for designing and
developing applications that are consistent across systems.
ΓòÉΓòÉΓòÉ <hidden> Glossary - T ΓòÉΓòÉΓòÉ
table tags - In Information Presentation Facility, a document element that
formats text in an arrangement of rows and columns.
tag - (1) One or more characters attached to a set of data that contain
information about the set, including its identification. (I) (A) (2) In
Generalized Markup Language markup, a name for a type of document or
document element that is entered in the source document to identify it.
target object - An object to which the user is transferring information.
Task List - In the Presentation Manager, the list of programs that are active.
The list can be used to switch to a program and to stop programs.
terminate-and-stay-resident (TSR) - Pertaining to an application that modifies
an operating system interrupt vector to point to its own location (known as
hooking an interrupt).
text - Characters or symbols.
text cursor - A symbol displayed in an entry field that indicates where typed
input will appear.
text window - Also known as the VIO window.
text-windowed application - The environment in which the operating system
performs advanced-video input and output operations.
thread - A unit of execution within a process. It uses the resources of the
process.
thumb mark - The portion of the scroll bar that describes the range and
properties of the data that is currently visible in a window. Also known as
a slider box.
thunk - Term used to describe the process of address conversion, stack and
structure realignment, etc., necessary when passing control between 16-bit
and 32-bit modules.
tilde - A mark used to denote the character that is to be used as a mnemonic
when selecting text items within a menu.
time slice - (1) An interval of time on the processing unit allocated for use
in performing a task. After the interval has expired, processing-unit time
is allocated to another task, so a task cannot monopolize processing-unit
time beyond a fixed limit. (2) In systems with time sharing, a segment of
time allocated to a terminal job.
time-critical process - A process that must be performed within a specified
time after an event has occurred.
timer - A facility provided under the Presentation Manager, whereby
Presentation Manager will dispatch a message of class WM_TIMER to a
particular window at specified intervals. This capability may be used by an
application to perform a specific processing task at predetermined
intervals, without the necessity for the application to explicitly keep
track of the passage of time.
timer tick - See clock tick.
title bar - In SAA Advanced Common User Access architecture, the area at the
top of each window that contains the window title and system menu icon. When
appropriate, it also contains the minimize, maximize, and restore icons.
Contrast with panel title.
TLB - Translation lookaside buffer.
transaction - An exchange between a workstation and another device that
accomplishes a particular action or result.
transform - (1) The action of modifying a picture by scaling, shearing,
reflecting, rotating, or translating. (2) The object that performs or
defines such a modification; also referred to as a transformation.
Translation lookaside buffer (TLB) - A hardware-based address caching
mechanism for paging information.
Tree - In the Presentation Manager, the window in the File Manager that shows
the organization of drives and directories.
truncate - (1) To terminate a computational process in accordance with some
rule (A) (2) To remove the beginning or ending elements of a string. (3) To
drop data that cannot be printed or displayed in the line width specified or
available. (4) To shorten a field or statement to a specified length.
TSR - Terminate-and-stay-resident.
unnamed pipe - A circular buffer, created in memory, used by related processes
to communicate with one another. Contrast with named pipe.
unordered list - In Information Presentation Facility, a vertical arrangement
of items in a list, with each item in the list preceded by a special
character or bullet.
update region - A system-provided area of dynamic storage containing one or
more (not necessarily contiguous) rectangular areas of a window that are
visually invalid or incorrect, and therefore are in need of repainting.
user interface - Hardware, software, or both that allows a user to interact
with and perform operations on a system, program, or device.
User Shell - A component of OS/2 that uses a graphics-based, windowed
interface to allow the user to manage applications and files installed and
running under OS/2.
utility program - (1) A computer program in general support of computer
processes; for example, a diagnostic program, a trace program, a sort
program. (T) (2) A program designed to perform an everyday task such as
copying data from one storage device to another. (A)
ΓòÉΓòÉΓòÉ <hidden> Glossary - U ΓòÉΓòÉΓòÉ
There are no glossary terms for this starting letter.
ΓòÉΓòÉΓòÉ <hidden> Glossary - V ΓòÉΓòÉΓòÉ
value set control - A visual component that enables a user to select one
choice from a group of mutually exclusive choices.
vector font - A set of symbols, each of which is created as a series of lines
and curves. Synonymous with outline font. Contrast with image font.
VGA - Video graphics array.
view - A way of looking at an object's information.
viewing pipeline - The series of transformations applied to a graphic object
to map the object to the device on which it is to be presented.
viewing window - A clipping boundary that defines the visible part of model
space.
VIO - Video Input/Output.
virtual memory (VM) - Synonymous with virtual storage.
virtual storage - (1) The storage space that may be regarded as addressable
main storage by the user of a computer system in which virtual addresses are
mapped into real addresses. The size of virtual storage is limited by the
addressing scheme of the computer system and by the amount of auxiliary
storage available, not by the actual number of main storage
locations. (I) (A) (2) Addressable space that is apparent to the user as
the processor storage space, from which the instructions and the data are
mapped into the processor storage locations. (3) Synonymous with virtual
memory.
visible region - A window's presentation space, clipped to the boundary of the
window and the boundaries of any overlying window.
volume - (1) A file-system driver that uses a block device driver for input
and output operations to a local or remote device. (I) (2) A portion of
data, together with its data carrier, that can be handled conveniently as a
unit.
ΓòÉΓòÉΓòÉ <hidden> Glossary - W ΓòÉΓòÉΓòÉ
wildcard character - Synonymous with global file-name character.
window - (1) A portion of a display surface in which display images pertaining
to a particular application can be presented. Different applications can be
displayed simultaneously in different windows. (A) (2) An area of the
screen with visible boundaries within which information is displayed. A
window can be smaller than or the same size as the screen. Windows can
appear to overlap on the screen.
window class - The grouping of windows whose processing needs conform to the
services provided by one window procedure.
window coordinates - A set of coordinates by which a window position or size
is defined; measured in device units, or pels.
window handle - Unique identifier of a window, generated by Presentation
Manager when the window is created, and used by applications to direct
messages to the window.
window procedure - Code that is activated in response to a message. The
procedure controls the appearance and behavior of its associated windows.
window rectangle - The means by which the size and position of a window is
described in relation to the desktop window.
window resource - A read-only data segment stored in the .EXE file of an
application o the .DLL file of a dynamic link library.
window style - The set of properties that influence how events related to a
particular window will be processed.
window title - In SAA Advanced Common User Access architecture, the area in
the title bar that contains the name of the application and the OS/2
operating system file name, if applicable.
Workplace Shell - The OS/2 object-oriented, graphical user interface.
workstation - (1) A display screen together with attachments such as a
keyboard, a local copy device, or a tablet. (2) (D of C) One or more
programmable or nonprogrammable devices that allow a user to do work.
world coordinates - A device-independent Cartesian coordinate system used by
the application program for specifying graphical input and output. (I) (A)
world-coordinate space - Coordinate space in which graphics are defined before
transformations are applied.
WYSIWYG - What-You-See-Is-What-You-Get. A capability of a text editor to
continually display pages exactly as they will be printed.
ΓòÉΓòÉΓòÉ <hidden> Glossary - X ΓòÉΓòÉΓòÉ
There are no glossary terms for this starting letter.
ΓòÉΓòÉΓòÉ <hidden> Glossary - Y ΓòÉΓòÉΓòÉ
There are no glossary terms for this starting letter.
ΓòÉΓòÉΓòÉ <hidden> Glossary - Z ΓòÉΓòÉΓòÉ
z-order - The order in which sibling windows are presented. The topmost
sibling window obscures any portion of the siblings that it overlaps; the
same effect occurs down through the order of lower sibling windows.
zooming - The progressive scaling of an entire display image in order to give
the visual impression of movement of all or part of a display group toward
or away from an observer. (I) (A)
8.3 file-name format - A file-naming convention in which file names are
limited to eight characters before and three characters after a single dot.
Usually pronounced "eight-dot-three." See also non-8.3 file-name format.
ΓòÉΓòÉΓòÉ <hidden> IBM Trademark ΓòÉΓòÉΓòÉ
Trademark of the IBM Corporation.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of AT&T, Inc.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of the Intel Corporation.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of Western Digital Corporation.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of Orchid Technology, Inc.
(.txt)
(.txt)