|
$userid | ||
User identification to which the database is assigned. Only required if the database is not cataloged under the identification with which the DBH was started. | ||
dbname | ||
Name of the database | ||
copy-name | ||
Suffix of the shadow database. | ||
n | Size of the user buffer pool for the database in Mbytes. If the parameter bufferid is specified, the buffer pool specified by n is created as a shared user buffer pool (see below): | |
n = 1 .. 2047 | ||
For a database in 8-Kbyte page format, at least 3 Mbytes are created. | ||
n = 0 | ||
The size of the user buffer pool has already been defined in another database. | ||
n not specified and bufferid not specified | ||
The database is buffered in the system buffer pool corresponding to its page format. If this system buffer pool does not exist, activation of the database is rejected. | ||
n not specified and bufferid specified | ||
The size of the user buffer pool has already been defined in another database. | ||
bufferid | ||
Identifier of a shared user buffer pool up to 6 alphanumeric characters (no special characters) | ||
realm-name | ||
Name of the realm | ||
password | ||
password may be up to four bytes in length and is represented as follows: X’nnnnnnnn’: d: | ||
admpassword | ||
admpassword may be up to four bytes in length and is represented as follows: X’nnnnnnnn’: | ||
The ADD command is used to link databases, realms and passwords into an ongoing session. However, it is also possible to use an ADD command to revoke a DROP command, provided that no PERFORM command has yet been issued to initiate execution of the DROP and ADD commands. As a rule, ADD DB and ADD RN are not executed until a PERFORM has been issued.
Attaching databases
ADD DB=[$userid.]dbname
The DBH notes a request to attach the given original database. As a result, the current DB configuration is altered. If the specified database is already attached and a DROP command requesting detachment of the database has previously been issued, the DROP command is revoked by ADD DB.
ADD DB=$userid.dbname.copy-name
Attaches the corresponding shadow database, and thus alters the current DB configuration.
When a detach request (DROP DB) exists for a database which has already been attached (original or copy), this detach request is only canceled by a subsequent DAL command ADD DB if the copyname specified in ADD DB matches the copy currently attached (in the case of a DB original this means: no copyname is specified). Otherwise the current copy of the database is detached with the following PERFORM, and the copy with the specified copy name is attached.
This enables
a DB original to be replaced by a DB copy,
a DB copy to be replaced by a DB original or
a DB copy to be replaced by another DB copy
during PERFORM processing (i.e. in one step).
OPTION default value
With regard to the original database:
No RETRIEVAL option, i.e. the DBH opens the database in the exclusive mode; the application programs have read and write access.
With regard to the shadow database: SHARED-RETRIEVAL.
OPTION=SHARED-RETRIEVAL
The DBH has shared access to the added database. Other DBHs may also access this database via OPTION=SHARED-RETRIEVAL. Application programs of all these DBHs will then have only read access to the added database.
OWN-BUFFER-SIZE=n
Specifies the size of a user buffer pool for the database to be attached. If a database with an 8-Kbyte page format is involved, at least 3 Mbytes are allocated. The buffer pool is created dynamically on attaching the database in addition to the system buffer pools. If ID=bufferid is not specified, this buffer pool should only be used to buffer pages of the associated database. If ID=bufferid is specified, a shared user buffer pool is allocated to the database (see below).
If OWN-BUFFER-SIZE is not specified, the database is buffered in the system buffer pool for its page format. If this system buffer pool does not exist, the request to attach the database is rejected.
ID=bufferid
The buffer pool specified with OWN BUFFER-SIZE=n is assigned to the database as shared user buffer pool with the identifier bufferid. A shared user buffer pool can be assigned to several databases as an exclusive, shared buffer pool. If no buffer pool with the identifier bufferid is available, a new shared user buffer pool with this name will be created and assigned to the database. Otherwise, the buffer pool bufferid is also used to buffer the pages of the associated database, under the following conditions:
The page size of the database matches the page size of the shared user buffer pool
The size of the buffer pool specified with OWN-BUFFER-SIZE=n corresponds to the size of the available shared user buffer pool
or
OWN-BUFFER-SIZE has the value 0
or
OWN-BUFFER-SIZE=n is not specified.
Responses in error situations
The ADD DB command is immediately rejected if
the number of databases specified for attachment is greater than that specified in PP MAXDB
an identically named original database or shadow database is already attached and no request to detach (DROP) it has been issued
a request to attach (ADD) an identically named database has already been issued.
the size of the buffer pool specified with OWN-BUFFER-SIZE=n does not correspond to the size of the shared user buffer pool specified with ID=bufferid.
OWN-BUFFER-SIZE=n has the value 0, ID=bufferid is specified and the bufferid buffer pool is not yet defined (in another database).
During processing of the request to attach a database there may be errors if
the specified database does not exist or cannot be attached in the required usage mode.
the specified database is inconsistent and consistency cannot be restored by means of a warm start because the database is engaged in RETRIEVAL functions or because the DBH cannot access the associated RLOG file and/or DB status file exclusively (see section "Evaluation of DBH load parameters" in chapter "DBH load parameters").
owing to distributed processing featuring UDS-D/openUTM in the (inconsistent) database there are transactions in the "Prepared to Commit" (PTC) condition and, in the case of UDS-D, the PTCSYNCH value for the current session is set to WAIT.
errors occur when the files of this database are attached.
the page size of the database does not correspond to that of the shared user buffer pool specified with ID=bufferid.
one of the ALOG logging specifications which were made using the DEFAULT-SUPPORT or RESERVE-SUPPORT parameter in the BMEND statement START-LOG is outside the pubset space of the current UDS/SQL pubset declaration.
If consistency cannot be restored owing to one of these errors occurring while the database is being attached, the database is immediately detached again.
If database consistency can be restored in spite of the above problems, the database is attached to the fullest possible extent to enable at least a partial realm configuration to be deployed.
Attaching realms
ADD RN=realm-name[,DB=dbname]
The DBH notes a request to attach the realm realm-name or cancels a pending DROP command.
DB=dbname need only be specified if the realm name is not unique throughout the DB configuration. It then specifies the intended database.
The ADD RN command can be used to rejoin to the current session a realm detached (DROP) for repairs or owing to device shortages.
The ADD RN request is not executed until the PERFORM command is issued.
The ADD RN command can be used to revoke an earlier DROP RN command. DROP requests which have already been started cannot be revoked.
Responses in error situations
The ADD RN command is rejected if:
the designated realm is not present in the attached databases
the realm name is not unique in the current DB configuration because DB=dbname has not been specified
the designated realm is already attached and no request to detach it has been issued
the designated realm cannot be attached because it is a temporary realm or part of a database for which SHARED RETRIEVAL has been specified
errors occur when the realm is being attached
the realm is marked defective or inconsistent.
A failsafe log of the attachment of a realm is not entered in the DBDIR until the request has been processed in full. A failsafe attachment is one that remains in effect following session aborts and DBH termination.
Attaching file passwords
ADD PW=password
Attaches the designated file password. This alters the current set of passwords.
Responses in error situations
The ADD PW command is rejected if the limit of 100 concurrent passwords is exceeded as a result of adding the designated password (see section “Assigning passwords to UDS/SQL files”).
Attaching administration passwords
ADD ADM=admpassword
Attaches the designated database administrator password. As a result the database administrator password is either specified for the first time if no password has yet been attached by means of the PP ADMPASS parameter, or changed, provided that the current database administrator password has previously been excluded with the DAL command DROP ADM.
Responses in error situations
The ADD ADM command is rejected if an database administrator password has already been defined for the DBH.