CREATE

Syntax

          CA           CA         I16  I16V  U16V
  CREATE (formaldesig, entryname, pin, parm, loadflags,
          I16V       I16V    I16V     U16V           I16V
          stacksize, dlsize, maxdata, priorityclass, rank);

Parameters

formaldesig

character array (required)

The name of the program to be created, specified either in MPE or HFS syntax. If you are using MPE syntax, formaldesig passes the name, group (optional), and account (optional) of the file containing the program to be run, and, if applicable, a lockword. If you are using HFS syntax, formaldesig passes the relative pathname or the absolute pathname of the file containing the program to be run. The last element of the array must be a blank. This parameter is equivalent to the progfile parameter of the RUN command.

entryname

character array (optional)

Passes the declared entry point (label) in the program where execution is to begin when the process is activated. The last element of the array must be a blank. Specify the program's primary entry point with an array consisting of one blank character. (Equivalent to the entrypoint parameter of the RUN command.)

Default: The program's primary entry point is used.

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.

parm

16-bit signed integer by value (optional)

Passes information to the new process. The new process can access this information by using the GETINFO intrinsic. (Equivalent to the parm= parameter of the RUN command.)

Default: parm=0.

loadflags

16-bit unsigned integer by value (optional)

Specifies the loading options as follows:

Bits	Value	Meaning
15:1	Active
	0 (default)	Calling process not activated when the new process terminates
	1	The system reactivates the calling process (parent) when the new process terminates
14:1	Loadmap	(equivalent to the LMAP parameter of the RUN command)
	0 (default)	No map produced
	1	A list of the allocated (loaded) program is produced on the job/session list device; displays information about all SOMs loaded during process creation
13:1	Debug	Ignored if nonprivileged and the new process requires privileged mode or if there is no read/write access for the new process program file (equivalent to the DEBUG parameter of the RUN command.)
	0 Default	Breakpoint not set
	1	Debug called prior to executing the first instruction of the new process
12:1	Privilege	(equivalent to the NOPRIV parameter of the RUN command)
	0 (default)	Program loaded in the mode specified when the program was linked
	1	Program loaded in nonprivileged mode
10:2	LIBSEARCH bits	Specifies a failed load if the formaldesignator parameter contains a program name which cannot be expressed using the MPE syntax. This option is equivalent to the LIB= parameter of the RUN command
	00 (default)	(NM) If formaldesig was linked using the XL= parameter of the LINK command, then search the libraries specifying XL= first. Otherwise, search only the system libraries. (CM) Search only the system libraries (SL.PUB.SYS).
	01	(NM) Search the account public library (XL.PUB.accountname) in the account where formaldesig is located, then search the system libraries. (CM) Search the account public library (SL.PUB.accountname) in the account where formaldesig is located, then search the system libraries.
	10	(NM) Search the group library (XL.groupname.accountname) in the account where formaldesig is located, then the account public library, and then the system libraries. (CM) Search the group library (SL.groupname.accountname) in the account where formaldesig is located, then the account public library, and then the system libraries.
9:1	Control Block	controls where the control blocks of device files are established and files of type message, RIO, and circular (equivalent to the NOCB parameter of the RUN command)
	0 (default)	Establish file control blocks in the process control block extension (PCBX) area of the CM stack
	1	Establish file control blocks in an extra data segment
7:2	00	Reserved for operating system
5:2	Stack dump	control the enabling/disabling mechanism where the stack is dumped in the event of an abort
	00 (default)	Stack dump mechanism enabled only at parent level
	01	Stack dump mechanism enabled unconditionally
	10	Stack dump mechanism enabled only at parent level
	11	Stack dump mechanism disabled unconditionally for new process
4:1	0	Reserved for operating system
3:1	DL to initial Q	Ignored if formaldesig specifies a native mode program file. Used for backward-compatibility with MPE V/E-based systems only.
	0 (default)
	1
0:3	000	Reserved for operating system used only when bits (5:2)=01.

stacksize

16-bit signed integer by value (optional)

(NM) Ignored if formaldesig specifies an NM program file (used for backward-compatibility with MPE V/E-based systems only). The NM stack is created using NM default values. The CM stack is created using MPE V/E mode default values. (Equivalent to the stack= parameter of the RUN command.)

(CM) Passes the number of words assigned to the local stack area bounded by the initial Q and Z registers. A value of -1 indicates that the Segmenter will assign the default values (equivalent to omitting this parameter).

dlsize

16-bit signed integer by value (optional)

(NM) Ignored if formaldesig specifies an NM program file (used for backward-compatibility with MPE V/E-based systems only). The NM stack is created using NM default values and the CM stack is created using MPE V/E maximum default values. (Equivalent to the DL= parameter of the RUN command.)

(CM) Passes the number of words in the user stack area bounded by the DL and DB registers. A value of -1 indicates that the Segmenter will assign the default values (equivalent to omitting this parameter).

maxdata

16-bit signed integer by value (optional)

(NM) Ignored if formaldesig specifies a native mode program file (used for backward-compatibility with MPE V/E-based systems only). The NM stack is created using NM default values and the CM stack is created using MPE V/E maximum default values. (Equivalent to the MAXDATA= parameter of the RUN command.)

(CM) Passes the maximum size allowed for the process stack in words. This value overrides the value specified at program preparation. A value of -1 indicates that the Segmenter will assign the default value. If not specified in either the intrinsic call or the program file, the stack size remains the same.

priorityclass

16-bit unsigned integer by value (optional)

Returns the integer equivalent of two ASCII characters specifying the priority class where the new process is scheduled (AS, BS, CS, DS, ES). It is computed as:

  (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 a user is nonprivileged, the processes can be rescheduled into any of the five subqueues except the AS queue. This function is limited by the maximum priority assigned to the account by the system manager.

If a user is privileged, the processes can be scheduled into any subqueue, including the AS. A process in the AS or BS linear queue does not give up CPU voluntarily; it could loop infinitely and prevent other processes from accessing the CPU. (Equivalent to the PRI= parameter of the RUN command.)

Default: The calling process priority.

rank

16-bit signed integer by value (optional)

For backward-compatibility with MPE V/E-based systems only.

Operation Notes

1. Loads the program to be run by the new process into virtual memory.

2. Creates the process as the child of the calling process.

3. Initializes the process data areas.

4. Schedules the process.

5. Returns the new process identification number (PIN) to the requesting process.

• The value (a nonexistent subqueue) specified is illegal for the priorityclass parameter.

• The formaldesig is illegal.

• The entryname is illegal.

• The program specified by formaldesig contains more capabilities than allowed. PM, MR, or DS capability is not allowed if the program name uses HFS syntax.

• The program specified by formaldesig uses HFS syntax and has PH capability, but the user does not have PH capability.

• A CM program cannot be loaded from the HFS directory.

• The program file of the creating process does not have process handling (PH) capability.

• A required parameter (formaldesig or pin) is omitted.

• A reference parameter is not within the required range.

• The program name is equal to blank spaces.

Condition Codes

Related Information