ROLLOUT

ANSI

The ROLLOUT instruction suspends program execution allowing one or more system functions may be performed. Program execution is reinstated at the next instruction using the appropriate rollback method for the runtime being used. The instruction uses the following format:

[label]

ROLLOUT

{command}[,{name}]

Where:

label

Optional. A Program Execution Label.

command

Required. A previously defined Character String Variable, a string Literal, or a character string ARRAY element containing the command line executed.

name

Required. A previously defined Character String Variable, a string Literal, or a character string ARRAY element that is ignored by the runtime.

Flags Affected: NONE

Note the following:

If {command} is a string variable, only the Logical String contents are utilized.
The optional {name} parameter is provided for language compatibility only and is ignored by the runtime. A warning message is displayed if the parameter is specified.
The current program status, including all variable pointers, file pointers and Flags, is written into a file for subsequent restoration upon the return from the ROLLOUT. The program terminates and control is passed to the operating system.
If {command} is provided, and it is not a Null String, it is placed in the key ahead buffer for execution once the operating system takes control. The command line's execution status is only limited by the operating system's criteria for executable command lines.
If the command fails to execute when using PLBWIN or SUNDB86A, ROLLOUT automatically attempts to execute the command using the current COMSPEC keyword if available.
The command line may be limited to 127 bytes or may not be supported by some operating systems (although functional under true MS-DOS and Linux compatible systems). Note: For SUNDB86x, if ANSI.SYS is not loaded the command line is limited to 15 bytes. Note: Programs running with Windows-Style runtimes fall into the "Unsupported" category.
Under PLBWIN, ROLLOUT functions as an EXECUTE and no rollback is necessary. When the task is finished, the current program begins executing again at the instruction following the ROLLOUT. If the task was another PL/B program, the STOP in that program returns control to the current program. There is no ROLLOUT file that is saved.
To return from a ROLLOUT under SUNDB86x, the ROLLOUT return program SUNDBACK must be executed manually or as the last command in the batch file. If the program was loaded with SUNDBSYx on the same command line, SUNDBACK must also be loaded with SUNDBSYx. For example:

	SUNDBSYS	SUNDBSYS PROGRAM
	PROGRAM	...
	...	SUNDBSYS SUNDBACK
	SUNDBACK

To return from a ROLLOUT under Linux, PLB must be executed using the `-r' option manually or as the last command in the shell script file.
To return from a ROLLOUT under PLBCON, PLBCON must be executed using the `-r' option manually or as the last command in the shell script file.
Using the correct ROLLOUT return sequence restores the screen (including all attributes and cursor positioning) to its original condition before the ROLLOUT was executed. In addition, all other program attributes previously saved are restored.
Programs that increase or modify the resident memory contents should not be between a ROLLOUT and its subsequent return. Such activity may cause indeterminate results.
Any files open at the time of the ROLLOUT should not be modified or the results may be indeterminate. (Note on PLBCMP: Only files open in SHARE (default) mode remain open upon ROLLOUT return. Any file opened in READ or EXCLUSIVE mode must be re-opened upon return from the ROLLOUT. If the current working subdirectory after return from the ROLLOUT is not the same as it was before the ROLLOUT, I/O errors (I03) may occur.)
SUNDBACK (ROLLOUT return) is not supported by programs generated with the 'C' option under SUNDB86M. The SUNDB86M compiler generates an error message if the 'C' option is given and a ROLLOUT instruction is detected.
ROLLOUT should not be performed in a program invoked via an EXECUTE instruction.
For PLBCMP in a GUI environment, the ROLLOUT does not actually terminate the process butsuspends the process. A new window is created and the command passed in the ROLLOUT instruction executed. ROLLOUT should not be employed to exit from the PL/B environment. Use SHUTDOWN or STOP instead.
If a FILEPI instruction is active, it is terminated.
ROLLOUT is not available when using the PLBCE runtime.
ROLLOUT while using Auto Load DIM variables is not allowed and will produce an error. This is because the Auto Load DIM variables are created using OS memory allocation functions and these variables do not reside in the program memory space.