HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
126.96.36.199.7 Error Recovery
Whenever possible, ICC services attempt to return an appropriate status
value to the caller, either as the routine status value or in the
status fields of the IOSB or IOS_ICC structure. Sometimes the only
recovery method available to ICC is to disconnect the connection. ICC
disconnects only when it lacks sufficient context to return status to
the calling application.
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.
To open an association to ICC, call ICC$OPEN_ASSOC, which provides the following parameters:
188.8.131.52.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: GETUTC--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 either must be supplied 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.
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
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:
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.
|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.|
|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.|
|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
You need additional privileges to perform some specific functions; for
example, raising the base priority of a process requires ALTPRI
4.1.2 Determining Process Identification
There are two types of process identification:
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:
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.
|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.|
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: