This statement inserts entries in the SQL database catalog.
Definition
Second DBH start statement
Function
You use the DBH start statement ADD-SQL-DATABASE-CATALOG-LIST to supply the SQL database catalog with entries. You enter in the SQL database catalog the databases that the DBH can access during a DBH session. During a session, the DBH can only access databases that are entered in the SQL database catalog.
Each database in the SQL database catalog is identified by its logical name. The logical database name is the name by which an application program addresses a SESAM/SQL database. If there is no SESAM/SQL database with this logical name, an existing database is assigned by means of the physical database name. The physical database name is the name of the physical SESAM/SQL database.
When you make an entry, you assign a BS2000 user ID (DB user ID) to each database, enter the appropriate BS2000 password, assign the physical database name to the logical database name, and regulate access to the database. For each entry, SESAM/SQL inserts the valid status of the database during the current DBH session (see also the section on the SHOW-SQL-DB-CATALOG-ENTRIES administration statement on "SHOW-SQL-DB-CATALOG-ENTRIES").
You use the DBH option SQL-DATABASE-CATALOG (see "SQL-DATABASE-CATALOG") to specify the maximum permitted number of database entries. The default is 1, but you can specify a value of up to 254. If you enter more databases than the maximum number permitted, an error message appears.
You can enter up to 100 databases in a single start statement. If you want to enter more than 100 databases, you have to enter ADD-SQL-DATABASE-CATALOG-LIST as many times as is necessary.
You can also use several ADD-SQL-DATABASE-CATALOG-LIST statements to enter the required databases in groups.
You must always conclude parameter input for the ADD-SQL-DATABASE-CATALOG-LIST statement with the END statement. You can then enter the END statement again. The second END statement concludes input of the DBH start statements. Do not enter the second END statement at this point if you want to use the ADD-OLD-TABLE-CATALOG-LIST start statement to insert entries in the CALL DML table catalog.
You can enter fewer databases than specified by the DBH option SQL-DATABASE-CATALOG. SESAM/SQL reserves unused entries for administration. You can use administration statements to add or delete database entries during the session, but these additions and deletions apply only to this session.
Note that the CREATE CATALOG utility statement requires a free entry in the SQL database catalog.
ADD-SQL-DATABASE-CATALOG-LIST | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
ENTRY-1 = *NONE
No database is entered in the SQL database catalog at this point.
ENTRY-1 = *CATALOG(...)
First database entered in the SQL database catalog. You must at least enter the CATALOG-NAME operand, otherwise the entry in the SQL database catalog is invalid.
CATALOG-NAME = <filename 1..18_without_all>
Logical name of the database to be entered. The logical database name is the name by which a database is addressed in the application program. You must enter the logical database name, otherwise the entry in the SQL database catalog is invalid. The logical database name must be unique; you cannot assign this name more than once.
USER-ID = *DBH-USER-ID / <name 1..8>
DB user ID of the database.
The default value of USER-ID corresponds to the DBH user ID.
PASSWORD = *NONE / <c-string1..4> / <x-string 1..8> /
<integer -2147483648..+2147483647>
BS2000 password that protects the files in the database from unauthorized access. If the files in the database are protected by a BS2000 password, you must enter it here. The default, *NONE, means that the files in the database are not password protected.
PHYSICAL-NAME =
Physical name of the database
The physical database name assigns the logical database name used by the application program to the name of a physical database. The physical database name must be unique; you cannot assign this name more than once.
PHYSICAL-NAME = *STD
The physical database name corresponds to the logical database name you assigned under CATALOG-NAME.
PHYSICAL-NAME = <filename 1..18_without_all>
You must enter the physical database name when it differs from the logical database name.
The physical database name is derived from the BS2000 file name of a database's catalog space. The .CATALOG suffix is omitted. The BS2000 file name of a database's catalog space is: :catid:user-id.name.CATALOG
COPY-NUMBER =
Version number of the SESAM backup copy of the specified database. The SESAM backup copy of the catalog space must be complete and must be created with the COPY CATALOG utility statement.
COPY-NUMBER = *NONE
The default value *NONE means that you only work with the original database.
COPY-NUMBER = <1..999999>
Version number of a SESAM backup copy of the specified catalog space. If you specify COPY-NUMBER, read access to the database is entered automatically (see ACCESS = *PARAMETERS(...)).
ACCESS =
Specifies which access functions can be used on the database.
ACCESS = *ALL
Allows unrestricted access to the database. Permits read and write access to user data and metadata. The operand value *ALL only refers to the original database.
ACCESS = *PARAMETERS(...)
Restricts access to the database.
The parameters are arranged in a hierarchical structure. If CAT-ADMINISTRATION is permitted, so, implicitly, are WRITE and READ In the same way, WRITE implicitly permits READ.
At least one parameter must be specified with *YES.
If you specified COPY-NUMBER, the value READ = *YES is set automatically. An implicit or explicit ACCESS = *ALL specification is then ignored.
WRITE=*NO and CAT-ADMINISTRATION=*NO must be specified explicitly when ACCESS=*PARAMETERS() is used to specify the access privileges in detail, and READ=*YES and REPLICATION=*NO must also be set (implicitly or explicitly), otherwise an error message will result.
You are not permitted to specify the parameters WRITE and CAT-ADMINISTRATION for backup copies.
READ = *YES
Permits read access to user data and metadata. The data can be queried but not changed.
READ = *NO
Prevents read and write access to user data and metadata.
You cannot select READ = *NO if you have set *YES (the default) for either CAT-ADMINISTRATION or WRITE.
WRITE = *YES
Permits read and write access to user data. Metadata can be read but not changed.
WRITE = *NO
Prevents write access to user data and metadata.
You cannot select WRITE = *NO if you have set *YES (the default) for CAT-ADMINISTRATION.
CAT-ADMINISTRATION = *YES
Permits read and write access to both user data and metadata.
CAT-ADMINISTRATION = *NO
Prevents write access to the metadata in the catalog space of the database. It therefore prevents the use of the following statements:
SQL statements for schema definition and management and memory management
Utility statements
REPLICATION = *YES
Access to a replication of the specified database. You cannot access a normal catalog with this database entry. Only read access and the REFRESH
REPLICATION utility statement are permitted for a replication.
REPLICATION = *NO
No access to a replication.
ENTRY-2 = *NONE / *CATALOG(...)
Opening line of the second database entered in the SQL database catalog. The operands of ENTRY-2 are identical to those of ENTRY-1.
You can enter up to 100 databases in an ADD-SQL-DATABASE-CATALOG-LIST statement. You begin each entry with ENTRY-x = ... where the placeholder x can have any value from 1 to 99, The placeholder “x” must have a different value for each entry. The associated operands in each case are identical to those of ENTRY-1.
ENTRY-100 = *NONE / *CATALOG(...)
Opening line of the 100th database entered in the SQL database catalog.You cannot enter more than 100 databases in one ADD-SQL-DATABASE-CATALOG-LIST statement. If you want to include more than 100 databases in the DBH session, you have to enter this start statement again.