System Services, $CREPRC
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help System Services, $CREPRC *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
Creates, on behalf of the calling process, a subprocess or
detached process on the current node, or a detached process on
another OpenVMS Cluster node.
Format
SYS$CREPRC [pidadr] ,[image] ,[input] ,[output] ,[error]
,[prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic]
,[mbxunt] ,[stsflg] ,[itmlst] ,[node] ,[home_rad]
C Prototype
int sys$creprc (unsigned int *pidadr, void *image, void
*input, void *output, void *error, struct
_generic_64 *prvadr, unsigned int *quota, void
*prcnam, unsigned int baspri, unsigned int
uic, unsigned short int mbxunt, unsigned int
stsflg,...);
| 1 - Arguments |
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: write only
mechanism: by reference
Process identification (PID) of the newly created process. The
pidadr argument is the address of a longword into which $CREPRC
writes the PID.
image
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the image to be activated in the newly created process.
The image argument is the address of a character string
descriptor pointing to the file specification of the image.
The image name can have a maximum of 63 characters. If the image
name contains a logical name, the logical name is translated in
the created process and must therefore be in a logical name table
that it can access.
To create a process that will run under the control of a command
language interpreter (CLI), specify SYS$SYSTEM:LOGINOUT.EXE as
the image name.
input
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Equivalence name to be associated with the logical name SYS$INPUT
in the logical name table of the created process. The input
argument is the address of a character string descriptor pointing
to the equivalence name string.
output
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Equivalence name to be associated with the logical name
SYS$OUTPUT in the logical name table of the created process. The
output argument is the address of a character string descriptor
pointing to the equivalence name string.
error
OpenVMS usage:logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Equivalence name to be associated with the logical name SYS$ERROR
in the logical name table of the created process. The error
argument is the address of a character string descriptor pointing
to the equivalence name string.
Note that the error argument is ignored if the image argument
specifies SYS$SYSTEM:LOGINOUT.EXE; in this case, SYS$ERROR has
the same equivalence name as SYS$OUTPUT.
prvadr
OpenVMS usage:mask_privileges
type: quadword (unsigned)
access: read only
mechanism: by reference
Privileges to be given to the created process. The prvadr
argument is the address of a quadword bit mask wherein each bit
corresponds to a privilege; setting a bit gives the privilege. If
the prvadr argument is not specified, the current privileges are
used.
Each bit has a symbolic name; the $PRVDEF macro defines these
names. You form the bit mask by specifying the symbolic name of
each desired privilege in a logical OR operation.
Refer to the OpenVMS System Services Reference Manual to view
the table containing the symbolic name and description of each
privilege.
You need the user privilege SETPRV to grant a process any
privileges other than your own. If the caller does not have this
privilege, the mask is minimized with the current privileges of
the creating process; any privileges the creating process does
not have are not granted, but no error status code is returned.
quota
OpenVMS usage:item_quota_list
type: longword (unsigned)
access: read only
mechanism: by reference
Process quotas to be established for the created process. These
quotas limit the created process's use of system resources. The
quota argument is the address of a list of quota descriptors,
where each quota descriptor consists of a 1-byte quota name
followed by a longword that specifies the desired value for
that quota. The list of quota descriptors is terminated by the
symbolic name PQL$_LISTEND.
If you do not specify the quota argument or specify it as 0, the
operating system supplies a default value for each quota.
Refer to the OpenVMS System Services Reference Manual to
view MACRO and C examples, individual quota descriptions, and
instructions for use of the quota list.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Process name to be assigned to the created process. The prcnam
argument is the address of a character string descriptor pointing
to a process name string.
If a subprocess is being created, the process name is implicitly
qualified by the UIC group number of the creating process. If a
detached process is being created, the process name is qualified
by the group number specified in the uic argument.
baspri
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Base priority to be assigned to the created process. The baspri
argument is a longword value.
The OpenVMS VAX range is 0 to 31, where 31 is the highest
priority and 0 is the lowest. Usual priorities are in the range 0
to 15, and real-time priorities are in the range 16 to 31.
The OpenVMS Alpha range is 0 to 63, with real-time priorities in
the range 32 to 63.
If you want a created process to have a higher priority than its
creating process, you must have ALTPRI privilege to raise the
priority level. If the caller does not have this privilege, the
specified base priority is compared with the caller's priority
and the lower of the two values is used.
A process with ALTPRI privilege running on a VAX node can create
a process with a priority greater than 31 on an Alpha node.
If the baspri argument is not specified, the priority defaults
to 2 for VAX MACRO and VAX BLISS-32 and to 0 for all other
languages.
uic
OpenVMS usage:uic
type: longword (unsigned)
access: read only
mechanism: by value
User identification code (UIC) to be assigned to the created
process. The uic argument is a longword value containing the UIC.
If you do not specify the uic argument or specify it as 0 (the
default), $CREPRC creates a process and assigns it the UIC of the
creating process.
If you specify a nonzero value for the uic argument, $CREPRC
creates a detached process. This value is interpreted as a 32-bit
octal number, with two 16-bit fields:
bits 0-15-member number
bits 16-31-group number
You need IMPERSONATE or CMKRNL privilege to create a detached
process with a UIC that is different from the UIC of the creating
process.
If the image argument specifies the SYS$SYSTEM:LOGINOUT.EXE,
the UIC of the created process will be the UIC of the caller of
$CREPRC, and the UIC parameter is ignored.
mbxunt
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Unit number of a mailbox to receive a termination message when
the created process is deleted. The mbxunt argument is a word
containing this number.
If you do not specify the mbxunt argument or specify it as 0 (the
default), the operating system sends no termination message when
it deletes the process.
The Get Device/Volume Information ($GETDVI) service can be used
to obtain the unit number of the mailbox.
If you specify the mbxunt argument, the mailbox is used when
the created process actually terminates. At that time, the
$ASSIGN service is issued for the mailbox in the context of the
terminating process and an accounting message is sent to the
mailbox. If the mailbox no longer exists, cannot be assigned,
or is full, the error is treated as if no mailbox had been
specified.
If you specify this argument when you create a process on another
node, an accounting message will be written to the mailbox when
the process terminates. If the node is removed from the cluster
before the created process terminates, an accounting message
will be simulated. The simulated message will contain the created
process's PID and name and a final status of SS$_NODELEAVE, but
will lack execution statistics.
Note that two processes on different nodes cannot use the
termination mailbox for general interprocess communication.
The accounting message is sent before process rundown is
initiated but after the process name has been set to null. Thus,
a significant interval of time can occur between the sending of
the accounting message and the final deletion of the process.
To receive the accounting message, the caller must issue a read
to the mailbox. When the I/O completes, the second longword of
the I/O status block, if one is specified, contains the process
identification of the deleted process.
The $ACCDEF macro defines symbolic names for offsets of fields
within the accounting message.
Refer to the OpenVMS System Services Reference Manual to view
the table describing the offsets, their symbolic names, and the
contents of each field.
stsflg
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Options selected for the created process. The stsflg argument
is a longword bit vector wherein a bit corresponds to an option.
Only bits 0 to 22 are used; the others are reserved and must be
0.
Each option (bit) has a symbolic name, which the $PRCDEF macro
defines. You construct the stsflg argument by performing a
logical OR operation using the symbolic names of each desired
option.
Refer to the OpenVMS System Services Reference Manual to view the
table describing the symbolic name of each option.
itmlst
OpenVMS usage:reserved
type: longword (unsigned)
access:
mechanism: 0
The itmlst argument is reserved by Compaq.
node
OpenVMS usage:SCS_nodename
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the OpenVMS Cluster node on which the process is to be
created. The node argument is the address of a character string
descriptor pointing to a 1- to 6-character SCS node name string.
If the argument is present but zero or if the string is zero
length, the process is created on the current node.
home_rad
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Sets the home resource affinity domain (RAD) of a process.
The home RAD is determined by the operating system, unless you
explicitly request one. If bit PRC$M_HOME_RAD in the stsflg is
set, home_rad is the RAD on which the process is to start. Note
that you may set this bit to 0 on non-RAD systems.
Note: OpenVMS support for RADs is available only on the new
AlphaServer GS series systems. For more information about using
RADs, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
|
|
