Generated from C.65.00 /SYSADMIN/PUB/MYCICAT last modified on Sun Aug 29 15:08:37 2004
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. DP : 240. 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. 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