The DBH and the utility routines DDL compiler, SSL compiler, BGSIA, BGSSIA, BPRIVACY, BMEND, BREORG, BCHANGE, BRENAME and BALTER maintain a database job variable to enhance automatic administration. You can use this job variable to control user requests and programs.
The name of the database job variable has the following format:
UDSSQL.DB.databasename[.copyname][.no]
databasename | |
Name of the database (up to 17 characters) | |
copyname | |
Copy name of a database attached in the DBH in SHARED-RETRIEVAL mode | |
no | |
Single-digit number (1..9) of the database in the case of databases which are used in various sessions in parallel in SHARED-RETRIEVAL mode. | |
The database job variable is always located in the user ID and in the pubset of the DBDIR of the corresponding database.
If no database job variable exists at initialization time, it is created with the following properties:
ACCESS=*WRITE USER-ACCESS=*ALL-USERS BASIC-ACL=*NONE (simple access control list)
If the job variable is to be used with other properties, you must create it with the required properties before the DBH starts or before the utility routine executes. When using job variables, access control can be implemented using standard resources (e.g. Basic-ACL, Guards).
Before a job variable is used in a foreign user ID, you must either create it yourself or take appropriate measures (e.g. co-ownership in a foreign user ID) to ensure that it can be created dynamically.
Please also take note of “Information on using the job variables”.
Special conditions in the case of database in SHARED-RETRIEVAL mode
When a database is opened in SHARED-RETRIEVAL mode, the DBH first checks whether suitable job variables with numbering already exist. If one of these job variables contains the current name of the configuration, it is used, otherwise the DBH selects a job variable name which has not yet been used, creates the corresponding job variable, and enters the current configuration name. Job variables which are empty or have not yet had configuration names assigned are not used because when databases are used in parallel in multiple DBH sessions it must be ensured that a different database job variable is used by each DBH session. A corresponding job variable with no number is included in this process and reserved with priority in the event of free selection.
Database job variables in SHARED-RETRIEVAL mode are always initialized fully when the database is attached.
In the case of genuinely parallel SHARED-RETRIEVAL mode it is advisable to configure the database job variables before using them and to supply the configuration name of the DBH session (columns 61-68).
No special rules need to be observed when numbering the job variables. If all of the 10 possible job variables are in use and are therefore assigned to other configurations, no job variable can be created for the database concerned. A message to this effect is issued by the DBH.
Structure of the database job variable
The database job variable UDSSQL.DB.databasename.[.copyname][.no] is assigned values as follows:
Column | Contents | Meaning |
1-2 | 01 | Version identifier of the session job variable’s layout |
3-19 | ccccccccccccccccc | Database name (1) |
20-26 | cccccc / 'BLANK' | Copy name (2) |
27-32 | cccccc | DB layout version |
33 | C / I / 'BLANK' | Consistency (3) |
34-40 | 'BLANK' | Reserved |
41-50 | Processing status (4): | |
UPDATE / RETR / WARMSTART / | – Attach mode for the DBH | |
OPEN / | – Attach mode for a utility routine | |
DROP / CLOSE / ERROR | – Cause of the last termination in the case of the DBH or a utility routine | |
51 | 'BLANK' / A | Activation of ALOG (5) |
52 | 'BLANK' / O | Identifier for online backup capability (6) |
53-60 | DBH or utility routine (7) | |
DBH / | – Independent DBH | |
LKIN-DBH / | – Linked-in DBH | |
UTIL-DBH / | – Utility routine with linked-in DBH (DDL/SSL compiler, BGSIA, BGSSIA, BPRIVACY) | |
utility | – Name of a modifying utility routine | |
61-68 | cccccccc / 'BLANK' | Configuration name of the DBH session (8) |
69-72 | cccc / 'BLANK' | Default catalog of the DBH user ID (9) |
73-81 | $cccccccc / 'BLANK' | User ID of the DBH session (with $) (9) |
82-89 | nnnnnnnn / 'BLANK' | Session section number (10) |
Start of processing (11) | ||
90-99 | yyyy-mm-dd | Date |
100-107 | hh:mm:ss | Time |
End of processing (12) | ||
108-117 | yyyy-mm-dd | Date |
118-125 | hh:mm:ss | Time |
Last ALOG change (13) | ||
126-135 | yyyy-mm-dd | Date |
136-143 | hh:mm:ss | Time |
144-152 | nnnnnnnnn / 'BLANK' | ALOG sequence number (14) |
153-162 | nnnnnnnnnn / 'BLANK' | Size of the ALOG file (15) |
163-167 | nnnnn / 'BLANK' | Extents of the ALOG file (16) |
168-182 | 'BLANK' | Reserved |
Last change job variable | ||
183-192 | yyyy-mm-dd | Date |
193-200 | hh:mm:ss | Time |
Table 25: Structure of the database job variable for UDS/SQL
Comments | |
(1) | Database name is the name of the database which is also contained in the job variable name. |
(2) | Copy name is only filled with values in the shadow database. |
(3) | Consistency is only filled with values by the DBH and shows whether the database is consistent ("C") or inconsistent ("I"). In this sense a database is inconsistent when the DBH is currently modifying the database and possibly not all changes have been written back to the database files. However, the database can also be inconsistent if processing by the DBH was terminated abnormally. Warm-starting the database generally returns it to a consistent status. |
(4) | Processing status shows the attach mode or the cause of the last termination. Temporary access restrictions (e.g. because of DAL ACCESS) or restrictions to the operating mode (because, for example, the RLOG file cannot be used) are not displayed. ERROR is set if the database is switched off under control while it is inconsistent or processing of the database has been terminated because of other errors. In the latter case it is possible that the database is still consistent. However, in some cases it is possible that the DBH session is terminated abnormally without it being possible to update the processing status. The database is then generally still inconsistent and the processing status remains UPDATE. When a subsequent warm start is performed by the DBH, the processing status WARMSTART is set, and at the end of the warm start the status required for processing (e.g. UPDATE) is entered. Modifying utility routines supply the statuses OPEN, CLOSE and, if required, ERROR. In some error situations controlled program termination is not possible for the utility routines. In such a case the ERROR status can also not be set correctly. The job variable then remains in the OPEN status even after the utility routine has terminated. It is also possible that an error occurs in the last phase of utility routine termination after the job variable has already been supplied with the CLOSE status. In this case the job variable is, if possible, filled with the ERROR status. |
(5) | Activation of ALOG shows whether ALOGGING is activated ("A") for the database or not (blank). Current processing in the DBH can take place without ALOGGING if, for example, the database is attached in SHARED-RETRIEVAL mode. |
(6) | Identifier for online backup capability |
(7) | DBH or utility routine is filled with information by the DBH or utility routine when the database is attached and then remains unchanged. |
(8) | Configuration name of the DBH session shows the current or the last name of the DBH configuration. The item is filled with information when the database is attached and then remains unchanged. Utility routines which do not use the linked-in DBH enter blanks. In SHARED-RETRIEVAL mode a database job variable should be created before the database is attached to a DBH session and filled with the configuration name. |
(9) | Default catalog of the DBH user ID and User ID of the DBH session contain the values of the relevant DBH session. These values can be used for unique access to the session job variable. Utility routines which do not use the linked-in DBH enter blanks. |
(10) | Session section number is filled with the current value of the session when the database is attached, and the DBH deletes it with blanks when the database is detached. Utility routines which do not use the linked-in DBH enter blanks when the database is attached. |
(11) | Start of processing is filled when the database is attached (DBH) or opened (utility routine) and then remains unchanged. |
(12) | End of processing is filled when the database is detached (DBH) or closed (utility routine). When utility routines terminate abnormally, the data provided depends on whether the job value as a whole is updated. In the UPDATE and RETR status the item contains blanks. |
(13) | Last ALOG change shows the time of the last ALOG change or (re)activation of ALOGGING. The date is retained even when ALOGGING is disabled. |
(14) | ALOG sequence number is filled with values by the DBH or utility routines in the event of a change of ALOG if ALOGGING is enabled. |
(15) | Size of the ALOG file shows the size of the used part of the ALOG file in PAM pages. This size can differ slightly from the file size as seen by the DMS. This deviation can be caused either by rounding on account of the size of the allocation unit used (3, 4 or 32 PAM pages) or because as a result of doubling the secondary allocation (cf. class-2 system parameter DMMAXSC or the MAXIMAL-ALLOCATION parameter in ADD-/MODIFY-MASTER-CATALOG-ENTRY) a current file extension is larger than the extension requested by UDS/SQL. The item is filled with a current value only by the DBH. Utility routines which do not use the linked-in DBH enter blanks. |
(16) | Extents of the ALOG file shows the number of extents of the ALOG file. The item is filled with a current value only by the DBH. |
Output example:
%01MDV29B6 004.00C UPDATE A DBH MDV29B6 IUDS$UDSDEV 024AD708EF2019-01-2512:36:10 2019-01-2512:34:520000000010000000 19200001 2019-01-2512:36:10
Where:
- ALOG sequence number = 000000001
- Size of the ALOG file = 0000000192
- Extents of the ALOG file = 00001