This statement closes spaces of a database logically and physically in order to prepare for the creation of a foreign copy.
Scope of validity
DBH administration
See also
DBH administration statement END-FOREIGN-COPY on "END-FOREIGN-COPY"
DBH administration statement BEGIN-LOCK-SEQUENCE on "BEGIN-LOCK-SEQUENCE"
DBH administration statement END-LOCK-SEQUENCE on "END-LOCK-SEQUENCE"
Function
At the time when a foreign copy is created, the spaces concerned must be properly closed. You can use the PREPARE-FOREIGN-COPY statement to close the spaces logically and physically.
In logical closure, the update is interrupted on the space by a transaction lock. The contents of the buffers of the selected database are written to the corresponding files. These files remain physically open.
As long as the database is not updated, a foreign copy can be created. Updates must be prevented by organizational means or by issuing the PREPARE-FOREIGN-COPY statement in a lock sequence, which is better. Read access to the database is also possible during the lock sequence.
Lock sequences are opened with BEGIN-LOCK-SEQUENCE and terminated with END-LOCK-SEQUENCE.
In the case of physical closure the contents of the buffers of the selected database are retained. This means that foreign copies are also possible which require the database files to be physically closed (e.g. SNAP dump). The database is placed in the CLOSED status. In this status accesses to the database are rejected with SQLSTATE. This remains invisible for application programs if the statement sequence PREPARE-FOREIGN-COPY (with CLOSE) and END-FOREIGN-COPY is used within a lock sequence.
The logging for a space, a space set or the entire catalog can be turned on with the statement PREPARE-FOREIGN-COPY. The logging information can be used for repair with foreign copies generated after the statement PREPARE-FOREIGN-COPY.
The statement PREPARE-FOREIGN-COPY can be used independently of the statement END-FOREIGN-COPY.
If the statement END-FOREIGN-COPY follows in the same administration session, this only acts on the spaces entered in the preceding statement PREPARE-FOREIGN-COPY.
If the logging is only to be turned on for a few spaces and other spaces are to be backed up as a space set, a PREPARE-FOREIGN-COPY statement must first be given for turning on the logging. This is then followed by another PREPARE-FOREIGN-COPY statement with all the spaces to be backed up. The final END-FOREIGN-COPY statement then acts on all the spaces backed up.
PREPARE-FOREIGN-COPY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
SELECT =
Specifies the name by means of which the database is identified.
SELECT = *LOGICAL(...)
Selects the database to be logically closed.
CATALOG-NAME =
<filename 1..18 without-cat-user-gen-vers>
Logical database name
SELECT = *PHYSICAL(...)
Selects the database to be logically closed.
PHYS-CATALOG-NAME =
<filename 1..18 without-cat-user-gen-vers>
Physical database name
SPACE-NAMES =
Specifies the spaces to be closed.
The backups of the spaces closed with this statement can be entered in a space list in the utility statement RECOVER (using foreign copy); see the utility statement RECOVER in the “ SQL Reference Manual Part 2: Utilities” manual.
SPACE-NAMES = *ALL(...)
All user spaces and the catalog space are logically closed.
CLOSE = *NO
The database files remain physically open.
CLOSE = *YES
The database files are also physically closed.
The database is placed in the CLOSED status. An END-FOREIGN-COPY statement must be entered in the same DBH session.
SPACE-NAMES = *CATALOG
Only the catalog space is logically closed. You can then only generate a consistent foreign copy of the catalog space.
SPACE-NAMES = *FROM-FILE(...)
Selects the spaces which are to be logically closed by listing them in a file.
FILE-NAME = <filename 1..54>
File name of a SAM file which contains a space name in each line. Up to 999 spaces can be specified in this way.
Example
File with a list of space names which was created with the EDT editor:
TABLESPACE INDEXSPACE BLOBSPACE
SPACE-NAMES =
list-poss(200): <filename 1..18 without-cat-user-gen-vers>
The user spaces entered are logically closed. You can then only generate a consistent foreign copy of these spaces.
LOGGING =
Specifies whether the logging is turned on for the spaces specified in the operand SPACE-NAMES.
LOGGING = *UNCHANGED
The settings for the logging remain unchanged.
LOGGING = *ON
The logging is turned on for the spaces specified in the operand SPACE-NAMES. Logging for individual spaces can only be turned on if the catalog is already logging. The backups on the spaces which are closed with this statement form the basis of the logging.
Administration command in ISP format and at the CALL DML interface
The FCOPY,PREPARE administration command corresponds to the PREPARE-FOREIGN-COPY administration statement here.
FCOPY,P[REPARE],supplement
[,{space|CLOSE}][,L[OGGING-ON]]
supplement ::= {C[ATALOG]=catalog-name|
P[HYSICAL-NAME]=physical-name}
space ::= S[PACE]={(space-name,...)|C[ATALOG]}
Up to 999 user spaces can be specified for space-name. If only one space-name is specified, the parentheses can be omitted. The values defined beforehand in the relevant operands may be entered for catalog-name and physical-name.
In INFORM-PROGRAM administration you must adhere to the permissible length for the command (see section “Administration using INFORM-PROGRAM”).