This document covers the following:
Where appropriate, specific sections are used when there are substantial handling differences between platforms (UNIX and Windows).
All commands to utilities are read from stdinor SYS$INPUT, and the output is directed to stdout or SYS$OUTPUT. The standard input and output may be directed to files that are normally supported by the operating system. By default, the standard output does not include the utility parameters specified, but if you set the environment variable ADAPARLOG to YES, the parameter specifications are copied to stdout/SYS$OUTPUT, provided the parameters are not specified interactively.
If the utility produces one or more output files, the environment variable/logical name corresponding to each output file must be set to a legal file name, before the utility is started. For detailed information concerning the assignment of environment variables/logical names, refer to the utilities in question. The output files produced by each utility and the environment variable/logical name assignments for these files are described near the beginning of each utility chapter. If the environment variable/logical name for an output file is not set before the utility is started, the output file is created in the current directory, and the name of the output file is the same as the environment variable/logical name. If the environment variable/logical name for a command log file or a protection log file is not set before the utility is started, the output file is created in the current directory, and the name of the output file is the same as the environment variable/logical name with a sequence number appended.
Several utilities also require environment settings for user exits and hyperexits. For more details, refer to the section User Exits and Hyperexits.
The utilities may be executed interactively or in the background.
You must have the necessary permissions in order to execute a utility. The installation sets the permissions as follows: utilities may be executed by the Software AG products administrator user, e.g. sag, and by all users that belong to the corresponding group, e.g. sag.
Before you execute a utility, you must set the required logical names if the names of the files to be used differ from the default values.
The procedure dbgen.com generates a file called assign.com when it creates a new database. This file can be sourced in the shell to set the logical names for the container files, command log and protection log. To source this file, change your working directory to your database directory and enter:
@assign.com
Utility input lines contain control statements that consist of strings defining the settings of parameters, a function to be executed or both.
All functions and parameters are described in the documentation.
The utilities are located in the directory ADABAS$VERSION. You can execute the utility directly by specifying its name at the operating system prompt. The following examples assume that the foreign command ADAxxx = = $ADABAS$VERSION:ADAxxx.exe is defined.
You execute a utility interactively by specifying its name followed by carriage return at the operating system prompt.
When a utility starts, it displays an informational message consisting of date, time and version number. It then prompts with its name and a colon for input of control statements:
%ADAREP-I-STARTED, 18-JUL-2005 11:39:49, Version 5.1.1 adarep:
In interactive mode, the input line starts directly after the utility prompt.
You can extend the input over several physical input lines by terminating each line with a carriage return. The utility outputs with its name and a colon at the start of each continuation line.
The control statements also be specified at the call level, e.g. for the utility adarep:
adarep dbid=20 summary
The control statements can also be redirected from an input file. If, for example, the file rep.in contains the lines:
dbid=20 summary
then you can run adarep with these two control statements by specifying:
define SYS$INPUT rep.in ADAREP
The output produced by the utility usually goes to SYS$OUTPUT, which means that it can be redirected. So, for example, to redirect the output of the sample adarep call to the file rep.out, specify:
define SYS$INPUT rep.in define SYS$OUTPUT rep.out ADAREP deassign SYS$INPUT deassign SYS$OUTPUT
Note:
Setting the environment variable ADAPARLOG to YES may help you to
find errors in the parameter specification - it displays the parameters as
specified interactively.
The utilities may be executed interactively or in the background.
You must have the necessary permissions in order to execute a utility.
The installation sets the permissions as follows: utilities may be executed by
the Software AG products administrator user, e.g. sag, and by all users that
belong to the corresponding group, e.g. sag. If this group is not your current
group, it is recommended that you change the group with the
newgrp command before you execute a utility
(including ADANUC); failing to do so may lead to other users encountering
permission problems because the group for IPC resources created by the user is
the current group of the user who executes the utility, and some IPC resources
allow access for only the group.
Before you execute a utility, you must set the required environment variables if the names of the files to be used differ from the default values (see the section "Environment Variables" in this chapter).
The utility adadba (DBA Workbench) and the program dbgen generate a file called assign.bsh (for Bourne shell and Korn shell) or assign.csh (for C shell) when they create a new database. This file can be sourced in the shell to set the environment variables for the container files, command log and protection log. To source this file, change your working directory to your database directory and enter:
. ./assign.bsh
If you do not set the environment variables for container files externally, the utilities extract the settings themselves via the configuration files ADABAS.INI and DBxxx.INI, as described in the Adabas Extended Operation Manual.
Utility input lines contain control statements that consist of strings defining the settings of parameters, a function to be executed or both.
All functions and parameters are described in the documentation, as well as in help messages.
The utilities are located in the directory $ADADIR/$ADAVERS. If this directory is defined in the PATH environment variable, you can execute the utility directly by specifying its name at the operating system prompt, otherwise you have to precede the utility name by "$ADADIR/$ADAVERS". The following examples assume that the directory name $ADADIR/$ADAVERS is defined in the PATH environment variable.
You execute a utility interactively by specifying its name followed by carriage return at the operating system prompt.
When a utility starts, it displays an informational message consisting of date, time and version number. It then prompts with its name and a colon for input of control statements:
%ADAREP-I-STARTED, 18-JUL-2005 11:39:49, Version 5.1.1 adarep:
In interactive mode, the input line starts directly after the utility prompt.
You can extend the input over several physical input lines by terminating each line with a backslash ("\") followed by carriage return. The utility outputs the prompt ">" at the start of each continuation line.
The control statements also be specified at the call level, e.g. for the utility adarep:
adarep dbid=20 summary
The control statements can also be redirected from an input file. If, for example, the file rep.in contains the lines:
dbid=20 summary
then you can run adarep with these two control statements by specifying:
adarep <rep.in
The output produced by the utility usually goes to stdout, which means that it can be redirected. So, for example, to redirect the output of the sample adarep call to the file rep.out, specify:
adarep <rep.in >rep.out
Notes:
adadcu fields 'NEW RECORD',AA,AB end_of_fields
Invalid, because it is equivalent to
adadcu fields NEW RECORD,AA,AB end_of_fields
The quotes are missing.
adadcu fields \'NEW RECORD\',AA,AB end_of_fields
Invalid, because it is equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
The literal must be specified on one line.
adadcu fields \'NEW\ RECORD\',AA,AB end_of_fields
Valid, this is equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
adadcu "fields 'NEW RECORD',AA,AB end_of_fields"
Invalid, because it is equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
fields and end_of_fields must be specified on separate lines.
adadcu fields "'NEW RECORD'",AA,AB end_of_fields
or
adadcu fields "'NEW RECORD',AA,AB" end_of_fields
Valid, both are equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
It is possible to switch the parameter input for a utility from the command line to standard input by entering a '+' character (plus sign) after the last parameter specified in the command line.
adafdu dbid=35 file=36 + <employee.fdu
The utilities may be executed interactively or in the background.
In order to be able to execute Adabas utilities of an installed Adabas version, some environment variables must be set. This is done when you select or when you start the Adabas Workbench.
If you want to execute Adabas commands from the standard command prompt, you have the following possibilities:
You can set the environment variables required for Adabas as system environment variables by selecting Set Adabas System Environment. You can delete these system environment variables again by selecting Unset Adabas System Environment.
If you don’t want to set the environment variables as system environment variables, you can execute the command startenv.cmd in the bin folder of the current Adabas version. You can find out the name of the folder by right-clicking on the Adabas Command Prompt and selecting Properties.
Note:
The button and the
command startenv.cmd were not available in Adabas
Version 3.3. Therefore, if you want to run Adabas Version 3.3 and Version 5.1
(or higher) in parallel, the installation sets the system environment variables
correctly for Adabas Version 3.3. Then the setting is correct for executing
Adabas Version 3.3 utilities via the default command prompt or by the Adabas
Version 3.3 workbench. Adabas Version 5.1 (or higher) utilities can be executed
as described above.
Before you execute a utility offline, you must set the required environment variables if the names of the files to be used differ from the default values (see the section "Environment Variables" in this chapter).
The utility adadba (DBA Workbench) generates a file called assign.bat when it creates a new database. This file can be sourced in the shell to set the environment variables for the container files, command log and protection log. To source this file, change your working directory to your database directory and enter:
CALL assign.bat
If you do not set the environment variables for container files externally, the utilities extract the settings themselves via the configuration files ADABAS.INI and DBxxx.INI, as described in the Adabas Extended Operation documentation.
Utility input lines contain control statements that consist of strings defining the settings of parameters, a function to be executed or both.
All functions and parameters are described in this manual, as well as in help messages.
The utilities are located in the directory %ADADIR%\%ADAVERS%. If this directory is defined in the PATH environment variable, you can execute the utility directly by specifying its name at the operating system prompt, otherwise you have to precede the utility name by "%ADADIR%\%ADAVERS%". The following examples assume that the directory name %ADADIR%\%ADAVERS% is defined in the PATH environment variable.
You execute a utility interactively by specifying its name followed by carriage return at the operating system prompt.
When a utility starts, it displays an informational message consisting of date, time and version number. It then prompts with its name and a colon for input of control statements:
%ADAREP-I-STARTED, 18-JUL-2005 11:39:49, Version 5.1.1 adarep:
In interactive mode, the input line starts directly after the utility prompt.
You can extend the input over several physical input lines by terminating each line with a backslash ("\") followed by carriage return. The utility outputs the prompt ">" at the start of each continuation line.
The control statements also be specified at the call level, e.g. for the utility adarep:
adarep dbid=20 summary
The control statements can also be redirected from an input file. If, for example, the file rep.in contains the lines:
dbid=20 summary
then you can run adarep with these two control statements by specifying:
adarep <rep.in
The output produced by the utility usually goes to stdout, which means that it can be redirected. So, for example, to redirect the output of the sample adarep call to the file rep.out, specify:
adarep <rep.in >rep.out
Note:
Blanks are equivalent to a line feed in interactive input - if a
blank should appear in a parameter value, it must occur between double
quotes.
adadcu fields 'NEW RECORD',AA,AB end_of_fields
Invalid, because it is equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
The literal must be specified in one line.
adadcu "fields 'NEW RECORD',AA,AB end_of_fields"
Invalid, because it is equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
fields and end_of_fields must be specified in separate lines.
adadcu fields "'NEW RECORD'",AA,AB end_of_fields
or
adadcu fields "'NEW RECORD',AA,AB" end_of_fields
valid, both are equivalent to
adadcu fields 'NEW RECORD',AA,AB end_of_fields
It is possible to switch the parameter input for a utility from the command line to standard input by entering a '+' character (plus sign) after the last parameter specified in the command line.
adafdu dbid=35 file=36 + <employee.fdu
If the option LOCAL_UTILITIES is not set for an active nucleus of a given Adabas database, the database can be accessed remotely by certain Adabas utilities, using SOFTWARE AG's product ENTIRE NET-WORK or NET-WORK ACCESS, provided that the architecture of the local and remote machines is identical (for example, that both machines use byte-swapping). The utilities that can access a database remotely are:
ADACMP
ADADBM
ADAFDU
ADAREC
ADAREP
ADATST
ADAULD
For ADADBM and ADAULD, only the functions which are allowed when the nucleus is running can be executed remotely.
Note:
ADAFDU cannot be executed remotely if you define an ADAM file or if
you specify the parameter FORMAT.
The arguments of a function are called parameters. Parameters may have various values. A parameter that has only two possible values, which are logically complementary, is called a switch.
Functions are represented by reserved keywords. Three types of functions are used:
Functions requiring no arguments;
Functions requiring one argument;
Functions requiring more than one argument.
A function that does not require an argument is a switch, and can be enabled or disabled by keywords such as LOCK and UNLOCK.
Arguments are of the following type:
Strings
A string is a sequence of valid ASCII characters with the exception
of comma `,', carriage return <CR>, semicolon `;' opening `(' and closing
brackets `)', which are all regarded as string delimiters. Embedded blanks and
tabs are removed. The backslash `\' can be used as an escape character.
Most strings are converted to upper case. Instead of the equals sign, it is also possible to specify a colon ‘:’. The difference is that strings following a colon are not converted to upper case. Although a colon may also be specified for other parameters where the utility syntax description does not allow a colon, it is recommended to use a colon only in these cases; otherwise the results of the parameter specification may be undefined.
adatst: rb=test adatst: rb <<<<<< RECORD BUFFER >>>>>> 00000000 54455354 ........ ........ ........ TEST............ adatst: rb:test adatst: rb <<<<<< RECORD BUFFER >>>>>> 00000000 74657374 ........ ........ ........ test............
If you specify “rb=test”, the string “test” is converted to upper case, while it is not converted if you specify “rb:test”.
Keywords
A keyword is a predefined string.
Numbers
A number is a string of digits representing an unsigned integer.
Numbers can be entered in hexadecimal format by preceding the digits with the
two characters "0x".
Number ranges
A number range is a number followed by a hyphen (-) and another
number.
Lists of keywords, strings, numbers or number ranges
A list is a sequence of keywords, strings or numbers, separated by
commas and enclosed in brackets.
Arguments are specified according to the following rules:
The first argument is specified after the equal sign `=' following the function keyword;
Subsequent arguments are specified by using keywords followed by an equal sign and a value.
adadbm: recover
adadbm: renumber = (3,14)
adadbm: reuse = (isn,ds), file = 6
adarec: regenerate = * adarec: plog = 654 adarec: checkpoint = synp adarec: block = 0x1A
The list of arguments may be continued in the following lines. In the case of a multi-function utility, the function is executed if this list is complete and correct.
If an argument is mandatory or has a default value, this is indicated by the characters `M' or `D' in the list of arguments at the beginning of the utility description.
The current values of all parameters that were set or preset can be displayed by entering an asterisk `*':
adarep:*<cr>
%ADAREP-I-PARSET setting of COUNT=<set> %ADAREP-I-PARSET setting of DBID=5 %ADAREP-I-PARSET setting of FDT=<set> %ADAREP-I-PARSET setting of FILES=(10)
If a switch is set, it is displayed as "<set>".
Some utilities (ADACLP, ADADBM, ADAREP) require arguments in the form of an absolute date or date and time string. The string used must correspond to the following absolute format:
dd-mmm-yyyy[:hh:mm:ss]
For more detailed information about how to use absolute dates and times, please refer to the individual utilities concerned.
Depending on the number of functions that can be performed during one run, a utility is called a single-function or multi-function utility.
In a single-function utility, the correctness of each keyword value is checked after it is entered. The completeness of the set of arguments is checked when the utility is executed by pressing CTRL/D (UNIX) on a line by itself or by pressing CTRL/Z followed by a carriage return (Windows) or by pressing CTRL/Z (OpenVMS). A single-function utility is terminated after the execution of a function.
A multi-function utility accepts sequences of function specifications and/or parameter settings. The sequence must correspond to a certain logical order. A function is executed when this sequence is complete and correct. The execution of a function in a multi-function utility is terminated with a message indicating successful or non-successful completion. The utility itself does not terminate after the execution of a function.
The QUIT control statement or its abbreviation "Q" is used to terminate a utility. Also EXIT can be used as a synonym for QUIT.
Note:
Utility control parameters are always converted to upper case. It is,
therefore, also possible to specify QUIT and EXIT in lower
case. QUIT and EXIT can also be specified in the FDT parsing
mode, for example, after specifying the FIELDS parameter. However, no
conversion to upper case is done in the FDT parsing mode after specifying the
LOWER_CASE_FIELD_NAMES parameter; in this case, you must specify QUIT
or EXIT in upper case.
In a single-function utility, QUIT aborts the function and terminates the utility. An EOF (CTRL/D on a line by itself [UNIX] or CTRL/Z followed by a carriage return [Windows]or CTRL/Z [OpenVMS]) first executes the function and then terminates the utility.
In a multi-function utility, QUIT terminates the utility. If entered while setting the function parameters, QUIT aborts the function and terminates the utility. However, an EOF tries to execute the function before termination. If some of the parameters required have not been specified, the utility requests their entry before the function is executed.
In all cases of termination, a statistical summary of the IOs made on the input and output files is given and an informational message is issued with utility name, date, time and elapsed time e.g.:
%ADAFRM-I-IOCNT, 500 IOs on dataset WORK %ADAFRM-I-IOCNT, 800 IOs on dataset DATA %ADAFRM-I-IOCNT, 600 IOs on dataset ASSO %ADAFRM-I-TERMINATED, 28-JUL-2005 11:39:50, elapsed time: 00:00:51
If a utility terminates successfully, the final TERMINATED message is displayed and the program exit status is set to 0, otherwise an ABORTED message is issued and the program exit status is set to a non-zero value. Multi-function utilities always terminate successfully if they are used interactively without input redirection.
In some cases, utilities display the TERMINATED message and deliver a non-zero exit status to indicate an exception, for example the utility ADAVFY if an error has been found, or the utility ADACMP if records were rejected.
Incorrect sections of utility commands are indicated by up arrows in the following line and an error message in a subsequent line. Errors are processed from left to right.
If an error occurs in a sequence of parameter settings, all settings before the error are executed.
adadbm: refresh = 30
^
%ADADBM-E-NOTLOAD, file not loaded
The position of the error in the input line is indicated by an up arrow in the following line.
The Adabas nucleus or utilities usually work with sequential files for input and output. In addition to these sequential files, there are also internal files with a uniform internal Adabas format (Protection Log, for example), and external files with a user-defined format (decompressed data, for example).
Internal Adabas sequential files may be directed to the file system, a raw section or a tape device. Some Adabas sequential files can be directed to a named pipe. The following table lists all of the internal Adabas sequential file types, the ADADEV keywords for raw device access, and the corresponding environment variables that can be set to a disk section (UNIX only), tape device or file system. If the environment variable is not defined, Adabas uses a file in the current working directory with the name of the environment variable.
| Sequential File Type | ADADEV Keyword | Environment Variable |
|---|---|---|
| Protection Log | PLG | DEVPLGx, NUCPLGx(*), PLPLEX, PLPPLGx, RECPLGx |
| Command Log | CLG | CLPCLGx, DEVCLGx, NUCCLGx |
| Backup File | BCK | BCK00nx, DEV00nx, ULD00nx |
| Backup File Copy | BCKOUT | BCKOUTx, DEVOUTx |
| Compressed Data | DTA | CMPDTAx, DCUDTAx, DEVDTAx, MUPDTAx, ULDDTAx |
| Descriptor Value Table | DVT | CMPDVTx, DEVDVTx, MUPDVTx, ULDDVTx |
| ADAMUP Temporary Data | MUPTMP | MUPTMPx |
| ADAMUP Log (DTA/DVT) |
MUPLOG | DEVLOGx, MUPLOGx |
| Reorder File | ORDEXP | DEVEXPx, ORDEXPx |
| Utility Error File | ERR | ERRINx, CMPERRx, DCUERRx, DEVERRx, INVERRx, MUPERRx, RECERRx, |
where: n = 1 - 9; x is omitted or is greater than 1.
(*)
NUCPLG cannot be on tape.
The following Adabas sequential files must be located in a file system:
| Sequential File Type | Environment Variable |
|---|---|
| ADAMUP ISN List | MUPISN |
| ADAMUP temporary working space for LOB processing | MUPLOB, MUPLBI |
| Field Definition Data | FDUFDT, CMPFDT, DCUFDT |
| Decompressed Raw Data | CMPIN, DCUOUT |
The disk-space management utility ADADEV can be used to manage files in raw disk sections (see ADADEV for further information [UNIX only]).
Adabas sequential files have different internal formats on high-oder-first and low-order-first platforms, but they are compatible between all platforms with the same byte order.
| Platform 1 | Byte Oder | Platform 2 | Byte Order | Compatible |
|---|---|---|---|---|
| Solaris | High-order-first | AIX | High-order first | Yes |
| LINUX (Intel) | Low-order-first | Windows | Low-order-first | Yes |
| Solaris | High-order-first | Windows | Low-order-first | No |
| OpenVMS | Low-order first | AIX | High-oder first | No |
Only the following files are compatible between all platforms:
Decompressed data files
Pure text files, for example FDT files
If you want to exchange date between high-order-first and low-order-first platforms, you should proceed as follows:
Unload with ADAULD
Decompress with ADADCU
Compress with ADACMP
Load with ADAMUP
If this is not possible because the decompressed records are too large, you must write a program that reads data from the source database. The program can either write data to an intermediate file in the file system, from where it is read by a second program which writes data to the target database, or it can store the data directly in the target database via Entire Net-Work.
Note:
Use the cvt_fmt utility on OpenVMS if the decompression was done on
an OpenVMS Alpha system.
Named pipes can be used to save storage space when the output of a utility is to be processed by another utility or application, or if the input of a utility is output by another utility or application (not on OpenVMS). Named pipes can be used for all Adabas sequential files except MUPDTA, MUPDVT, MUPISN, MUPLBI, MUPLOB, MUPLOG, MUPTMP, NUCPLG, ORDEXP, PLPLEX, PLPPLG, ULD00n.
Named pipes under Windows are transient objects. If an environment variable contains the name of a named pipe (for example \\.\pipe\anyname), the utility that attempts to write to the named pipe will create it implicitly. Then this utility waits for a predefined amount of time until the reading utility comes up and begins to read from the named pipe. If the time elapses without the reading utility coming up, the writing utility aborts with an I/O error.
If the space allocated to a sequential file becomes exhausted while it is being created by a utility, Adabas attempts to continue the file in another free slot. This applies to all sequential files that are located on raw device if the allocated or pre-allocated space becomes exhausted or if the file system where the sequential file is located becomes full. Multiple environment variables may be used with this technique, with a counter being appended to the name of the environment variable.
setenv NUCPLG /dev/rdsk/c4d0s2 setenv NUCPLG2 /usr/adabas/PLOG_2 setenv NUCPLG3 /dev/rdsk/c7d0s2
These three devices are used for the Protection Log during a nucleus session.
An alternative method is to set all of the file/device names within one environment variable:
Note:
For Unix platforms the delimiter is a blank, and on Windows
platforms it is the semicolon character ";".
setenv NUCPLG "/dev/rdsk/c4d0s2 /usr/adabas/PLOG_2 /dev/rdsk/c7d0s2"
Adabas starts with the first environment variable (in this case NUCPLG), or with its default if the environment variable is not set (the default is a file in the current directory with the same name as the environment variable). When the end of the file is reached, or when the file system becomes full (in cases where a file system is used), the file will be closed, and the next environment variable (NUCLPG2) will be translated and the associated file or disk section opened. Then it allocates free space from that disk section to be used for the next extent. If a subsequent environment variable does not exist (e.g. NUCPLG4), Adabas will wrap around to the first disk section (NUCPLG).
If only one environment variable is defined and assigned to a disk section, the subsequent file extents will all be created in the same disk section. If only one environment variable is defined and assigned to a file in a file system, Adabas cannot continue if the file system becomes full.
When a switch occurs from one file extent to another, the closed extent usually gets renamed by appending the extent number to its name. For example, a file extent called PLG.3 in a disk section will be renamed to PLG.3(1), and a file extent called /tmp/BCK_DB in a file system will be renamed to /tmp/BCK_DB(1). The name of the new file extent contains the new file extent number. Thus, in the example just mentioned, the new file extent in the disk section is named PLG.3(2) and the new file extent in the file system is named /tmp/BCK_DB(2).
Note:
The size of the value of an environment variable is
limited to 512 bytes or more, depending on the operating system. If you specify
a large number of extents in one environment variable, it may happen that the
value of the environment variable is truncated, and this will result in an
error. In this case, you must specify the extents in separate environment
variables.
define NUCPLG ADABAS$MAIN:[DB012]NUCPLG_X_Y define NUCPLG2 define NUCPLG3
where X is the Adabas session ID and Y is the PLOG number from 2 to 9.
There is one important restriction that applies to using the utilities with multiple extent files: input redirection is not allowed if more than one file extent is required and only one environment variable is set to only one value. In this case, the utility aborts with a message of the following form:
%ADABCK-E-SFNOTPO, subsequent file extents not possible with input redirection
The following modes will work successfully:
adabck <RETURN> dbid=5, dump=4 <RETURN> <CTRL/D>
adabck <RETURN> dbid=5, dump=4 <RETURN> <CTRL/Z><RETURN>
adabck <RETURN> dbid=5, dump=4 <CTRL/Z>
adabck dbid=5 dump=4
adabck dbid=5 dump=4 &
The utility process will be stopped if a subsequent tape is required. In this case, the user can bring the job into the foreground in order to enter a valid device name and continue processing.
When reading sequential files that are split into multiple extents, Adabas checks whether an extent is finished and prompts for the file/device path name of the next extent at which reading is to continue, if just the normal environment variable is given.
ADAREC regenerates a Protection Log that is spread over 2 sections. The environment variable RECPLG must point to the first extent of protection log 5 (PLG.5(1)). Once it has been processed, ADAREC prompts for the file/device path name of the next extent:
Enter next file/device path name to continue PLG.5(2)
The file extent can be either in a disk section or a file system or on a tape device. After opening the subsequent extent, Adabas checks to see whether the given extent is the one it expects. If it is not the correct one, an error message is displayed and the prompt for the correct file/device path name is displayed again. If such a subsequent prompt appears, you can abort further processing by entering "quit". Situations can arise where no subsequent protection log extent exists although Adabas expects one. In this case, you can enter "close" to terminate the processing of the current protection log file without error.
It is also possible to process the files in one go, without prompting, when using `counted' environment variables. In this case, the same technique is used as when creating the files. The file(s) may be located on raw device, file system or tape device.
C Shell:
setenv RECPLG /dev/rmt/0m setenv RECPLG2 /dev/rdsk/c10d0s2 setenv RECPLG3 /dev/rdsk/c7d0s2
Bourne Shell, Korn Shell:
RECPLG = /dev/rmt/0m export RECPLG RECPLG2 = /dev/rdsk/c10d0s2 export RECPLG2 RECPLG3 = /dev/rdsk/c7d0s2 export RECPLG3
Windows:
set RECPLG=\\.\TAPE0 set RECPLG2=C:\BCK_2 set RECPLG3=D:\BCK_3
OpenVMS:
define RECPLG SAG$ROOT:[...]TAPE0 define RECPLG2 SAG$ROOT:[...]BCK_2 define RECPLG3 SAG$ROOT:[...]BCK3
An alternative method is to set all of the file/device names within one environment variable.
If the mass update utility ADAMUP uses a data file (DTA) that is split into 2 extents, then the following can be set:
C Shell:
setenv MUPDTA "/dev/rdsk/c5d0s2 /usr/adabas/DTA_2"
Bourne Shell, Korn Shell:
MUPDTA = "/dev/rdsk/c5d0s2 /usr/adabas/DTA_2"export MUPDTA
Windows:
set MUPDTA=\\.\TAPE0;C:\adabas\DTA_2
The Adabas utilities can read from and write to tape devices directly. In order to make use of this ability, the corresponding environment variable must be set to point to the tape device-name. The utilities use their own tape format, which is not compatible with other tape handling utilities.
The environment variable must point to the name of the tape device before the utility is started. If, for example, you want to use the backup utility ADABCK on an HP-UX machine, you should enter the following:
C Shell:
setenv BCK001 /dev/rmt/0m
Bourne Shell, Korn Shell:
BCK001 = /dev/rmt/0m export BCK001
If, for example, you want to use the backup utility ADABCK on Windows to write to a tape device \\.\TAPE0, you should enter the following:
Windows:
set BCK001=\\.\TAPE0
The device name of a tape drive has the form \\.\TAPE<tape id>, where <tape id> is the number of the tape device starting from zero.
It may be necessary for very large files to be spread over two or more tapes. If a tape gets full, the utility informs the user of the situation and prompts for input. After changing the tape, the user must enter the device name again in order to continue.
%ADABCK-I-TDEVFU, end of tape reached, rewinding
Insert new tape and enter device name, [/dev/rmt/0m] (UNIX)
Insert new tape and enter device name, [\\.\TAPE0] (Windows)
A similar method is used when multiple tapes are read. The utility checks to see whether the tapes are mounted in the correct sequence. If the tapes are inserted in the wrong sequence, the utility issues an error message and prompts for input.
%ADABCK-F-ILLSUB, illegal subsequent tape detected,
present 1, expected 3
In order to continue, the user must mount the correct tape and enter the device name (the name of the tape device does not have to be the same as the first). Standard file names or raw sections may not be entered.
In order to support automatic tape change without prompting, you can set multiple tape devices within one environment variable. This means, for example, that if the first tape selected gets full, Adabas will automatically switch to the second etc. This mechanism is supported for both reading and writing tapes.
setenv BCK001 "/dev/rmt/0m /dev/rmt/1m" setenv RECPLG "/dev/rmt/0m /dev/rmt/1m"
or
setenv BCK001 /dev/rmt/0m setenv BCK0012 /dev/rmt/1m setenv RECPLG /dev/rmt/0m setenv RECPLG2 /dev/rmt/1m
set BCK001=\\.\TAPE0;\\.\TAPE1 set RECPLG=\\.\TAPE0;\\.\TAPE1
A large database is to be dumped onto the two tapes selected. If two tapes are not enough, Adabas will prompt for a third one.
There is one important restriction that applies to using the utilities with tapes: input redirection is not allowed if more than one tape is required and the automatic tape feature described above is not used. In this case, the utility aborts with the following message:
%ADABCK-E-STNOTPO, subsequent tapes not possible with input redirection
The following modes will work successfully:
adabck <RETURN> dbid=5, dump=4 <RETURN> <CTRL/D>
adabck <RETURN> dbid=5, dump=4 <RETURN> <CTRL/Z><RETURN>
adabck dbid=5 dump=4
adabck dbid=5 dump=4 &
The utility process will be stopped if a subsequent tape is required. In this case, the user can bring the job into the foreground in order to enter a valid device name and continue processing.
Adabas supports multiple files on a single tape, provided that this feature is supported by the operating system in question (for example, via the mt interface with the no-rewind tape). In order to use this capability, skip to the desired position on the tape and then execute the utility.
mt fsf 1 adabck db=5 dump=3
The first file on the tape is skipped, and the database is dumped to tape as the second file.
Sometimes, external data (such as uncompressed data) may reside on tapes with a tape format not supported by Adabas, and this results in an I/O error from Adabas. Such tapes can be read using the UNIX command dd to read the file into a named pipe. The Adabas utility can then read from the named pipe.
The Adabas utilities can read from and write to diskette devices directly. In order to make use of this ability, the corresponding environment variable must be set to point to a file on the diskette drive.
The environment variable must point to the name of the diskette drive before the utility is started. If, for example, you want to use ADABCK on a machine running Windows, you should enter the following
set BCK001=A:
or
set BCK001=A:\BACKUP
Note:
Adabas container files may be contained on a diskette drive instead
of on a hard disk drive. However, the performance will not be as good as on a
hard disk drive.
It may be necessary for large sequential files to be spread over two or more diskettes. If a diskette gets full, the utility informs the user of the situation and prompts for input. After changing the diskette, the user must enter the device name again in order to continue.
There is one important restriction that applies to using the utilities with diskettes: input redirection is not allowed if more than one diskette is required. In this case, the utility aborts with the following message:
%ADABCK-E-STNOTPO, subsequent diskettes not possible with input redirection
The following modes will work successfully:
adabck <RETURN> dbid=5, dump=4 <RETURN> <CTRL/Z> <RETURN>
adabck dbid=5 dump=4