{
{   The purpose of this request is to save the state of a program so that it
{ may later be restored.  The state of a program consists of the writable
{ working storage and the stack.  The state of the program is saved in the
{ container provided by the caller.  The state can be restored from the
{ container by using the pmp$restore_program_state request.
{
{   The primary purpose of this request is to provide a building block that
{ can be used by a task to clone itself.  The clone task would be executing
{ the same program at the same place and would have nearly the same working
{ storage and stack as the original task.  The minor differences between the
{ working storage and/or stack of the two tasks are the result of parameters
{ on the save/restore program state interfaces that make it possible for the
{ original and clone task to take different paths following the clone.
{
{   In order for a task to clone itself, the program being executed must
{ have two different paths and a means of determining which path is to be
{ followed. The path selection could be as simple as choosing the path based
{ on a parameter passed to the program when it is started.  One of the paths
{ of the program can be considered the normal path and it implements the
{ primary function of the program.  The other path is used only to complete
{ a cloning process.  The following algorithm demonstrates how a clone can
{ be achieved.
{
{   Original Task
{
{   1. The program looks at its parameters and determines that it should
{      perform its primary function.
{
{   2. As part of performing its primary function, it determines that it
{      must create a clone task.
{
{   3. It creates a segment access file and uses the pmp$save_program_state
{      request to save its current state in the segment.
{
{   4. It determines that it is the original program from the
{      original_program parameter returned by pmp$save_program_state and
{      therefore continues with the original program part of the algorithm
{      as follows.
{
{   5. It uses pmp$execute to start the clone task.  It does the execute
{      with its own program description but passes parameters which select
{      the "complete cloning" path and identify the file containing the
{      saved state.
{
{   6. It continues any other processing required by the original task.
{
{
{   Clone Task
{
{   1. The program looks at its parameters and determines that it should
{      perform the "complete cloning" function.
{
{   2. It opens the program state file (program parameter) for segment
{      access.
{
{   3. If desired, it sets up a parameter block in working storage that is
{      to be passed to the clone.
{
{   4. It uses the pmp$restore_program_state request to restore the program
{      state to that saved in the program state file.
{
{   5. It resumes execution following the pmp$save_program_state request
{      made by the original task but determines that it is not the original
{      program based on the original_program parameter returning false.
{
{   6. It continues any other processing required by the clone task.  Its
{      working storage and stack are the same as the original task, except
{      for the parameter block passed on the pmp$restore_program_state
{      request.  The parameter block can be used to cause the clone to
{      perform differently than the original task.
{
{
{       PMP$SAVE_PROGRAM_STATE (P_STATE_CONTAINER, ORIGINAL_PROGRAM, STATUS)
{
{ P_STATE_CONTAINER: (input, output) This parameter specifies a container in
{       which the program state is to be placed.  The container is an
{       adaptable sequence.  The program state is placed in the sequence at
{       the current position.  The current position is updated to reflect
{       the amount of space occupied by the program state.
{
{ ORIGINAL_PROGRAM: (output) This parameter returns the value TRUE to the
{       program that makes the pmp$save_program_state request.  It returns
{       the value FALSE to any program that "returns" from
{       pmp$save_program_state by using the pmp$restore_program_state
{       request.
{
{ STATUS: (output) This parameter returns the request status.
{        CONDITIONS:
{              pme$state_container_full
{              pme$unreadable_program_state
{
{
