DosGetPrty

This call gets the priority of the initial thread of execution for any process, or any thread in the current process.

Syntax

DosGetPrty (Scope, Priority, ID)

Parameters

Scope (USHORT) - input

Scope of priority request. Used to define the scope of the request.

0 - Thread 1 (the initial thread of execution) of the indicated process.

2 - Any thread of the current process.

Priority (PUSHORT) - output

Address of the base priority of the thread identified by ID. The high-order byte of this word is set equal to the priority class. The low-order byte is set equal to the priority level.

ID (USHORT) - input

A process ID (scope = 0) or a thread ID (scope = 2). If this operand is equal to 0, the current process or thread is assumed.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 303 ERROR_INVALID_PROCID
• 308 ERROR_INVALID_SCOPE
• 309 ERROR_INVALID_THREADID

Remarks

If scope = 0 (process) the priority of the first thread of a process is returned. If that thread has terminated, the ERROR_INVALID_THREAD_ID error code is returned.

A thread's priority is changed by issuing DosSetPrty. A process can change the priority of all the threads of any process whose process ID is known to the thread. It can also change the priority of another thread in its process, or all the threads of the current or a child process, as well as all its descendants.

DosGetPID and DosGetPPID are useful for obtaining process and thread IDs. DosGetPID gets the ID of the current thread, the process ID of its current process, or the process ID of the parent process of the current process. DosGetPPID gets the parent process ID of any specified process.

Bindings

C

#define INCL_DOSPROCESS

USHORT  rc = DosGetPrty(Scope, Priority, ID);

USHORT  Scope;         /* Indicate scope of query */
PUSHORT Priority;      /* Address to put priority (returned) */
USHORT  ID;            /* Process or thread ID */

USHORT  rc;            /* return code */

MASM

EXTRN  DosGetPrty:FAR
INCL_DOSPROCESS     EQU 1

PUSH   WORD    Scope         ;Indicate scope of query
PUSH@  WORD    Priority      ;Priority (returned)
PUSH   WORD    ID            ;Process or thread ID
CALL   DosGetPrty

Returns WORD

Example

The following example illustrates how to obtain the priority of a thread and how to change the priority. The main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints a line and then sleeps, relinquishing its time slice to the main thread. After one or two iterations by Thread2, the main thread obtains Thread2's priority information and prints it. It then raises Thread2's priority to fixed-high, and increments the level by ten. Since Thread2 is now at a high priority, it immediately finishes its remaining iterations before relinquishing control on a long sleep; at this point, the main thread re-examines Thread2's priority and reports its new priority level. In this example, it is helpful to understand how the DosSleep calls are used either to relinquish control of the processor, or to keep a thread alive (see DosTimerAsync or DosTimerStart for alternatives to DosSleep).

#define INCL_DOSPROCESS

#include <os2.h>

#define  PRTYC_FIXEDHIGH   4         /* Priority class: fixed-high */
#define  PRTY_DELTA        10        /* Priority delta: increase by 10 */
#define  SEGSIZE           4000      /* Number of bytes requested in segment */
#define  ALLOCFLAGS        0         /* Segment allocation flags - no sharing */
#define  SLEEPSHORT        0L        /* Sleep interval - 5 milliseconds */
#define  SLEEPLONG         20L       /* Sleep interval - 75 milliseconds */
#define  RETURN_CODE       0         /* Return code for DosExit() */

VOID APIENTRY Thread2()
{
  USHORT     i;

  /* Loop with four iterations */
  for(i=1; i<5; i++)
  {
    printf("In Thread2, i is now %d\n", i);

    /** Sleep to relinquish time slice to main thread **/
    DosSleep(SLEEPSHORT);          /* Sleep interval */
  }
  DosExit(EXIT_THREAD,             /* Action code - end a thread */
          RETURN_CODE);            /* Return code */
}

main()
{
  USHORT     Priority;            /* Thread priority */
  USHORT     Class;               /* Priority class */
  USHORT     Level;               /* Priority level */
  SEL        ThreadStackSel;      /* Segment selector for thread stack */
  PBYTE      StackEnd;            /* Ptr. to end of thread stack */
  USHORT     rc;

  /* Allocate segment for thread stack; this is better than just */
  /* declaring an array of bytes to use as a stack.  Make pointer eos. */

  rc = DosAllocSeg(SEGSIZE,            /* Number of bytes requested */
                   &ThreadStackSel,    /* Segment selector (returned) */
                   ALLOCFLAGS);        /* Allocation flags */
  StackEnd = MAKEP(ThreadStackSel, SEGSIZE-1);

  /* Start Thread2 */
  if(!(DosCreateThread((PFNTHREAD) Thread2,    /* Thread address */
                       &ThreadID,              /* Thread ID (returned) */
                       StackEnd)))             /* End of thread stack */
    printf("Thread2 created.\n");

  /** Sleep to allow Thread2 to execute **/
  if(!(DosSleep(SLEEPLONG)))                       /* Sleep interval */
    printf("Slept a little to let Thread2 execute.\n");

  /** Obtain Thread2's priority information and report it **/
  if(!(rc=DosGetPrty(PRTYS_THREAD,          /* Scope - single thread */
                     &Priority,             /* Address to put priority */
                     ThreadID)))                  /* ID - thread ID */
  {
    /* Extract priority class and level information */
    Class = HIBYTE(Priority);
    Level = LOBYTE(Priority);
    printf("Thread2: ID is %d, Priority Class is %d and Level is %d\n",
           ThreadID, Class, Level);
  }
  /** Raise Thread2's priority **/
  if(!(rc=DosSetPrty(PRTYS_THREAD,         /* Scope - single thread */
                     PRTYC_FIXEDHIGH,      /* Prty class - fixed-high */
                     PRTY_DELTA,           /* Prty delta - increase by 10 */
                     ThreadID)))           /* ID - thread ID */
  {
    /* Obtain Thread2' new priority information and report it */
    rc=DosGetPrty(PRTYS_THREAD,            /* Scope - single thread */
                  &Priority,               /* Address to put priority */
                  ThreadID);               /* ID - thread ID */

    /* Extract priority class and level information */
    Class = HIBYTE(Priority);
    Level = LOBYTE(Priority);
    printf("Thread2: ID is %d, New Priority Class is %d and Level is %d\n",
           ThreadID, Class, Level);
  }
}