CREATEPROCESS

Syntax

                 I*            I16  CA           I*A       I*A
  CREATEPROCESS (createstatus, pin, formaldesig, itemnums, items);

Parameters

createstatus

(NM) 32-bit signed integer by reference (required)

(CM) 16-bit signed integer by reference (required)

Returns a value indicating the type of success or failure. A negative value indicates that the associated message is a warning, an error terminates the intrinsic call, and a warning means the call continues. Check the job control word (JCW) before continuing. The following is a list of the possible values returned:

VaIue

Meaning

0

Successful

1

Process handling (PH) capability required

2

Pin or formaldesig parameter missing; or one of itemnum pair is missing (for example, 11 and 12 or 19 and 24)

3

Parameter address (other than createstatus) out of bounds

4

Out of system resources

5

Process not created; invalid itemnum specified; or, for a compatibility mode process, total requested stack space exceeds maximum configured.

6

Process not created; formaldesig does not exist

7

Process not created; formaldesig invalid

8

Process not created; entry name invalid or does not exist

-9

Process created; LIBSEARCH bits ignored

-10

Process created; itemnum=19 ignored

15

Process not created; reserved item was specified

16

Process not created; hard load error occurred (for example, I/O error reading formaldesig)

17

Process not created; illegal value specified for itemnum=7

18

Process not created; specified $STDIN could not be opened

19

Process not created; specified $STDLIST could not be opened

20

Process not created; string to be passed to new process invalid (pointer without length, length without pointer, or length exceeds stack size of calling process)

pin

16-bit signed integer by reference (required)

Returns the process identification number (PIN) of the newly created process. This PIN is used by other intrinsics to reference the new process. If an error is detected, a value of zero is returned.

formaldesig

character array (required)

Passes the name of the program file to be run. Terminate the string with any nonalphanumeric character other than a period (.) or a backslash (/). This paramenter is equivalent to the progfile parameter of the RUN command.)

itemnums

(NM) 32-bit signed integer array (optional)

(CM) 16-bit signed integer array (optional)

Specifies which item value is to be passed.

Values passed may be passed by value.

items

(NM) 32-bit signed integer array (optional)

(CM) 16-bit signed integer array (optional)

Specifies if the formaldesig parameter contains a program name that is unrecognizable using MPE syntax, LIBSEARCH will result in a failed load.

Itemnum

Item Description

0

Indicates the end of the option list. No value is required in the corresponding item.

1

The address must be a byte address (type-coerced) containing the entry point name in the program where the new process is to begin execution (equivalent to the entrypoint parameter of the RUN command.) The name consists of a string of characters terminated by a blank.

2

A value passed to the new process (equivalent to the PARM= parameter of the RUN command.)

3

The load options for loading the program file of the new process, designated as:

  (NM)
      Bits (0:16)    Zeros
      Bits (16:16)   Load options
  (CM)
      Bits (0:16)    Load options

Item 3 has the same definition as the loadflag parameter of the CREATE intrinsic. If both itemnums 3 and 19 are specified, the LIBSEARCH option is ignored or if LIBSEARCH is set to a value other than its default (00), a warning is returned indicating the LIBSEARCH option was ignored.

4,5,6

(CM Only) Ignored if formaldesig specifies an NM program file; created using MPE V/E maximum default values (equivalent to the STACK=, DL=, and MAXDATA= parameters of the RUN command).

7

The priority class where the new process is scheduled (AS, BS, CS, DS, ES); is computed as (equivalent to the PRI= parameter of the RUN command.):

  (ASCII of first character 256) + (ASCII of second character)

The integer equivalents are:

  AS = 16,723
  BS = 16,979
  CS = 17,235
  DS = 17,491
  ES = 17,747

If in user mode (nonprivileged), any priority class can be specified except AS; this is limited by the maximum priority assigned to the account by the system manager. If PM capability has been assigned, processes can be scheduled into all subqueues. A process in the linear queue AS or BS does not give up the CPU voluntarily, it could loop infinitely and prevent other processes from accessing the CPU. Default: The calling process priority class.

8

The address must be a byte address (type-coerced) containing a definition of the file to be used as $STDIN for the new process (equivalent to the STDIN= parameter of the RUN command). Must contain an ASCII string (terminated by a carriage return) specifying the file to be used as $STDIN (that is, everything after the FILE formaldesig=; portion of the file equation). If itemnum=8 is not specified, the default $STDIN and $STDLIST (current for the creating (parent) process) are used for the new process creation.

9

The address must be a byte address (type-coerced) containing a definition of the file to be used as $STDLIST for the new process (equivalent to the STDLIST= parameter of the RUN command). If itemnum=9 is not specified, the default $STDIN and $STDLIST (current for the creating (parent) process) are used for the new process creation.

10

Specifying this item is equivalent to calling the ACTIVATE intrinsic with the newly created process. The value passed is equivalent to the allow parameter of ACTIVATE, except bit (31:1) is the parent activation bit and bit (30:1) is the child activation bit.

11

The address must be a byte address (type-coerced) containing information to be passed to the new process. The length of the string must be specified in itemnum=12 (equivalent to the INFO= parameter of the RUN command), accessible through the GETINFO intrinsic.

12

The length (in bytes) of the string referenced by itemnum=11. The maximum allowable value of the INFO string length is 1024 bytes. Accessible through the GETINFO intrinsic.

13

Not used.

14

The address must be a byte address (type-coerced) containing a definition of the file to be used as $STDERR for the new process. If itemnum=14 is not specified, the $STDERR (current for the creating (parent) process) is used for the new process creation.

Redirecting output to $STDERR permits the user to write errors to a user-specified disc file.

15-18

(NM Only) Reserved for the system.

19

(NM Only) The address (type-coerced) containing a list of unresolved external references found in formaldesig (equivalent to the XL= parameter of the RUN command). When formaldesig contains a name in MPE syntax, the file names must follow file naming conventions and be separated by commas. When formaldesig contains a name in HFS syntax, you must use an absolute pathname and the file names specified in this item must be fully qualified.
If itemnums 3 and 19 are specified, the LIBSEARCH option in itemnum=3 is ignored or if LIBSEARCH is set to a value other than its default (00), a warning is returned indicating the LIBSEARCH option was ignored. The length of the string must be specified in itemnum=24.

20-22

(NM Only) Reserved for operating system.

23

(NM Only) The address (type-coerced) containing the name of a procedure to link unsatisfied references to. The name consists of a string of characters terminated by an ASCII carriage return character or a blank (equivalent to the UNSAT= parameter of the RUN command).

24

(NM Only) The length of the string referenced by itemnum=19.

25

(NM Only) Reserved for operating system.

26

The address must be a byte address containing the maximum size (in bytes) that the NM stack can grow (equivalent to the NMSTACK= parameter of the RUN command).

27

The address must be a byte address containing the maximum size (in bytes) that the NM heap can grow (equivalent to the NMHEAP= parameter of the RUN command).

Condition Codes

CCE (2)

Request granted.

CCG (0)

Request granted. Check the createstatus parameter to see if warning codes were returned.

CCL (1)

Request denied. Check the createstatus parameter to determine why the request was denied.

Related Information

Intrinsics

CREATE

Commands

RUN

Manual

Process Management Programmer's Guide