Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Programming Concepts Manual
Previous Contents Index

Chapter 4
Process Control

This chapter describes how to use operating system features to control a process or kernel thread. It contains the following sections:

Section 4.1 describes the control of a process or kernel thread to complete a programming task.

Section 4.2 describes how to use the operating system's process information services to gather information about a process or kernel thread.

Section 4.3 describes how to change a process's scheduling.

Section 4.4 describes the affinity and capability mechanisms for CPU scheduling.

Section 4.5 describes the class scheduler and how to use it on both VAX and Alpha systems.

Section 4.6 describes how to change a process's name.

Section 4.7 describes how to access another process's context.

Section 4.8 describes how to synchronize programs by setting specific times for program execution.

Section 4.9 describes how to suspend, resume, and stop program execution.

4.1 Using Process Control for Programming Tasks

Process control features in the operating system allow you to employ the following techniques to design your application:

Among the services and routines the operating system provides to help you monitor and control the processes or kernel threads involved in your application are those that perform the following functions:

You can use system routines and DCL commands to accomplish these tasks. Table 4-1 summarizes which routines and commands to use. You can use the DCL commands in a command procedure that is executed as soon as the subprocess (or detached process) is created.

For process synchronization techniques other than specifying a time for program execution, refer to Chapters 6, 7, and 8.

Table 4-1 Routines and Commands for Controlling Processes and Kernel Threads
Routine DCL Command Task
LIB$GETJPI
SYS$GETJPI
SYS$GETJPIW 		SHOW PROCESS Return process or kernel thread information. SYS$GETJPI(W) can request process and thread information from a specific PID or PRCNAM. If no specific thread is identified, then the data represents the initial thread.
SYS$SETPRV SET PROCESS Set process privileges.
SYS$SETPRI SET PROCESS Set process or kernel thread priority. This service affects the base and current priority of a specified kernel thread and not the entire process.
SYS$SETSWM SET PROCESS Control swapping of process.
SYS$HIBER
SYS$SUSPND
SYS$RESUME 		SET PROCESS Hibernate, suspend, and resume a process or kernel threads. These services hibernate, suspend, or resume all kernel threads associated with the specified process.
SYS$SETPRN SET PROCESS Set process name.
SYS$FORCEX
SYS$EXIT 		EXIT and STOP Initiate process and image rundown. All associated kernel threads of a specified process are run down and deleted.
SYS$DELPRC EXIT and STOP Delete process.
SYS$CANTIM CANCEL Cancel timer for process or kernel threads. This service finds and cancels all timers for all threads associated with the specified process.
SYS$ADJSTK SET PROCESS Adjust or initialize a stack pointer. Stack adjustments are performed for the kernel thread requesting the service.
SYS$PROCESS_SCAN SHOW PROCESS Scan for a process or kernel thread on the local system, or across the nodes in an OpenVMS Cluster system.
SYS$SETSTK None available Allow the current process or kernel thread to change the size of its stacks. This service adjusts the size of the stacks of the kernel thread that invoked the service.

By default, the routines and commands reference the current process or kernel thread. To reference another process, you must specify either the process identification (PID) number or the process name when you call the routine or a command qualifier when you enter commands. You must have the GROUP privilege to reference a process with the same group number and a different member number in its UIC, and WORLD privilege to reference a process with a different group number in its UIC.

The information presented in this section covers using the routines. If you want to use the DCL commands in a command procedure, refer to the OpenVMS DCL Dictionary.

4.1.1 Determining Privileges for Process Creation and Control

There are three levels of process control privilege:

You need additional privileges to perform some specific functions; for example, raising the base priority of a process requires ALTPRI privilege.

4.1.2 Determining Process Identification

There are two types of process identification:

For example, you could call the SYS$CREPRC system service, as follows: 


unsigned int orionid=0, status; 
$DESCRIPTOR(orion,"ORION"); 
   .
   .
   .
status = SYS$CREPRC(&orionid,           /* pidadr (process id returned) */ 
                    &orion,             /* prcnam  - process name */ 
                ...);

The service returns the process identification in the longword at ORIONID. You can now use either the process name (ORION) or the PID (ORIONID) to refer to this process in other system service calls.

A process can set or change its own name with the Set Process Name ($SETPRN) system service. For example, a process can set its name to CYGNUS, as follows: 


/* Descriptor for process name */ 
        $DESCRIPTOR(cygnus,"CYGNUS"); 
 
        status = SYS$SETPRN( &cygnus );   /* prcnam -  process name */

Most of the process control services accept the prcnam or the pidadr argument or both. However, you should identify a process by its process identification number for the following reasons:

If you specify the PID address, the service uses the PID address. If you specify the process name without a PID address, the sevice uses the process name. If you specify both---the process name and PID address---it uses the PID address unless the contents of the PID is 0. In that case, the service uses the process name. If you specify a PID address of 0 without a process name, then the service is performed for the calling process.

If you specify neither the process name argument nor the process identification number argument, the service is performed for the calling process. If the PID address is specified, the service returns the PID of the target process in it. Table 4-2 summarizes the possible combinations of these arguments and explains how the services interpret them.

Table 4-2 Process Identification
Process
Name
Specified? 		PID
Address
Specified? 		Contents of
PID 		Resultant
Action
by Services
No No -- The process identification of the calling process is used, but is not returned.
No Yes 0 The process identification of the calling process is used and returned.
No Yes PID The process identification is used and returned.
Yes No -- The process name is used. The process identification is not returned.
Yes Yes 0 The process name is used and the process identification is returned.
Yes Yes PID The process identification is used and returned; the process name is ignored.

4.1.3 Qualifying Process Naming Within Groups

Process names are always qualified by their group number. The system maintains a table of all process names and the UIC associated with each. When you use the prcnam argument in a process control service, the table is searched for an entry that contains the specified process name and the group number of the calling process.

To use process control services on processes within its group, a calling process must have the GROUP user privilege; this privilege is not required when you specify a process with the same UIC as the caller.

The search for a process name fails if the specified process name does not have the same group number as the caller. The search fails even if the calling process has the WORLD user privilege. To execute a process control service for a process that is not in the caller's group, the requesting process must use a process identification and must have the WORLD user privilege.

4.2 Obtaining Process Information

The operating system's process information procedures enable you to gather information about processes and kernel threads. You can obtain information about either one process or a group of processes on either the local system or on remote nodes in an OpenVMS Cluster system. You can also obtain process lock information. DCL commands such as SHOW SYSTEM and SHOW PROCESS use the process information procedures to display information about processes. You can also use the process information procedures within your programs.

The following are process information procedures:

The SYS$GETJPI(W) and SYS$PROCESS_SCAN system services can also be used to get kernel threads information. SYS$GETJPI(W) can request threads information from a particular process ID or process name. SYS$PROCESS_SCAN can request information about all threads in a process, or all threads for each multithreaded process on the system.

For more information about SYS$GETJPI, SYS$PROCESS_SCAN, and SYS$GETLKI, see the OpenVMS System Services Reference Manual.

The differences among these procedures are as follows:

4.2.1 Using the PID to Obtain Information

The process information procedures return information about processes by using the process identification (PID) or the process name. The PID is a 32-bit number that is unique for each process in the cluster. Specify the PID by using the pidadr argument. You must specify all the significant digits of a PID; you can omit leading zeros.

With kernel threads, the PID continues to identify a process, but it can also identify a kernel thread within that process. In a multithreaded process each kernel thread has its own PID that is based on the initial threads PID.

4.2.2 Using the Process Name to Obtain Information

To obtain information about a process using the process name, specify the prcnam argument. Although a PID is unique for each process in the cluster, a process name is unique (within a UIC group) only for each process on a node. To locate information about processes on the local node, specify a process name string of 1 to 15 characters. To locate information about a process on a particular node, specify the full process name, which can be up to 23 characters long. The full process name is configured in the following way:

Note that a local process name can look like a remote process name. Therefore, if you specify ATHENS::SMITH, the system checks for a process named ATHENS::SMITH on the local node before checking node ATHENS for a process named SMITH.

Chapter 17 and the OpenVMS System Services Reference Manual describe these routines completely, listing all items of information that you can request. LIB$GETJPI, SYS$GETJPI, and SYS$GETJPIW share the same item codes with the following exception: LIB$K_ items can be accessed only by LIB$GETJPI.

In the following example, the string argument rather than the numeric argument is specified, causing LIB$GETJPI to return the UIC of the current process as a string: 


! Define request codes 
INCLUDE '($JPIDEF)' 
 
! Variables for LIB$GETJPI 
CHARACTER*9 UIC 
INTEGER LEN 
 
STATUS = LIB$GETJPI (JPI$_UIC, 
2                    ,,, 
2                    UIC, 
2                    LEN)

To specify a list of items for SYS$GETJPI or SYS$GETJPI(W) (even if that list contains only one item), use a record structure. Example 4-1 uses SYS$GETJPI(W) to request the process name and user name associated with the process whose process identification number is in SUBPROCESS_PID.

Example 4-1 Obtaining Different Types of Process Information 

   .
   .
   .
! PID of subprocess 
INTEGER SUBPROCESS_PID 
 
! Include the request codes 
INCLUDE '($JPIDEF)' 
! Define itmlst structure 
STRUCTURE /ITMLST/ 
 UNION 
  MAP 
   INTEGER*2 BUFLEN 
   INTEGER*2 CODE 
   INTEGER*4 BUFADR 
   INTEGER*4 RETLENADR 
  END MAP 
  MAP 
   INTEGER*4 END_LIST 
  END MAP 
 END UNION 
END STRUCTURE 
! Declare GETJPI itmlst 
RECORD /ITMLST/ JPI_LIST(3) 
! Declare buffers for information 
CHARACTER*15    PROCESS_NAME 
CHARACTER*12    USER_NAME 
INTEGER*4       PNAME_LEN, 
2               UNAME_LEN 
! Declare I/O status structure 
STRUCTURE /IOSB/ 
 INTEGER*2 STATUS, 
2          COUNT 
 INTEGER*4 %FILL 
END STRUCTURE 
! Declare I/O status variable 
RECORD /IOSB/ JPISTAT 
! Declare status and routine 
INTEGER*4       STATUS, 
2               SYS$GETJPIW 
                   . 
                   . ! Define SUBPROCESS_PID 
                   . 
! Set up itmlst 
JPI_LIST(1).BUFLEN    = 15 
JPI_LIST(1).CODE      = JPI$_PRCNAM 
JPI_LIST(1).BUFADR    = %LOC(PROCESS_NAME) 
JPI_LIST(1).RETLENADR = %LOC(PNAME_LEN) 
JPI_LIST(2).BUFLEN    = 12 
JPI_LIST(2).CODE      = JPI$_USERNAME 
JPI_LIST(2).BUFADR    = %LOC(USER_NAME) 
JPI_LIST(2).RETLENADR = %LOC(UNAME_LEN) 
JPI_LIST(3).END_LIST  = 0 
! Request information and wait for it 
STATUS = SYS$GETJPIW (, 
2                     SUBPROCESS_PID, 
2                     , 
2                     JPI_LIST, 
2                     JPISTAT, 
2                     ,) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
! Check final return status 
IF (.NOT. JPISTAT.STATUS) THEN 
  CALL LIB$SIGNAL (%VAL(JPISTAT.STATUS)) 
END IF 
   .
   .
   .

4.2.3 Using SYS$GETJPI and LIB$GETJPI

SYS$GETJPI uses the PID or the process name to obtain information about one process and the -1 wildcard as the pidadr to obtain information about all processes on the local system. If a PID or process name is not specified, SYS$GETJPI returns information about the calling process. SYS$GETJPI cannot perform a selective search---it can search for only one process at a time in the cluster or for all processes on the local system. If you want to perform a selective search for information or get information about processes across the cluster, use SYS$GETJPI with SYS$PROCESS_SCAN.

4.2.3.1 Requesting Information About a Single Process

Example 4-2 is a Fortran program that displays the process name and the PID of the calling program. If you want to get the same information about each process on the system, specify the initial process identification argument as -1 when you invoke LIB$GETJPI or SYS$GETJPI(W). Call the GETJPI routine (whichever you choose) repeatedly until it returns a status of SS$_NOMOREPROC, indicating that all processes on the system have been examined.

Example 4-2 Using SYS$GETJPI to Obtain Calling Process Information 

! No process name or PID is specified; $GETJPI returns data on the 
! calling process. 
 
        PROGRAM CALLING_PROCESS 
 
        IMPLICIT NONE                   ! Implicit none 
 
        INCLUDE '($jpidef)   /nolist'   ! Definitions for $GETJPI 
 
        INCLUDE '($ssdef)    /nolist'    ! System status codes 
 
        STRUCTURE /JPIITMLST/           ! Structure declaration for 
         UNION                          !  $GETJPI item lists 
          MAP 
           INTEGER*2 BUFLEN, 
        2            CODE 
           INTEGER*4 BUFADR, 
        2            RETLENADR 
          END MAP 
          MAP                           ! A longword of 0 terminates 
           INTEGER*4 END_LIST           !  an item list 
          END MAP 
         END UNION 
        END STRUCTURE 
        RECORD /JPIITMLST/              ! Declare the item list for 
        2         JPILIST(3)            !  $GETJPI 
 
        INTEGER*4 SYS$GETJPIW           ! System service entry points 
 
        INTEGER*4 STATUS,               ! Status variable 
        2         PID                   ! PID from $GETJPI 
 
        INTEGER*2 IOSB(4)               ! I/O Status Block for $GETJPI 
 
        CHARACTER*16 
        2         PRCNAM                ! Process name from $GETJPI 
        INTEGER*2 PRCNAM_LEN            ! Process name length 
        ! Initialize $GETJPI item list 
 
        JPILIST(1).BUFLEN    = 4 
        JPILIST(1).CODE      = JPI$_PID 
        JPILIST(1).BUFADR    = %LOC(PID) 
        JPILIST(1).RETLENADR = 0 
        JPILIST(2).BUFLEN    = LEN(PRCNAM) 
        JPILIST(2).CODE      = JPI$_PRCNAM 
        JPILIST(2).BUFADR    = %LOC(PRCNAM) 
        JPILIST(2).RETLENADR = %LOC(PRCNAM_LEN) 
        JPILIST(3).END_LIST  = 0 
        ! Call $GETJPI to get data for this process 
 
        STATUS = SYS$GETJPIW ( 
        2                    ,           ! No event flag 
        2                    ,           ! No PID 
        2                    ,           ! No process name 
        2                    JPILIST,    ! Item list 
        2                    IOSB,       ! Always use IOSB with $GETJPI! 
        2                    ,           ! No AST 
        2                    )           ! No AST arg 
        ! Check the status in both STATUS and the IOSB, if 
        ! STATUS is OK then copy IOSB(1) to STATUS 
 
        IF (STATUS) STATUS = IOSB(1) 
 
        ! If $GETJPI worked, display the process, if done then 
        ! prepare to exit, otherwise signal an error 
 
        IF (STATUS) THEN 
                TYPE 1010, PID, PRCNAM(1:PRCNAM_LEN) 
1010                FORMAT (' ',Z8.8,'  ',A) 
        ELSE 
                CALL LIB$SIGNAL(%VAL(STATUS)) 
        END IF 
 
        END

Example 4-3 creates the file PROCNAME.RPT that lists, using LIB$GETJPI, the process name of each process on the system. If the process running this program does not have the privilege necessary to access a particular process, the program writes the words NO PRIVILEGE in place of the process name. If a process is suspended, LIB$GETJPI cannot access it and the program writes the word SUSPENDED in place of the process name. Note that, in either of these cases, the program changes the error value in STATUS to a success value so that the loop calling LIB$GETJPI continues to execute.

Example 4-3 Obtaining the Process Name 

   .
   .
   .
! Status variable and error codes 
INTEGER STATUS, 
2       STATUS_OK, 
2       LIB$GET_LUN, 
2       LIB$GETJPI 
INCLUDE '($SSDEF)' 
PARAMETER (STATUS_OK = 1) 
 
! Logical unit number and file name 
INTEGER*4 LUN 
CHARACTER*(*) FILE_NAME 
PARAMETER (FILE_NAME = 'PROCNAME.RPT') 
! Define item codes for LIB$GETJPI 
INCLUDE '($JPIDEF)' 
 
! Process name 
CHARACTER*15 NAME 
INTEGER LEN 
! Process identification 
INTEGER PID /-1/ 
   .
   .
   .
! Get logical unit number and open the file 
STATUS = LIB$GET_LUN (LUN) 
OPEN (UNIT = LUN, 
2     FILE = 'PROCNAME.RPT', 
2     STATUS = 'NEW') 
! Get information and write it to file 
DO WHILE (STATUS) 
  STATUS = LIB$GETJPI(JPI$_PRCNAM, 
2                     PID, 
2                     ,, 
2                     NAME, 
2                     LEN) 
  ! Extra space in WRITE commands is for 
  ! FORTRAN carriage control 
  IF (STATUS) THEN 
    WRITE (UNIT = LUN, 
2          FMT = '(2A)') ' ', NAME(1:LEN) 
    STATUS = STATUS_OK 
  ELSE IF (STATUS .EQ. SS$_NOPRIV) THEN 
    WRITE (UNIT = LUN, 
2          FMT = '(2A)') ' ', 'NO PRIVILEGE' 
    STATUS = STATUS_OK 
  ELSE IF (STATUS .EQ. SS$_SUSPENDED) THEN 
    WRITE (UNIT = LUN, 
2          FMT = '(2A)') ' ', 'SUSPENDED' 
    STATUS = STATUS_OK 
  END IF 
 
END DO 
! Close file 
IF (STATUS .EQ. SS$_NOMOREPROC) 
2  CLOSE (UNIT = LUN) 
   .
   .
   .

Example 4-4 demonstrates how to use the process name to obtain information about a process.

Example 4-4 Using SYS$GETJPI and the Process Name to Obtain Information About a Process 

! To find information for a particular process by name, 
! substitute this code, which includes a process name, 
! to call $GETJPI in Example 4-2
 
! Call $GETJPI to get data for a named process 
 
STATUS = SYS$GETJPIW ( 
2                    ,           ! No event flag 
2                    ,           ! No PID 
2                    'SMITH_1',  ! Process name 
2                    JPILIST,    ! Item list 
2                    IOSB,       ! Always use IOSB with $GETJPI! 
2                    ,           ! No AST 
2                    )           ! No AST arg

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5841PRO_009.HTML