 |
» |
|
|
|
Creates and activates a process and, if necessary, creates
a remote session for that process to run in. Process Handling (PH)
capability is required. Syntax | |
RPMCREATE (progname,namelen [,location][,loclen][,login][,loginlen] [,password][,passwdlen][,flags][,opt][,pd][,result]) |
Parameters | |
- progname
(input)
Character array, by reference.
The name of the program for which a process is to be created. - namelen (input)
32-bit integer, by value.
The length in bytes of the program name. - location (input)
Character array, by reference.
The node name or environment ID indicating where the process should
be created. - loclen (input)
32-bit integer, by value.
The length in bytes of the location name. - login (input)
Character array, by reference. A logon sequence
for the local or remote node on which the process is to be created,
in the form [session,]user.acct[,group]. - loginlen (input)
32-bit integer, by value.
The length in bytes of the logon sequence. - password (input)
Character array, by reference.
Password(s) to be used with the logon sequence, in the form [userpass][,acctpass][,grouppass]. - passwdlen (input)
32-bit integer, by value. The
length in bytes of the password parameter. - flags (input)
32 bits, by reference. A
bit representation of various options. The following flags are defined: flags [0]
(input). Indicates that all environment information given in a prior
DSLINE command (for the remote environment in
question) should be ignored when the new process is created. For
example, if this flag is on, a logon sequence provided in the LOGON
option of a DSLINE command will not override
the logon given in this RPMCREATE
call. flags [1]
(input). Causes the calling process to wait in this intrinsic call
until the new process terminates. (The RPMCREATE
call will complete only after the new process finishes executing.) flags [2]
(input). Causes RPM to create a process using RPM protocols from
HP's software release UB Delta 1 or earlier. In software
release UB Delta 1 or earlier, RPM flags 3 and 30 are not supported. flags [3]
(input). Causes RPMCREATE to fail
if the remote node has a version of RPM installed that is from HP's
software release UB Delta 1 or earlier. By default, if the remote
node does not have the newer RPM installed, RPMCREATE
will act as if flags [2]
is set and conform to the older format. flags (input). Causes
the remote node to create the process into a session that may accommodate
multiple RPM created processes. By default RPMCREATE
will only create one remote process per remote session. flags [31]
(input). Makes the created process dependent on the creator. When
the creator process dies, the created process will be killed. (If
this bit is off, the created process will continue executing on
its own.) Default: off; created process is independent of its creator.
- opt
Record or byte array, by reference.
A list of options, with associated information. The following options
are defined: RPM string (option code 20000, n-byte
array). Permits information to be sent to the created process in
the data portion of the opt parameter, such as a socket name. More
than one RPM string can be included. The strings may be retrieved
by the new process (using RPMGETSTRING)
in the same order that they occur in the opt
parameter. Entry point (code 22001, n-byte
array). The data portion of this parameter contains a string, terminated
by a blank, specifying the entry point (label) in the program where
execution is to begin when the process is activated. A blank by
itself indicates the primary entry point. This parameter corresponds
to item number 1 of the MPE/iX CREATEPROCESS
intrinsic. The contents of this option parameter should conform
to the value of the item parameter in
the CREATEPROCESS intrinsic. Default:
primary entry point. Program parameter (code 22002, 2-byte integer).
The data portion of this parameter contains an integer value used
to transfer control information to the new process. The word will
be accessible on the stack of the new process at location Q-4. This
parameter corresponds to item number 2 of the MPE/iX CREATEPROCESS
intrinsic. The contents of this option parameter should conform
to the value of the item parameter in the CREATEPROCESS
intrinsic. Create flags (code 22003, 2-byte bit map). The data
portion of this parameter contains a word whose bits specify loading
options, as follows. (Bit 15 is the least significant bit, bit 0
the most significant bit.) This parameter corresponds to item number
3 of the MPE/iX CREATEPROCESS intrinsic.
The contents of this option parameter should conform to the value
of the item parameter in the CREATEPROCESS
intrinsic. bit 15 — Ignored; should
be off. bit 14 — LOADMAP
bit. If on, a listing of the newly allocated program is produced
on the job/session listing device. This map shows the Code Segment
Table (CST) entries used by the new process. Default: off bit 13 — DEBUG
bit. If on, DEBUG is called at
the first executable instruction of the new program. You must have
read/write access to the program file of the new process. If the
new process requires privileged mode, you must be a privileged user.
Default: off. bit 12 — NOPRIV
bit. If on, the slave program is loaded in non-privileged mode.
If this bit is off, the program is loaded in the mode specified
when the program file was prepared. Default: off. bits 10 and 11 — LIBSEARCH
bits. A coded bit pattern that denotes the order in which libraries
are to be searched for the program. The default is 00: 00 = System Library only. 01 = Account Public Library, then System
Library. 10 = Group Library, then Account Public
Library, then System Library. bit 9 — NOCB
bit. If on, file system control blocks are established in an extra
segment. If off, control blocks may be established in the Process
Control Block Extension (PCBX) area. Default: off. This bit should
be set on if the new process uses a large stack. bits 7 and 8 — reserved for MPE; should
be off (00). bits 5 and 6 — STACKDUMP
bits. A coded bit pattern that controls the enabling/disabling of
stack dumping in the event of a program abort. The default is 00: 00 = enable stack dumping for new process
only if enabled at master level; 01 = enable stack dump unconditionally; 10 = same as 00; 11 = disable stack dump unconditionally. bit 4 — reserved for MPE; should be off. bits 0 to 3 — These four bits are used
only if the STACKDUMP bits are
01; otherwise they are ignored. Bits 1-3 represent portions
of the slave program's stack. If bit 3 is on, the portion
of the stack from DL to QI (Q-initial) is dumped; if off, this portion
is not dumped. If bit 2 is on, the portion of the stack from QI
to S is dumped. If bit 1 is on, the portion of the stack
from Q-63 to S is dumped. If bit 0 is on, the stack dump is interpreted
in ASCII characters in addition to octal values; if off, no ASCII
interpretation is performed. The default for each of these bits
is off.
The default conditions noted above take effect if the Create
flags option (flags) or the entire opt
parameter is omitted. Initial stack size (code 22004, 2-byte
integer). The data portion of this parameter contains an integer
(Z-Q) denoting the size, in words, of the local stack area
bounded by the initial Q and Z values. This parameter corresponds
to item number 4 of the MPE/iX CREATEPROCESS
intrinsic. The contents of this option parameter should conform to the
value of the item parameter in the CREATEPROCESS
intrinsic. Default: The value specified in the program file Initial dlsize (code 22005, 2-byte integer). The
data portion of this parameter contains an integer (DB-DL)
denoting the size, in words, of the user-managed stack area bounded
by the DL and DB values. This parameter corresponds to item number
5 of the MPE/iX CREATEPROCESS intrinsic.
The contents of this option parameter should conform to the value
of the item parameter in the CREATEPROCESS
intrinsic. Default: The value specified in the program file. Max stack size (code 22006, 2-byte integer). The
data portion of this parameter contains an integer (Z-DL)
denoting the maximum word size allowed for the process's
stack area (bounded by the DL and Z values). This parameter corresponds
to item number 6 of the MPE/iX CREATEPROCESS
intrinsic. The contents of this option parameter should conform
to the value of the item parameter in
the CREATEPROCESS intrinsic. Default:
The value specified in the program file or (if none is specified
there) the current stack size. Priority (code 22007, 2-byte array). The data portion
of this parameter contains a string of two ASCII characters (AS,
BS, CS, DS, or ES) indicating the priority class in which the new
process is scheduled. Default: The same priority as the calling
process. This parameter corresponds to item number 7 of the MPE/iX
CREATEPROCESS intrinsic. The contents
of this option parameter should conform to the value of the item
parameter in the CREATEPROCESS
intrinsic. $STDIN file name
(code 22008, n-byte array). The data
portion of this parameter contains the name of a file to which all
input requests to $STDIN will be
directed. This parameter corresponds to item number 8 of the MPE/iX
CREATEPROCESS intrinsic. The contents
of this option parameter should conform to the value of the item
parameter in the CREATEPROCESS
intrinsic. Default: With an interactive logon (HELLO,
REMOTE HELLO), input requests will
be directed to $STDIN. With the
logon option (either the LOGON=
parameter in a DSLINE command or the login
parameter of RPMCREATE), input
requests will be directed to the empty file $NULL. $STDLIST file name
(code 22009, n-byte array). The data
portion of this parameter contains the name of a file to which all
output requests to $STDLIST will
be directed. This parameter corresponds to item number 9 of the
MPE/iX CREATEPROCESS intrinsic.
The contents of this option parameter should conform to the value
of the item parameter in the CREATEPROCESS
intrinsic. Default: With an interactive logon (HELLO,
REMOTE HELLO), output requests
will be directed to $STDLIST.
With the logon option (either the LOGON=
parameter in a DSLINE command or the login
parameter of RPMCREATE), output
requests will be directed to the empty file $NULL. Info string (code 22011, n-byte
array). The data portion of this parameter contains an information
string that is passed to the new process. This string will be accessible
on the new process's stack at a byte address that is stored
at location Q-5. If this option is included, you must also include
the Info string length option (22012). This parameter corresponds
to item number 11 of the MPE/iX CREATEPROCESS
intrinsic. The contents of this option parameter should conform
to the value of the item parameter in
the CREATEPROCESS intrinsic. Info string length (code 22012, 2-byte integer).
The data portion of this parameter contains an integer specifying
the byte length of the info string given by the previous option.
The Info string length option must be included if the Info string
option is included. This parameter corresponds to item number 12
of the MPE/iX CREATEPROCESS intrinsic.
The contents of this option parameter should conform to the value
of the item parameter in the CREATEPROCESS
intrinsic. Logon timeout; real (code 22100, 4-byte real value).
The data portion of this parameter contains a real value representing
the number of seconds you are willing to wait for a remote logon,
performed by RPMCREATE, to complete.
If the remote session is not established during this time, you will
receive an error. Default: 120.0 seconds. Logon timeout; integer (code 22102, 4-byte integer).
This is the same as option 22100 except that the data portion of
this parameter contains an integer representing the number of milliseconds
that you are willing to wait for the remote logon, performed by
RPMCREATE to complete. If both
options are present in the opt array,
then the entry with the lowest array index will be the one selected.
- pd
(output)
16-byte array, by reference.
A program descriptor used to identify the created process. This
value, randomly generated, is presumed to be unique across all nodes.
A valid program descriptor is always a non-zero value. - result (output)
32-bit integer, by reference.
The error code returned; zero if no error.
Description | |
The RPMCREATE intrinsic enables
the calling process to create and activate another process —
that is, to initiate execution of another program. The new process
may be on a remote system. (RPM does not extend the process management
capabilities of a particular operating system, such as MPE, across
a network.) Normally, RPMCREATE allows
only one remote process per remote session. Bit 30 of the RPM flags
parameter allows multiple RPM remote processes in a remote session.
This session-sharing option of RPM is only available in HP's
software release UB delta 2 or later. The only required parameters
are progname, namelen,
location, and loclen.
(The intrinsic is option variable.) In order for multiple processes
to reside in a common remote session, three criteria must be satisfied: All the processes must have been created
with bit 30 of the flags parameter set.
Remote processes created without this bit set will not share sessions
with processes that do have it set. All the processes must have been created from processes
residing within the same session on the local node. Processes that
are running in different local sessions will RPMCREATE
remote processes into different remote sessions. All the processes must have the same logon string
including session name, if any. All the necessary passwords must
match.
The remote session may be any session that RPMCREATE
would normally use, including VT-created sessions, that is, sessions
created using the REMOTE HELLO command. The new process will run in an existing remote session (created
by REMOTE HELLO) if you specify
the appropriate environment ID in the location
parameter. A new session will be created on the remote node if one
does not already exist. RPM uses the logon sequence specified in
the login parameter (and the password
in password) unless (1) a logon is specified
in a prior DSLINE command for the remote environment
(in the LOGON option), and (2)
bit 0 of the flags parameter (the high-order
bit, which causes the DSLINE information
to be ignored) is off. In other words, the order of priority (from
high to low) is: existing session; DSLINE
logon; RPMCREATE logon. But the
"ignore DSLINE information"
flag forces the use of the RPMCREATE
logon instead of a DSLINE logon. If the new process is to be created on a remote node and the
login parameter is omitted, then
a remote session must already exist or logon information must be
given in a prior DSLINE command. For example,
let's say that a previous DSLINE command has
defined "S" as an environment ID for node FINANCE,
with logon USER.ACCT. Then an RPMCREATE
call giving "S" as the location and omitting the
login parameter will create a session
on FINANCE for USER.ACCT. Once an RPMCREATE call has
been made for a remote environment, you cannot issue remote commands
for that environment until the remote process has terminated (for
example, has been killed via RPMKILL).
If an independent RPM process has been left in the remote environment
after the process that created it has terminated, and you issue
a DSLINE ;CLOSE command for the remote environment,
you will first be asked whether you want to kill the remote RPM
process. If you kill the remote process and then do not abort the
remote session, you can subsequently issue commands in the remote
session. See "Releasing a Remote Environment"
in the "Virtual Terminal" chapter of this manual. RPMCREATE can also create
a new process on the local node. The new process will be created
in your local session if (1) the location
and login parameters are omitted or blank
or (2) location is the local node name
and login is the logon for your local
session (including session name, if any). A new process will also
be created on your local node, but in a different session, if (1)
you specify your local node name, and a logon different from your
own and (2) software loopback has been configured and activated
for your local node. Bit 31 (the low-order bit) of the flags
parameter determines whether the newly created process will be dependent
on its creator or independent (the default). A local dependent process
that was created under the same logon as its creator will terminate
automatically when the creator terminates. (In order to conserve
system resources, you should make local processes independent; that
is, set the bit off.) A remote dependent process will terminate if: RPMKILL
has been called for the dependent process. The creator process terminates before calling RPMKILL. The system on which the creator is running fails.
If the remote process is independent, it will continue to
execute unless explicitly terminated by RPMKILL.
Dependent mode ensures that the new process will not become an "orphan"
in the event of a program, system, or network link failure. However,
independent mode is less costly in terms of resources: the connection
set up for the RPMCREATE is not
maintained after the remote process is created. You should normally
use independent mode for processes that are expected to terminate
themselves. Preferred Method of Creating Interactive Programs | |
RPM works best to create non-interactive server programs on
a remote system. If you use RPM to create interactive programs,
some restrictions exist (described in a following section). Therefore,
as an alternative to using the RPMCREATE
intrinsic to create interactive programs, HP recommends that you
call the REMOTE RUN command from the COMMAND
intrinsic. Using this method will suspend the master process in
the COMMAND intrinsic while the
slave program runs. Only use RPMCREATE
if you require parallel execution of a master and slave process. Using $STDIN and $STDLIST in a Precreated VT Session | |
Beginning with MPE/iX release 2.2, remote RPM slave processes
can post interactive I/O to $STDIN
and $STDLIST through a precreated
VT session. This allows interactive I/O from remote programs to
appear on a local terminal. Before creating an RPM slave, use the REMOTE HELLO
command to create a remote session. After the session is established,
you can use the RPMCREATE command to create an
RPM son in the remote session. The location
parameter should contain the same environment name that was specified
in the REMOTE HELLO command. Do not specify the
login or loginlen
parameters, nor are the $STDIN/$STDLIST
options 22008/22009 required. Restrictions when Using RPMCREATE to Create Interactive
Programs | |
Because RPM was not designed to create interactive programs,
there are caveats you should be aware of before using RPM for your
application. Do not press the system BREAK or the subsystem
break [CTRL] Y while a remote application is running. Do not create an RPM slave in a VT session that is in break.
This will cause both the local and remote application to hang. Neither
the local or remote session can log off. Opt Parameter Format | |
The opt parameter, which denotes
various options, contains an integer code for each option along
with associated information. It is not necessary to know the internal
structure of this parameter to use it. The "opt
parameter manipulation intrinsics," INITOPT,
ADDOPT, and OPTOVERHEAD,
enable you to add option information without concerning yourself
with the parameter's structure. However, a knowledge of
the opt parameter's structure
can help you determine an appropriate size for the array. (The parameter
must be defined as a byte array or as a record structured in the
manner described below. If your program is written in a language
that supports dynamically allowed arrays, the OPTOVERHEAD
intrinsic may be used to determine the size of the array.) The opt parameter consists of these
fields: length, in bytes, of option entries
and data (2-byte integer); number of entries (2-byte integer); option entries (8 bytes per entry); data associated with the option entries (variable
length).
Each 8-byte option entry, in turn, consists of the following
fields: option code (2-byte integer); offset (relative to the base address of the opt
parameter) indicating the location of the data for this option entry
(2-byte integer); length, in bytes, of the data (2-byte integer);
If the parameter is declared as a simple byte array, it must
be large enough to contain 4 bytes for the first two fixed-length
fields, 8 bytes for each option entry, plus the actual data. That
is: 4 + 8 * numentries + datalength |
|
