HP 3000 Manuals HP 3000 Manuals
RUN
Executes a prepared or linked program. (Native Mode)
Syntax
The only required parameter is progfile. If you specify any other
parameters, they will override the default parameters that the creator of
the program established, but only for that particular execution of the
program. If run is implied, see operation note below.
RUN progfile[,["]entrypoint["]] [;NOPRIV][;LMAP][;DEBUG][;MAXDATA=maxstack]
[;PARM=parameternum][;STACK=stacksize][;DL=dlsize]
[;NMSTACK=nmstacksize][;NMHEAP=nmheapsize]
[ {G}]
[;LIB= {P}][;XL="library[,...]"] [;NOCB][;INFO="quotedstring"]
[ {S}]
[ [{*formaldesig}]]
[;UNSAT=["]unsatproc["]][;STDIN=[{fileref }]]
[ [{$NULL }]]
[ [{*formaldesig }]][ {BS} ]
[;STDLIST=[{fileref [,NEW]}]][;PRI= {CS} {#}]
[ [{$NULL }]][ {DS} ]
[ {ES} ]
Parameters
progfile The name of the program file to be executed. If
the name is not fully qualified, it is given a full
qualification consistent with the current job
domain. The file may be redirected with a file
equation.
entrypoint Program entry point where execution is to begin.
It contains a character string specifying the entry
point (label) in the program where execution is to
begin when the program is executed. This point may
be the primary entry point of the program, or any
secondary entry point in the program's outer block.
Default is the primary entry point.
By default, MPE/iX shifts all alphabetic characters
in entrypoint to uppercase; surrounding the
parameter with quotation marks (" or ') prevents
MPE/iX from performing the upshift and permits you
to enter strings for case-sensitive applications.
NOPRIV Specifies that the pages of the code space of the
program are to be assigned execution level 3 (the
least-privileged execution level), regardless of
the declared execution level. The execution level
of pages in a library are not affected by the
NOPRIV parameter. The default is that code in the
program executes at its declared execution level.
LMAP Indicates that the user wants a listing of the
process describing the spaces occupied by the
process and by the links created to bind the
external references of the process. The load map
is written to the loader list device. The default
is not to print a load map. Load maps for
compatibility mode and native mode are
significantly different from each other.
Native Mode
The load map for a native mode program or library is a listing that
describes the spaces loaded for a process and the linkages used to
connect the external references of the process. When the lmap option is
selected at run time, the listing is produced for the program and for
each library specified by the user.
The load map is organized into two major areas: the SOM's Description
area, with one per loaded SOM, and the Process Data Dictionary area.
Each SOM Description Area has six sections:
* The name section.
* The locality name section.
* The export code symbols section.
* The import code symbols section.
* The export data symbols section.
* The import data symbols section.
The above description is true for the program file and all user-supplied
library files, but not for the subsystem library XL.PUB.SYS. The SOMs
loaded from the subsystem library are now displayed in the load map.
However, only the name section is written except for subsystem SOMs that
have Shared Globals, in which case the export and import data symbols
sections are written to the load map.
SOM Description area
Name Section.
NM Program File : REALP.CMARTCLE.CICSNM
Module Name : REALS
FSN : 0
SOM : 0
LP : 240.40100000
DP : 240.41635000
Shared Data : YES
The first line of the load map from the name section displays the type of
the file (program or library) and the full name of the file. The title
is followed by the module name of the loaded SOM. The next grouping of
items is the File Sequence Number (FSN) and the SOM number. The FSN is
the number given the file according to its location in the ordered list
of files presented to the loader. Starting with the number zero, which
is assigned the program file, each user library is given the next number
as it is encountered in the binding sequence. SOMs are numbered
according to their position in the library file. This value is given by
the Link Editor and read by the Loader.
The FSN and SOM number are useful when using the Process Data Dictionary
area of the load map. They identify the file and SOM to which the data
export belongs.
The next grouping is the LP and DP. The LP is the pointer to the Cross
Reference Table (XRT), which contains the plabels for external procedure
calls for this module. The DP is the pointer to the Static Global Data
area for this module. The notation used for an address has the form:
sid.offset.
The sid (space ID) is the 32-bit virtual space number that was assigned
for that space when it was loaded. The offset is the byte offset within
the space relative to its beginning.
The next grouping shows the condition of the shared global flag for this
module. This information is only shown if the flag is set true.
Locality Name Section
Locality Name Type Address Length XL|R/W
------------- ---- ------- ------ ------
$LIT$ Code 2C5.5000 348 3
$UNWIND_START$ Code 2C5.5348 74 3
$DXRT$ Data 240.41634000 1000 3/0
$GLOBAL$ Data 240.41635000 E8 3/3
The name section is followed by the section that describes the spaces
declared with the module.
The new subspace is the $DXRT$, which is the Data Cross Reference Table.
Its address points to the bottom of the DXRT. Entry into the DXRT is
negatively offset from the beginning of the Static Global area, which is
the address of the $GLOBAL$ subspace.
The valid types for subspace are: Code, Data and Common. The length
column is the number of bytes in hexadecimal format. The last column is
read in two ways: for Code subspaces, it is the execution level; for
Data subspace, it is R-read access, W-write access.
Export Code Symbols Section
Entry Name Type Proc Addr Stub Addr XL/EL
---------- ---- --------- --------- -----
$START$ PProg 2C5.5014 3/3
main Entry 2C5.50BC 2C5.5050 3/3
The valid types for export code symbols are:
Entry Any code entry point. Includes both primary and
secondary entry points that may be used as targets
of r-space calls.
PProg Primary program entry point.
SProg Secondary Program entry point.
The procedure address (Proc Addr) column gives the starting address of
the procedure. The stub address (Stub Addr) column gives the (inbound)
external call stub. The last column is interpreted as follows:
XL-execution level and/or EL-the call execution level.
Import Code Symbols Section
External Name Type XRT Stub Addr
------------- ---- --- ---------
printf Stub 4 2C5.506C
proca Stub 3 2C5.509C
.
.
__exit Stub A 2C5.5294
The valid types for import code symbols are:
Stub This symbol marks an import (outbound). The Link
Editor creates an import stub for the unsatisfied
code symbols, and the Loader satisfies the
reference by filling in the XRT entry allocated for
this stub.
Plabl This symbol defines an export stub for a procedure
for which a procedure label has been generated.
The Loader builds an XRT entry for the procedure at
the offset allocated by the Link Editor.
The XRT column specifies the entry in the XRT through which the contents
of a plabel can be located. Each entry is 32 bytes. The stub address
(Stub Addr) column is the outbound stub address. This stub accesses the
XRT for the targeted export.
Export Data Symbols Section
Symbol Name Select Type Scope Size DP Addr R/W
----------- ------ ---- ----- ---- ------- ---
a YES Stor Univ 8 240.416350E0 3/3
b YES Data Univ n/a 240.41635000 3/3
The Select column indicates whether this particular export was the one
chosen by the Loader to place in the PDD.
The valid types for export data symbols are:
Data Normal initialized data. Example (a C construct):
double b = 3.3;
Stor Storage. This symbol requests a data storage
location of a certain size.
The scope column is always Univ-universal.
The Size column shows the number of bytes in decimal format required for
the export symbol. Space is allocated for four (4) characters only. To
accommodate numbers greater than 9999 bytes, the format changes to 10k up
to 999k (999 kilobytes). The next range is 1.0m up to 9.9m (9.9
megabytes), followed by 10m to 999m (999 megabytes), and finally, 1.0g to
4.2g (4.2 gigabytes). Size information is only available for storage
request types. There is no size information available for initialized
data, that is, data universals.
The DP Addr column contains the actual virtual address of the symbol,
provided the Select column is YES.
The last column gives the access rights for the symbol.
Import Data Symbols Section
IMPORTED DATA SYMBOLS .....
Symbol Name Type Scope DXRT DXRT Addr R/W
----------- ---- ----- ---- --------- ---
c Data Unsat -C 240.41634FE4 3/3
d Data Unsat -14 240.41634FEC 3/3
__ANSI_MODE Data Unsat -18 240.41634FE8 3/3
a Data Unsat -10 240.41634FF0 3/3
The valid type for import data symbols is:
Data Requested import data item. Example (a C
construct): extern double c
The scope column is always Unsat--Import request has not been satisfied.
A DXRT entry is indexed negatively from the DP of the SOM. The DXRT
column gives this offset, which is in bytes. The value is in hexadecimal
format. The DXRT Addr column gives the indirect address for the import
symbol.
The last column gives the access rights for the symbol.
Process Data Dictionary Area
|||||||||||||||||||||||||||||||||||||||||||||||||||||
||| |||
||| PROCESS DATA DICTIONARY |||
||| SHARED GLOBALS DATA EXPORTS |||
||| |||
|||||||||||||||||||||||||||||||||||||||||||||||||||||
Symbol Name FSN SOM Type Scope Size DP Addr R/W
----------- --- --- ---- ---- ---- ------- ---
a 0 0 Stor Univ 8 240.416350E0 3/3
b 0 0 Data Univ n/a 240.41635000 3/3
d 1 0 Stor Univ 8 240.416370A8 3/3
c 1 0 Data Univ n/a 240.41637000 3/3
.
.
__ANSI_MODE 2 0 Stor Univ 4 240.41641894 3/3
.
.
The FSN (File Sequence Number) and the SOM columns can lead you to the
file and SOM, which supplied the export data symbol. For example, the
_ANSI_MODE symbol comes from the subsystem library in the binding
sequence, which would be XL.PUB.SYS, and the first SOM (SOM 0) with
module name hp30026_01. Shown below are some lines from the SOM
Description Area of the load map for the subsystem library.
NM Library File : XL.PUB.SYS
Module Name : hp30026_01
FSN : 2
SOM : 0
LP : 240.401001A0
DP : 240.41639000
Shared Data : YES
EXPORTED DATA SYMBOLS .....
Symbol Name Select Type Scope Size DP Addr R/W
----------- ------ ---- ----- ---- ------- ---
.
.
__ANSI_MODE YES Stor Univ 4 240.41641894 3/3
.
.
Continuing with the PDD area, the remaining columns starting with Type
through R/W are interpreted in the same manner as explained in the Export
Data Section.
Compatibility Mode
A compatibility mode loader map shows information on the origin and
destination of the reference. The exact origin or destination is
identified by the file type, the segment within the file, and by the STT
entry of the segment. The level of parameter checking is also listed.
For example:
PROGRAM FILE SAMPLE.LOADER.MPEXL
TERMINATE PROG 0 4 0 SSL 0 2 41
GETUSERMODE PROG 0 3 0 SSL 0 13 44
GETPRIVMODE PROG 0 2 0 SSL 0 14 44
301
The first entry reading across lists the name. The next four entries
show the information for the reference origin. The last four show the
information for the reference destination:
Reference Origin Reference Destination
F T L S S F T L S S
i y C T e i y C T e
l p T g l p T g
e e e e
TERMINATE PROG 0 4 0 SSL 0 2 41
GETUSERMODE PROG 0 3 0 SSL 0 13 44
GETPRIVMODE PROG 0 2 0 SSL 0 14 44
301
The file types are:
PROG Compatibility mode program file
SSL SL.PUB.SYS
PSL SL.PUB.account
GSL SL.group.account
LC (Level of file checking):
0 No checking
1 Check procedure type
2 Check number of parameters
3 Check parameter type
STT is the segment transfer table entry within the segment.
Seg is the logical segment number of the segment.
A list of the CSTX numbers (the single number 301 in this example)
assigned to the segments of the program follows the load map. The first
number in the list corresponds to logical Seg 0, the second to logical
Seg 1, and so on.
DEBUG Instructs the process to enter the system debugger
just before executing the first instruction of the
program. Once the debugger has been invoked, the
commands available to the user depend upon the
user's assigned capability. The default is not to
enter the system debugger. This parameter is
ignored in a job.
maxstack The maximum CM stack area (Z-DL) size permitted, in
16-bit words. This parameter is included if you
expect the size of the DL or the Z-DB areas to be
changed during the program execution. But no
matter what you specify, MPE/iX may change maxstack
to accommodate table overflow conditions.
A value of -1 or a + sign (interpreted as a zero)
causes the default value to be used.
The maxstack is always equal to the compatibility
mode maximum default size if progfile is a native
mode program.
parameternum A value that can be passed to the program as a
general parameter for control or other purposes.
If the parameter is not specified, the default
value is zero (0). If the executing program is a
compatibility mode program, Q(initial)-4 contains
the parameter value. Note: Q relative addresses
are 16-bit word addresses. Q(initial) is the Q
address for the outer block of the program.
MPE/iX provides an intrinsic (GETINFO) for
retrieving the PARM parameter for a native mode
process.
stacksize The size of the CM local area, Z-Q, in 16-bit
words. This value, if specified, must be in the
range 512 to 32,767. It overrides the default
stack size estimated by the MPE segmenter.
The stacksize is always equal to the compatibility
mode maximum default size if progfile is a native
mode program.
dlsize The DL-DB area to be assigned initially to the CM
stack. To accommodate system logging requirements,
this area is always rounded upward in such a way
that the distance from the beginning of the stack
data segment to the DB address is a multiple of 128
16-bit words.
This value must be in the range -1 to 32,767. The
default (which is used when no value or an invalid
value is specified) is estimated by the MPE
segmenter. A + sign for this parameter is
interpreted as a zero.
The dlsize is always equal to the compatibility
mode maximum default size if progfile is a native
mode program.
nmstacksize The maximum size in bytes to which the NM stack may
grow. This must be a decimal number. If a value
is specified which is less than the system-defined
minimum (including values <= 0), the system-defined
value will be used. If a value is specified which
is greater than the system-defined maximum value,
the system-defined maximum value will be used. A +
sign for this parameter is interpreted as a zero.
The default is -1, which currently instructs MPE/iX
to assign a system-defined constant as the value of
nmstacksize.
nmheapsize The maximum size, in bytes, to which the NM heap
may grow. This must be a decimal number. If a
value is specified which is less than the
system-defined minimum (including values <= 0), the
system-defined value will be used. If a value is
specified which is greater than the system-defined
maximum value, the system-defined maximum value
will be used.
The default is -1, which currently instructs the
command to assign a system-defined constant as the
value of nmheapsize. A + sign for this parameter
is interpreted as a zero.
G, P, or S These parameters provide an efficient way to
specify the executable libraries that may be used
to load the program.
G The program's group library
is searched first, then its
public account library is
searched, and finally the
system library is searched to
resolve the program's
external references.
P The program's public account
library is searched before
the system library is
searched to resolve the
program external references.
S Only the system library is
used to bind the external
references of the program.
This is the default.
These parameters will result in a fail load if
progfile contains a program name which cannot be
expressed using the MPE syntax.
The group and account libraries referenced by this
parameter must be named SL.group.account for
compatibility mode programs and XL.group.account
for native mode programs. Group and account are
the group and account of the program, where the
program resides.
If the LIB and XL parameters are missing, this
parameter defaults to S. This parameter may not be
used at the same time as the XL parameter.
"library" Specifies the library or libraries to be searched,
and the order in which they are searched to resolve
any external references. This parameter is
available only for native mode load operations. It
may not be used at the same time as the LIB
parameter. It must be delimited by a matching pair
of quotation marks (either " or '). Compatibility
mode ignores this parameter if it is specified. In
native mode, this parameter overrides LIB= if both
are specified.
If any library name in the list is not fully
qualified, it will be qualified with a name
consistent with the program file being loaded.
Library names, except those in the system library,
may be redirected with a file equation.
A default value for this parameter may be stored in
the program file. The default is used only if the
LIB and XL parameters are both omitted.
In a list of libraries, each library must have a
privilege level equal to or greater than the
privilege level of the library that precedes it in
the list. The privilege level of any file is
governed by the privilege level of the group in
which it resides. For example,
RUN PROGA.grp.acct;XL='LIB1.PUB.TOOLS,LIB2.DIAG.SYS'
Suppose the group grp does not have privileged mode
(PM) capability. We assume for this example that
the user is able to execute PROGA.grp.acct.
Suppose also that PUB.TOOLS does have PM
capability, but that DIAG.SYS does not.
The program PROGA.grp.acct is able to load
PUB.TOOLS. But PUB.TOOLS has PM capability.
Therefore everything following it in the list must
have PM capability, too. Since DIAG.SYS does not,
the library search ends without loading
LIB2.DIAG.SYS.
This prevents non-PM processes from "piggybacking"
on legitimate PM processes.
NOTE XL.PUB.SYS and NL.PUB.SYS, which are two of the three system
libraries for MPE/iX, are searched automatically. The user does
not need to specify them.
If you do specify one or both, place them at the end of your list
of libraries. Otherwise, MPE/iX detects an error.
If you specify NL.PUB.SYS but not XL.PUB.SYS, only NL.PUB.SYS is
searched. XL.PUB.SYS is ignored in this particular case. However,
if you specify XL.PUB.SYS but not NL.PUB.SYS, both are searched
despite the omission of NL.PUB.SYS.
An absolute pathname must be used when a library name is specified
in HFS syntax. In addition, if progfile contains a name which can
only be expressed in the HFS syntax, the file names specified in
this item must be fully qualified.
To have an XL in the HFS, you must copy it from the MPE group to
the HFS directory.
NOCB Instructs the file system not to use the stack
segment, PCBX, for its control blocks, even if
sufficient space is available. This allows for
expansion of the stack, using the DLSIZE and ZSIZE
intrinsics, to the maximum possible limit at a
later time.
NOCB affects only those programs that use the following types of file:
MSG, RIO, and CIR. Programs using other types of files ignore the NOCB
parameter.
Be aware, that NOCB causes the file management
system to operate more slowly.
quotedstring Allows the user to pass an ASCII string to the
program that is to be run. The string must be
delimited by a matching pair of quotation marks
(either " or '). If you want a quotation mark to
appear within the string, you may double it, as
with most programming languages: can't must appear
as can''t, " and " must appear as ""and"", 'but'
must appear as ''but''. The maximum length of the
string, including delimiters, is 255 characters.
Refer to "Examples."
If the executing program is a compatibility mode
program, Q(initial)-5 contains a byte pointer to
the string, and Q(initial)-6 contains the number of
characters in the string. The Q-relative addresses
are 16-bit addresses. Q(initial) is the Q address
for the outer block of the program. Default is
that no string is passed, and the length of the
string is set to zero.
MPE/iX provides an intrinsic (GETINFO) for
retrieving the quotedstring for a native mode or
compatibility mode process.
unsatproc Specifies the (fall-through) procedure that is
linked in the event that any of the external
references cannot be resolved to one of the
libraries available to the process. This is
available only when loading a native mode program.
It is ignored when loading a compatibility mode
program. By default, MPE/iX shifts all alphabetic
characters in unsatproc to uppercase; surrounding
the parameter with quotation marks (" or ' )
prevents MPE/iX from performing the upshift and
permits you to enter strings for case sensitive
applications.
For instance:
;UNSAT = terminate
The procedure TERMINATE is linked if one of the
external references cannot be resolved to one of
the available libraries. Because the value
terminate is not delimited by quotation marks ( "
or ' ), the value is upshifted to TERMINATE.
;UNSAT = "foo"
;UNSAT = 'foo'
Here the procedure foo is linked if one of the
external references cannot be resolved to one of
the libraries. In both cases, delimiting the value
foo with quotation marks (" or ' ) causes MPE/iX to
use the value as given, in lowercase.
If the user does not supply an UNSAT procedure and
a process cannot be fully bound, the load fails.
An UNSAT procedure must reside in an XL. The UNSAT
procedure cannot be placed in an NMOBJ file and
linked with the rest of the program.
STDIN Specifies the file to be used as $STDIN by the
program being executed. If this parameter is
omitted, or if nothing is specified after the equal
sign, as in ;STDIN=Return, STDIN defaults to the
standard input device for the job or session.
*formaldesig The formal file designator for a file previously
specified in a file equation.
fileref The name of an existing permanent or temporary disk
file.
$NULL The actual file designator of a system-defined file
that is always treated as an empty file. When
referenced by another program, a program receives
only an end-of-file indication when accessed. When
referenced by a program as $STDLIST, the associated
write request is accepted by MPE/iX, but no
physical output is actually performed. Thus, $NULL
can be used to discard unneeded output from an
executing program.
PRI The execution priority that the command interpreter
uses for your program. BS has the highest
priority; ES has the lowest priority.
DS and ES are intended for batch jobs and are not
well-suited for interactive applications.
Specifying a positive integer (#) permits you to
set priority at points that lie between the preset
priority levels BS, CS, DS, and ES. Accepted values
for # are in the range 100 to 255, inclusive.
Refer to the CREATEPROCESS intrinsic in the MPE/iX
Intrinsics Reference Manual (32650-90028).
If you are in user mode (that is, nonprivileged)
you may specify BS, CS, DS, or ES.
If you attempt to specify a priority higher than
the priority permitted for your account or user
name, MPE/iX sets the highest priority below BS.
The default is CS. If you do not specify a value
the default (the parent process's dispatching
subqueue priority) is used.
CAUTION Use care in assigning the BS queue. Processes at the BS
priority can lock out other processes.
STDLIST Allows the user to specify the file to be used as
$STDLIST by the program being executed. If this
parameter is omitted, or if nothing is specified
after the equal sign, as in ;STDLIST=Return, then
STDLIST defaults to the standard list device for
the job or session. This parameter has the same
subparameters as STDIN, but you may also
specify the keyword NEW (for instance,
";STDLIST=filename,NEW").
NEW The name to be assigned to a job/session temporary
disk file consisting of 132-byte fixed ASCII
records.
Operation Notes
This command executes a program prepared in a program file. It permits
searching libraries (SLs for compatibility mode, XLs for native mode) to
satisfy external references. Relocatable libraries (RL) are not
searched.
If the volume set containing the file to be run is not mounted, this
command implicitly causes that volume set to be mounted. The volume set
has to be opened with a VSOPEN command.
If the program file is a temporary CM file, the logon group and account
libraries for the current session along with SL.PUB.SYS are searched. If
a program file is a temporary NM file XL.PUB.SYS and NL.PUB.SYS are also
searched. Refer to the Accessing Files Programmer's Guide (32650-60010)
for more information on file domains.
NOTE NM and CM loader error messages are reported differently, allowing
you to determine the system in which the error occurred.
NM Loader Error: !!ErrMessage!! (LDRERR nnnn)''
CM Loader Error: !!ErrMessage!! (LOAD ERR nnnn)''
The RUN command is parsed by the Compatibility Mode parser unless it is
implied, in which case the Native Mode parser is used. To use the
implied version of RUN simply omit the word run and enter the name of the
program along with either the INFO or PARM parameters.
Because the Native Mode parser is used with implied run you can use
quotes (" or ') with the program file name and/or the ;INFO= parameter.
Also, quotes are not required if the parameter contains no delimiter
characters such as a blank, comma, semicolon, quotemarks or equal sign.
In addition, the ;INFO string can be up to 280 characters long and the
;PARM= value can be any signed 31 bit number. Without implied RUN the
;INFO limit is 255 characters and the ;PARM= value is limited to a signed
15 bit decimal or unsigned 16 bit octal or hex value.
NOTE Programs whose name cannot be expressed using MPE syntax are not
allowed to have PM, MR or DS capability. Programs linked with
these capabilities cannot be loaded.
Users must have PM capability to load programs whose name cannot be
expressed using MPE syntax, with PM capability.
CM programs cannot be loaded from the HFS directory.
Use
This command may be issued from a session or a job. It may not be issued
in BREAK or from a program, unless the user or the calling program has PH
capability. Pressing Break suspends the execution of this command.
Entering the RESUME command continues the execution.
Examples
To list the references of a loaded program, enter:
RUN XLAB;LMAP
To run a program stored in the program file PROG4, beginning at the entry
point SECLAB, enter:
RUN PROG4,SECLAB
The following example runs a program TESTPROG with $STDIN set to an old
disk file named INPUT and $STDLIST set to the line printer:
FILE LPFILE;DEV=LP
RUN TESTPROG; STDIN=INPUT;&
STDLIST=*LPFILE
The next example runs a program using the STDIN parameter, setting $STDIN
to an existing disk file named INPUT, this time referenced through a file
equation. To set $STDLIST to a temporary disk file named RESULTS that is
automatically created by the RUN command, enter:
FILE INFILE=INPUT,OLD
RUN TESTPROG;DEBUG;STDIN=*INFILE;STDLIST=RESULTS,NEW
The following example of the RUN command uses the INFO= parameter to pass
a string to the program:
RUN MYPROG;INFO= "A TEST WITH ""AND""&
CHARACTERS"
In quotedstring, "AND" is bounded by an extra pair of quotation marks.
As a result, the string passed to the program is:
A TEST WITH "AND" CHARACTERS
Related Information
Commands LINK, PREP, XEQ, VERSION Utility
Manuals CREATEPROCESS intrinsic in the MPE/iX Intrinsics Reference
Manual (32650-90028)