Generated from C.60.01 /SYS/PUB/CICAT last modified on Thu Jan 11 09:18:52 2001
RUN
Executes a prepared or linked program. 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. (CM)
IMPLIED RUN Refer to the Commands Reference Manual
(32650-90003)
RUN progfile[,[ "]entrypoint[ "]]
[;NOPRIV]
[;LMAP] {*formaldesig}
[;DEBUG] [;STDIN=[{fileref }]
[;MAXDATA=maxstack] {$NULL }
[;PARM=parameternum]
[;STACK=stacksize] {*formaldesig }
[;DL=dlsize] [;STDLIST=[{fileref[,NEW]]}]
[;NMSTACK=nmstacksize] {$NULL }
[;NMHEAP=nmheapsize]
{BS}
{G} [;PRI={CS}{#}]
[;LIB={P}] {DS}
{S} {ES}
[;XL="library[, ...]"]
[;NOCB]
[;INFO=quotedstring]
[;UNSAT=[ "]unsatproc[ "]]
progfile The name of the program file to be executed. If the
name is not fully qualified, it will be 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 upper case; surrounding the
parameter with quote marks (" or ') prevents MPE/iX
from upshifting 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 will execute
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
will be written to the loader list device. The
default is not to print a load map. The load maps
for Compatibility Mode and for Native Mode are
significantly different from each other.
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:
o The SOM's Description area. There is one per loaded SOM.
o The Process Data Dictionary area.
Each SOM Description Area has six sections:
o The name section.
o The locality name section.
o The export code symbols section.
o The import code symbols section.
o The export data symbols section.
o 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.
Example
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.
EXPORTED CODE SYMBOLS ....
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:
o Entry - Any code entry point. Includes both primary and
secondary entry points that may be used as targets of
inter-space calls.
o PProg - Primary program entry point.
o 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.
IMPORTED CODE SYMBOLS .....
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:
o 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.
o Plabl - Plabel - 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.
EXPORTED DATA SYMBOLS .....
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:
o Data - Normal initialized data - Example (a C construct):
double b = 3.3;
o 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:
o 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.
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.
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
File Type
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. Regardless
of what you specify, MPE/iX may change maxstack to
accommodate table overflow conditions.
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 511 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 is estimated by the MPE
Segmenter.
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. 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, of the NM heap.
This must be a decimal number. The default
is -1, which currently instructs the command to
assign a system-defined constant as the value of
nmheapsize.
G, P, or S Use these parameters to quickly specify the
executable libraries that are used to load the
program. The meaning of these parameters
carry over from MPE V/E.
S Use the system library to bind the
external references of the program. This
is the default.
P Search the program's public account library
before searching the system library to
resolve the program external references.
G Search the program's group library first,
then its public account library, and
finally the system library to resolve the
program's external references.
These parameters will result in a fail load if the
progfile parameter 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.
Library names, except those in the system library,
may be redirected with a file equation.
If the LIB and XL parameters are missing, this
parameter will default to S. This parameter may not
be used at the same time as the XL parameter.
"library" Specifies the library or libraries that are to be
searched, and the order in which they are to be
searched, in order 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 quote marks (" or
'). Compatibility Mode will ignore this parameter
if it is specified. In Native Mode, this parameter
will override 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 will be used only if
the LIB and XL parameters are both absent.
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 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 will be 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 will end without loading
lib2.diag.sys.
This prevents non-PM processes from "piggybacking"
on legitimate PM processes.
XL.PUB.SYS and NL.PUB.SYS are searched
automatically. The user does not need to specify
them.
(XL.PUB.SYS, NL.PUB.SYS, and SL.PUB.SYS compose the
system libraries for MPE/iX.)
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 will be searched. XL.PUB.SYS will be
ignored in this particular case. However, if you
specify XL.PUB.SYS but not NL.PUB.SYS, both will be
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
the progfile parameter contains a name which can
only be expressed in the HFS syntax, the files 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 It 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, CIR. Programs using other types of file ignore the NOCB
parameter.
Be aware, however, 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 single or double
quote marks (" or '). If you want a quote 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 "EXAMPLE".
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. The default
is that no string is passed, and the length of the
string is set to zero (0).
MPE/iX provides an intrinsic (GETINFO) for
retrieving the quotedstring for a Native Mode or
compatibility mode process. Refer to the
Introduction to MPE/iX for MPE V Programmers
(30367-90005).
unsatproc Specifies the (fall-through) procedure that will be
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 upper case; surrounding
the parameter with quote marks prevents MPE
XL from performing the upshift and permits you to
enter strings for case sensitive applications.
For instance
;UNSAT = terminate
The procedure TERMINATE will be linked if one of the
external references cannot be resolved to one of the
available libraries. Because the value terminate is
not delimited by quote marks (" or '), the value is
upshifted to TERMINATE.
;UNSAT = "foo"
;UNSAT = 'foo'
Here the procedure foo will be linked if one of the
external references cannot be resolved to one of the
libraries. In both cases, delimiting the value foo
with quote marks (" or ') causes MPE/iX to use the
value as given, in lower case.
When the loader links a procedure call to the UNSAT
procedure, a warning message is sent to the loader
list device, giving the name of the missing
procedure and the file it is referenced from. If the
user does not supply an UNSAT procedure and a
process cannot be fully bound, the load will fail.
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. This
parameter must have one of the following
subparameters
*formaldesig The formal file designator for a file
previously specified in a file
equation.
fileref The name of an existing permanent disk
file.
$NULL The actual file designator of a
system-defined file that is always
treated as an empty file. When
referenced by 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 online programs. Specifying a
positive integer (#) permits you to set priority at
points that lie between the preset priority levels
BS, CS, DS, 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, non-privileged)
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 will set the highest priority below BS. The
default is CS.
Use care in assigning the BS queue. Processes at this 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 created with the system
defaults. The system defaults of the new
file are fixed length binary 132-byte
records with a maximum file size of 1023
records.
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 temporary, only the logon group and
account libraries for the current session will be searched.
Refer to Accessing Files Programmer's Guide (32650-90017)
for more information on file domains.
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 RESUME
continues the execution.
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) 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 PH capability to load programs whose name cannot be expressed, using MPE syntax, with PH capability. CM Programs cannot be loaded from the HFS directory.
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. In this example,
$STDLIST is set 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
Commands: None Manuals : MPE/iX Intrinsics Reference Manual (32650-90028). Back to Main Index