The main structure used in the client interface is a job handle, which appears to the caller as an integer.
Handles are created using the DBMS_DATAPUMP.OPEN or DBMS_DATAPUMP.ATTACH function. Other sessions can attach to a job to monitor and control its progress. Handles are session specific. The same job can create different handles in different sessions. As a DBA, the benefit of this feature is that you can start up a job before departing from work, and then watch the progress of the job from home.
Parent topic: Using the Oracle Data Pump API
一、DBMS_DATAPUMP Job States
Use Oracle Data Pump DBMS_DATAPUMP job states show to know which stage your data movement job is performing, and what options are available at each stage.
Job State Definitions
Each phase of a job is associated with a state:
Undefined — before a handle is created
Defining — when the handle is first created
Executing — when the DBMS_DATAPUMP.START_JOB procedure is running
Completing — when the job has finished its work and the Oracle Data Pump processes are ending
Completed — when the job is completed
Stop Pending — when an orderly job shutdown has been requested
Stopping — when the job is stopping
Idling — the period between the time that a DBMS_DATAPUMP.ATTACH is run to attach to a stopped job, and the time that a DBMS_DATAPUMP.START_JOB is run to restart that job
Not Running — when a Data Pump control job table exists for a job that is not running (has no Oracle Data Pump processes associated with it)
Usage Notes
Performing DBMS_DATAPUMP.START_JOB on a job in an Idling state returns that job to an Executing state.
If all users execute DBMS_DATAPUMP.DETACH to detach from a job in the Defining state, then the job is totally removed from the database.
If a job abnormally terminates, or if an instance running the job is shut down, and the job was previously in an Executing or Idling state, then the job is placed in the Not Running state. You can then then restart the job.
The Data Pump control job process is active in the Defining, Idling, Executing, Stopping, Stop Pending, and Completing states. It is also active briefly in the Stopped and Completed states. The Data Pump control table for the job exists in all states except the Undefined state. Child processes are only active in the Executing and Stop Pending states, and briefly in the Defining state for import jobs.
Detaching while a job is in the Executing state does not halt the job. You can reattach to a running job at any time to resume obtaining status information about the job.
A Detach can occur explicitly, when the DBMS_DATAPUMP.DETACH procedure is run, or it can occur implicitly when an Oracle Data Pump API session is run down, when the Oracle Data Pump API is unable to communicate with an Oracle Data Pump job, or when the DBMS_DATAPUMP.STOP_JOB procedure is run.
The Not Running state indicates that a Data Pump control job table exists outside the context of a running job. This state occurs if a job is stopped (and likely can restart later), or if a job has abnormally terminated. You can also see this state momentarily during job state transitions at the beginning of a job, and at the end of a job before the Data Pump control job table is dropped. Note that the Not Running state is shown only in the views DBA_DATAPUMP_JOBS and USER_DATAPUMP_JOBS. It is never returned by the GET_STATUS procedure.
The following table shows the valid job states in which DBMS_DATAPUMP procedures can be run. The states listed are valid for both export and import jobs, unless otherwise noted.
Table 6-1 Valid Job States in Which DBMS_DATAPUMP Procedures Can Be Executed
Procedure Name Valid States Description
ADD_FILE
Defining (valid for both export and import jobs)
Executing and Idling (valid only for specifying dump files for export jobs)
Specifies a file for the dump file set, the log file, or the SQLFILE output.
ATTACH
Defining, Executing, Idling, Stopped, Completed, Completing, Not Running
Enables a user session to monitor a job, or to restart a stopped job. If the dump file set or Data Pump control job table for the job have been deleted or altered in any way, then the attach fails.
DATA_FILTER
Defining
Restricts data processed by a job.
DETACH
All
Disconnects a user session from a job.
GET_DUMPFILE_INFO
All
Retrieves dump file header information.
GET_STATUS
All, except Completed, Not Running, Stopped, and Undefined
Obtains the status of a job.
LOG_ENTRY
Defining, Executing, Idling, Stop Pending, Completing
Adds an entry to the log file.
METADATA_FILTER
Defining
Restricts metadata processed by a job.
METADATA_REMAP
Defining
Remaps metadata processed by a job.
METADATA_TRANSFORM
Defining
Alters metadata processed by a job.
OPEN
Undefined
Creates a new job.
SET_PARALLEL
Defining, Executing, Idling
Specifies parallelism for a job.
SET_PARAMETER
Defining
Note: You can enter the ENCRYPTION_PASSWORD parameter during the Defining and Idling states.
Alters default processing by a job.
START_JOB
Defining, Idling
Begins or resumes execution of a job.
STOP_JOB
Defining, Executing, Idling, Stop Pending
Initiates shutdown of a job.
WAIT_FOR_JOB
All, except Completed, Not Running, Stopped, and Undefined
Waits for a job to end.
Parent topic: Using the Oracle Data Pump API
二、 What Are the Basic Steps in Using the Oracle Data Pump API?
To use the Oracle Data Pump API, you use the procedures provided in the DBMS_DATAPUMP package.
The following steps list the basic activities involved in using the Data Pump API, including the point in running an Oracle Data Pump job in which you can perform optional steps. The steps are presented in the order in which you would generally perform the activities.
To create an Oracle Data Pump job and its infrastructure, run the DBMS_DATAPUMP.OPEN procedure.
When you run the procedure, the Oracle Data Pump job is started.
Define any parameters for the job.
Start the job.
(Optional) Monitor the job until it completes.
(Optional) Detach from the job, and reattach at a later time.
(Optional) Stop the job.
(Optional) Restart the job, if desired.
Related Topics
Oracle Database PL/SQL Packages and Types Reference
Parent topic: Using the Oracle Data Pump API
