The Database Administrator Language DAL

In a session with the independent DBH, the commands of the Database Administrator Language DAL may be used to give instructions to the independent DBH and exercise control over execution of the session.

DAL syntax

The names of DAL commands and their operands may be abbreviated in accordance with the following rules:

• Specification of the first three characters of a name is sufficient, except in the case of %BIB, %DML and %TERM.

• If more than three characters are specified, you must also specify the correct syntax for the additional characters.

• If more than three characters are specified then the DAL command entry can be abbreviated so that it ends with a hyphen contained in the DAL command. If input is performed via UDSADM, you should note that UDSADM interprets a terminating hyphen as a continuation character.

• Names which are shorter than three characters cannot be abbreviated.

For the UDS-D-specific DAL commands, the first three characters following "&" are sufficient.

The overall length of DAL commands must not exceed 64 characters. This may lead to problems in the case of DAL commands requiring the database name and the realm name to be specified.
Such problems can be avoided by keeping realm names unique throughout the configuration (in which case specifying the database name is superfluous) or by keeping database names and realm names to a reasonable length (see the reference section of the manual "Design and Definition").

UDS/SQL helps correct potential errors arising from DAL commands which are too long, with the UDS0220 message. On receipt of a DAL command, UDS/SQL issues the following message:

% UDS0220 UDS RECEIVED COMMAND

This message contains the DAL command accepted by UDS/SQL as insert (&01). What was actually received by UDS/SQL is apparent from this insert. In particular, it identifies whether any parts of the command which you entered were truncated.

The end of command processing for error-free DAL commands is indicated by the following message:

% UDS0218 UDS COMPLETED EXECUTION OF DAL COMMAND

or, for UDS-D DAL commands, by the following message:

% UDS0832 UDS-D: COMMAND EXECUTED

Errors in DAL commands cause the following message to be issued:

% UDS0209 UDS USER ERROR: COMMAND REJECTED

The message UDS0209 may appear more than once with differing levels of detail concerning the cause. 

Certain DAL commands require transaction-id to be specified: 

transaction-id:

max. eight-digit decimal number assigned by the DBH to identify a transaction; it can be determined by means of the DISPLAY command. 

Command execution

With most of the DAL commands the required function is executed or at least initiated immediately. With the following commands the required function is merely noted:

ACT INCR
ACT DBTT-INCR
ADD DB
ADD RN
DEACT INCR
DEACT DBTT-INCR
DROP DB
DROP RN
NEW PUBSETS
NEW RLOG
CHECKPOINT
ACCESS DB (when in combination with ADD DB)

These pending requests are not executed until a PERFORM command is issued. This enables the user to collect requests in the course of a session. When PERFORM is issued, the DBH can execute all requests in a single operation and only needs to set internal locks once.

The requests may be entered in any order, but the DBH processes them in a defined sequence. The sequence varies according to whether

• the requests refer to databases already attached to the current configuration at the time when the PERFORM is issued

• the requests refer to databases not yet attached to the current configuration at the time when the PERFORM is issued.

For example, in the case of databases which are already attached, ADD RN is executed before DROP DB. This means that any failed realms which have been repaired are made available first, and only then is the entire database detached.

The order in which such requests are executed is shown in the table below. 

The request refers to databases that are already attached	The request refers to databases that are not yet attached
ACT INCR DEACT INCR ACT DBTT-INCR DEACT DBTT-INCR ADD RN= DROP RN= CHECKPOINT [DB=] DROP DB=	ADD DB= CHECKPOINT DB= ACCESS DB=

Table 13: Order of processing requests after PERFORM

The independent DBH recognizes the following DAL commands:

DAL commands for UDS-D all start with the special character &. They are evaluated in UDS-D mode only.
Here they have been incorporated in the alphabetic listing of the other DAL commands.

DAL command	Meaning
ABORT {transaction-id[,OPTION=PTC] |        ALL}	Rolls back the specified open transactions OPTION=PTC: No allowance made for interconfiguration consistency or UDS/SQL openUTM consistency
ACCESS {LOCK | RETRIEVAL | UPDATE},        {DB=dbname |         RN=realm-name[,DB=dbname]}	Handles access locks at database and realm level
ACT {DBTT-INCR,DB=dbname[, RECR=recordref]           [, EXT=extnr][, SCAN={YES | NO} |    INCR,DB=dbname[, RR=realmref]      [, EXT=(nr-pages,min-pages)]}	Activates online extensibility of DBTTs or realms
ADD {DB=[$userid.]dbname[.copy-name]         [,OPTION=[SHARED-RETRIEVAL]     [,OWN-BUFFER-SIZE=n][,ID=bufferid] |   RN=realm-name[,DB=dbname]   PW=password   ADM=admpassword }	Adds databases, realms and passwords
&ADD DISTRIBUTION,    {NODE=processor-name,          CONF=confname[,DB=dbname] |     DB=dbname,SS=subschema-name |     FILE=file-name }	Adds new entries to the distribution table
%BIB	Displays the number of messages to the UDS/SQL DBH forwarded by UDSCON. Counts not only the DML statements coming from the COBOL DML, CALL DML, SQL or KDBS, but also the messages from the runtime systems and from UDSCON.
&CHANGE=DISTRIBUTION,   NODE=processor-name,   CONF=confname	Assigns a configuration to a different host
CHECKPOINT[ DB=dbname[,OPTION=EVEN-WITHOUT- ALOG]]	Writes checkpoints in AFIM logging for individual databases of the configuration or for the entire configuration
CLOSE {RUN-UNITS | CALLS | ADMINISTRATION}	Terminates the current session normally or terminates DCAM administration
&CLOSE DISTRIBUTION	Terminates UDS-D operation
COMMIT transaction-id	Terminates transaction in PTC state and commits updates (FINISH) regardless of inter-configuration consistency or UDS/SQL-openUTM consistency
CONTINUE	Scrolls output of DISPLAY SQL DAL command
DEACT {DBTT-INCR,DB=dbname[, RECR=recordref]|        INCR,DB=dbname[, RR=realmref] }	Deactivates online extensibility of DBTTs or realms
DISPLAY {DB[,RUNID=transaction-id] |           USERS[,DB=dbname] |          SUBSCH[,DB=dbname]                [,LINES={n | ALL}] |          MAINREF[,STATE=BLOCK] |          transaction-id |          REALMS[,DB=dbname][,RN=realm-name]                [,LINES={n | ALL}] |          PP |          FPA [,DB=dbname][,RN=realm-name]              [,LINES={n | ALL}] |          INCR [,DB=dbname][,RN=realm-name]               [,LINES={n | ALL}] |          DBTT-INCR [,DB=dbname                      [, RECR=recordref]]                      [,LINES={n | ALL}] |          PUBSETS |          ALOG [,DB=dbname] }	Lists databases, transactions, subschemas, mainrefs, available free space or program parameters of the configuration or displays information on the online extensibility of realms or DBTTs or displays UDS/SQL pubset declaration
&DISPLAY DISTRIBUTION   [,NODE=processor-name]   [,CONF=confname]   [,DB=dbname]   [,SS=subschema-name]	Displays the distribution table
DISPLAY SQL{,VG=vg-nr |             ,OPTION=ALL[,VG=vg-nr] |             ,OPTION=IDLE[,TIME=z]}	Displays detailed information on one or more SQL conversations
%DML	Displays the number of messages to the UDS/SQL DBH forwarded by UDSCON. Counts not only the DML statements coming from the COBOL DML, CALL DML, SQL or KDBS, but also the messages from the runtime systems and from UDSCON.
DROP {DB=dbname |       RN=realm-name[,DB=dbname] |       PW=password |       ADM=admpassword}	Detaches databases and realms and excludes passwords
&DROP DISTRIBUTION,     {ALL |      NODE=processor-name,         CONF=confname[,DB=dbname][,ALL] |      DB=dbname,SS=subschema-name }	Deletes entries from the distribution table
DUMP [{ALL | STD | transaction-id}]	Generates a DBH memory dump
EXTEND DBTT,DB=dbname, RECR=recordref   [,EXT=extnmbr]	Executes online DBTT extension
EXTEND REALM,DB=dbname,RR=realmref,   EXT=nr-pages	Executes online realm extension
FORGET SQL,VG=con-no	Releases the resources belonging to the SQL conversation numbered con-no
GO {transaction-id | ALL | OLD}	Continues execution of the specified transaction(s)
&LOCK DISTRIBUTION,    {NODE=processor-name |     CONF=confname |     DB=dbname |     SS=subschema-name }	Locks entries in the distribution table
MODIFY {ALOG | ALOG-RES},    DB=dbname[,VALUE={:catid: | PUBLIC}]             [,SHARE={YES | NO}]	Changes the settings of DEFAULT-SUPPORT and RESERVE-SUPPORT of the ALOG files
MODIFY ALOG-SIZE,    DB=dbname,VALUE=([primary][,[secondary]])	Changes the storage allocation of the ALOG files
MODIFY {LOG | LOG-2},         VALUE={:catid: |               PUBLIC |               (priv-vsn-1/device-1                [,priv-vsn-2 device-2                [,priv-vsn-3 device-3]]) |               (vsn-1[,vsn-2[,vsn-3]])}	Changes the volume allocation for an original and duplicate RLOG file to be newly created
MODIFY LOG-SIZE,VALUE=([primary]                        [,[secondary]])	Changes the amount of storage in RLOG files
MODIFY PTCSYNCH,    VALUE=([{WAIT | ABORT | COMMIT}]           [,[{WAIT | ABORT | COMMIT}]])	Modifies the value of the DBH load parameter PTCSYNCH
MODIFY RESERVE,         VALUE={NONE |               :catid: |               PUBLIC |               (priv-vsn-1/device-1                [,priv-vsn-2 device-2                [,priv-vsn-3 device-3]]) |               (vsn-1[,vsn-2[,vsn-3]])}	Changes the reserve volumes for the RLOG files
NEW PUBSETS	Checks and notes new UDS/SQL pubset declaration
NEW RLOG	Selects new RLOG files
PERFORM {NOCANCEL | CANCEL}	Initiates execution of the DROP, ADD, NEW or CHECKPOINT commands Default value: NOCANCEL
&PWD DISTRIBUTION,CONF=confname,    {PWN=new-password |     PWO=old-password |     PWO=old-password,PWN=new-password}	Assigns and changes password
REACT INCR,DB=dbname[, RR=realmref]	Reactivates online realm extensibility
RESET ORDERS	Cancels pending requests
&SAVE DISTRIBUTION,FILE       [:catid:][$userid.]file-name	Saves the distribution table
&START DISTRIBUTION	Starts UDS-D operation
STOP {transaktionskennung | NEW | ALL}	Stops execution of the specified transaction(s)
&SYNCHRONIZE DISTRIBUTION	Terminates secondary subtransactions (STTs) in the PTC state
%TERM	Aborts the session in the quickest way (emergency halt) and optionally generates a complete DBH dump CAUTION! %TERM should be used only if the master task stops accepting DAL commands due to an error.
&UNLOCK DISTRIBUTION,   {NODE=processor-name |    CONF=confname |    DB=dbname |    SS=subschema-name }	Removes locks on entries in the distribution table

Table 14: DAL commands for the independent DBH

The linked-in DBH recognizes the following DAL commands:

DAL command	Meaning
%BIB	Displays the number of base interface blocks processed in this part of the session
%DUMP	Outputs a complete dump of the DBH with edited tables to a file; the program is not aborted

Table 15: DAL commands for the linked-in DBH

All DAL commands are described in detail below.