Document revision date: 19 July 1999

The ICC public structures and constants are declared in the module $ICCDEF (MACRO), within STARLET.REQ for BLISS and ICCDEF.H in SYS$LIBRARY:SYS$STARLET_C.TLB for C. STARLET.H provides full system service prototypes for C.

2.3.1.4 Servers

Opening an Association to ICC:

Call ICC$OPEN_ASSOC providing the following parameters:

Parameter	Description
assoc_handle	Address to receive the association handle. (longword) Required.
assoc_name	Address of a string descriptor pointing to the desired association name. If you omit this argument, the ICC default association will be opened. Association names are case sensitive. This is also the name used in the ICC security object for this association.
logical_name logical_table	Address of string descriptors describing the logical name and logical table name for use by the ICC simple registry. The logical name table must exist at the time of the call, and the caller must have write access to the table. Unless your application requires a logical name table for exclusive use of the application, use of the default ICC$REGISTRY_TABLE is recommended. The logical name is case sensitive. Table names are always converted to uppercase. The logical name supplied here is the name by which client using the registry will know the server. If either of these arguments is supplied, they must both be supplied.
conn_event_rtn	Address of a routine to be called whenever a client requests a connection to this server. A server may not omit this parameter. See the sections on connection and disconnection routines for more details about what actions a connection routine must take.
disc_event_rtn	Optional address of a routine to be called when a disconnect event occurs. This may be the same routine as the connection routine. See the section on connection and disconnection routines for more details about what actions a disconnection routine may take.
recv_rtn	Optional. Address of routine to be called whenever a connection receives data. Note that all connections on this association use the same routine. Please see the discussion on transfer sizes in Section 2.3.1.2.4 for information on how having or not a having a data routine affects maximum receive size.
maxflowbufcnt	Optional. Pass by value the maximum number of inbound messages per connection that ICC will allow before initiating flow control on the connection. The default value for this parameter is 5.
prot	The default protection for this association. Refer to OpenVMS Guide to System Security for information on the security attributes of ICC associations. This parameter is effective only if no Permanent Security Object has been created for this association. If prot is zero (0) or not specified, all users may connect to this association. If prot is one (1), only members of the same UIC group, or users with SYSPRV, may connect. If prot is two (2), only the owner or users with SYSPRV may connect. Object protection specified by a Permanent Security Object overrides this parameter. Additionally, if no Permanent Security Object exists, the value specified here may be overridden by the SET SECURITY command issued for the Temporary Security Object while the association is open.

2.3.1.4.1 Connection Events

Once the association is opened, connection requests are delivered as asynchronous calls to the server's connection routine.

The connection routine (and disconnection routine, if supplied) are each called with seven arguments as described in the $ICC_OPEN_ASSOC system service, located in the OpenVMS System Services Reference Manual: GETQUI--Z.

A single connection or disconnection routine may distinguish between the events based on the first argument (event_type) which will either be the code ICC$C_EV_CONNECT or ICC$C_EV_DISCONNECT.

A connection routine must either call SYS$ICC_ACCEPT to complete the connection or SYS$ICC_REJECT to reject the connection. The EPID and username of the requesting process are supplied by ICC. Any additional information required by the application for verification must be supplied either by the client via the connection data parameter or must be obtainable by the server itself (for example, via SYS$GETJPI.)

Failure to ACCEPT or REJECT the connection will stall all additional attempts to connect to this server.

2.3.1.4.2 Disconnection Events

A disconnect event signals either that the partner application of the connection has requested a disconnect, the partner process has been deleted, or that the remote node has left the cluster. Upon receiving a disconnect event, the server should call SYS$ICC_DISCONNECT to clean up the server side of the connection.

Failure to call DISCONNECT may leave resources allocated to the connection that will not be released until the image terminates. In the case of inner mode associations, resources will be released at process termination.

2.3.1.5 Clients

A simple client need not call SYS$ICC_OPEN_ASSOC although there may be some benefits for even the simplest clients. For a client, the major benefit of calling OPEN is declaring a data receive routine.

In cases where a client may wish to connect to multiple servers, calling OPEN_ASSOC multiple times can help isolate the routines related to data receipt and disconnection.

Call SYS$ICC_CONNECT[W] with the following arguments:

Argument	Description
IOS_ICC	Address of an IOS_ICC structure (defined in ICCDEF).
astadr astprm	Optional AST address and parameter.
assoc_handle	Either the value returned from the OPEN_ASSOC call or the constant ICC$DEFAULT_ASSOC if OPEN_ASSOC was not called.
conn_handle	Address of a longword to receive the connection handle for this connection.
remote_assoc	A string descriptor pointing to either the association name of the server or the registry name of the server if the server is using the ICC simple registry. Either use is case sensitive.
remote_node	If omitted, then the assoc_name argument will be treated as a name to look up in the ICC simple registry. A zero length or blank string represents the local node. Any other string will be converted to uppercase and must match the name of a node in the cluster.
user_context	A unique context value for this connection. This value will be passed to data event and disconnection routines.
conn_buf conn_buf_len	Address and length of any connection data. This could include additional authentication or protocol setup data required by the application.
return_buf return_buf_len retlen_addr	Address and length of a buffer to receive any data (accept or reject data) returned from the server. The buffer must be large enough to receive the maximum amount of data the server might return. The actual number of bytes will be written to retlen_addr.
flags	The only valid flag is ICC$M_SYNCH_MODE. If you select synch mode, the data transmission routines (TRANSMIT, REPLY, and RECEIVE---TRANSCEIVE can never complete synchronously) may return the alternate success status SS$_SYNCH and not call the AST completion routine. If you do not specify synch mode, the AST routine, if provided, will always be called.

When the CONNECT call completes, the connection is established and useable only if success status was returned as both the return value of the service and in the status fields (ios_icc$w_status and ios_icc$l_remstat) of the IOS_ICC.

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

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

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

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

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

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

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

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

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

3.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:

• Modularize application programs so that each process or kernel thread of the application executes a single task
• Perform parallel processing, in which one process or kernel thread executes one part of a program while another process or kernel thread executes another part
• Implement application program control, in which one process manages and coordinates the activities of several other processes
• Schedule program execution
• Dedicate a process to execute DCL commands
• Isolate code for one or more of the following reasons:
  • To debug logic errors
  • To execute privileged code
  • To execute sensitive code

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:

• Obtaining process information
• Obtaining kernel thread information
• Setting process privileges
• Setting process name
• Setting process scheduling
• Hibernating or suspending a process or kernel thread
• Deleting a process
• Synchronizing process execution

You can use system routines and DCL commands to accomplish these tasks. Table 3-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 Chapter 5, Chapter 16, and Chapter 17.

Table 3-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	Scans for a process or kernel thread on the local system, or across the nodes in an OpenVMS Cluster system.
SYS$SETSTK	None available	Allows 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 with 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.

3.1.1 Determining Privileges for Process Creation and Control

There are three levels of process control privilege:

• Processes with the same UIC can always issue process control services for one another.
• You need the GROUP privilege to issue process control services for other processes executing in the same group.
• You need the WORLD privilege to issue process control services for any process in the system.

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

3.1.2 Determining Process Identification

There are two types of process identification:

• Process identification (PID) number
  The system assigns this unique 32-bit number to a process when it is created. If you provide the pidadr argument to the SYS$CREPRC system service, the system returns the process identification number at the location specified. You can then use the process identification number in subsequent process control services.

• Process name
  There are two types of process names:
  • Process name
    A process name is a 1- to 15-character name string. Each process name must be unique within its group (processes in different groups can have the same name). You can assign a name to a process by specifying the prcnam argument when you create it. You can then use this name to refer to the process in other system service calls. Note that you cannot use a process name to specify a process outside the caller's group; you must use a process identification (PID) number.
  • Full process name
    The full process name is unique for each process in the cluster. Full process name strings can be up to 23 characters long and are configured in the following way:
    • 1--6 characters for the node name
    • 2 characters for the colons (::) that follow the node name
    • 1--15 characters for the local process name

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:

• The service executes faster because it does not have to search a table of process names.
• For a process not in your group, you must use the process identification number (see Section 3.1.3).

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---the PID address is used unless the contents of the PID is 0. In that case, the process name is used. 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 3-2 summarizes the possible combinations of these arguments and explains how the services interpret them.

Table 3-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.

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

3.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 one process or a group of processes on 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:

• Get Job/Process Information (SYS$GETJPI(W))
• Get Job/Process Information (LIB$GETJPI)
• Process Scan (SYS$PROCESS_SCAN)
• Get Lock Information (SYS$GETLKI)

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:

• SYS$GETJPI operates asynchronously.
• SYS$GETJPIW and LIB$GETJPI operate synchronously.
• SYS$GETJPI and SYS$GETJPIW can obtain one or more pieces of information about a process or kernel thread in a single call.
• LIB$GETJPI can obtain only one piece of information about a process or kernel thread in a single call.
• SYS$GETJPI and SYS$GETJPIW can specify an AST to execute at the completion of the routine.
• SYS$GETJPI and SYS$GETJPIW can use an I/O status block (IOSB) to test for completion of the routine.
• LIB$GETJPI can return some items either as strings or as numbers. It is often the easiest to call from a high-level language because the caller is not required to construct an item list.
• SYS$GETLKI returns information about the lock database.

	privacy and legal statement
5841PRO_005.HTML