The ADARIS utility, also known as the Initial-State utility, can be used to run an initial-state process for a single Adabas file and transfer the resulting initial-state data to a sequential file. This utility reads the data from the Adabas file using the L1 or L4 command, processes the data as requested by the Event Replicator subscription definition specified in the ADARIS utility job, and writes the initial-state data to a sequential file.
The following processing steps occur:
The ADARIS utility reads through all records (if no ISNLIST is specified) or only the records specified by the ISNLIST parameter.
The selected records are processed according to the rules in the subscription, and the override parameters provided in the ADARIS utility job.
The result of the processing is written to the sequential file specified by the DDOUT job control statement.
If the ADARIS utility parameter DCLASS is set to a value of "SAGTARG" for XML, or "SAGTRGB" for Binary raw data format. The resulting sequential output file can be processed by the Event Replicator Target Adapter.
If DCLASS=SAGTARG or DCLASS=SAGTRGB are
not specified, the file cannot be used by the Event Replicator Target Adapter. The layout of the
data written to a record in the sequential file is the same as the layout of
the data written to a message for a webMethods EntireX Broker or WebSphere MQ replication
destination. .
This release of the Event Replicator Target Adapter Data Mapping Tool introduces a new option that allows the user to optimize a Global Format buffer containing MU's, PE's, and MU's within PE's. The optimized Global Format buffer can ONLY be used for initial state processing in the Event Replicator Server nucleus or via the ADARIS utility.
Following restrictions apply:
Use of Optimized Global format buffer(s) require a new Subscription for Initial-state only processing.
Attempting to use an SDESTINATION for a subscription using an optimized Global Format buffer, will results in ADAFP8 errors during session startup, or executing an operator RPLREFRESH command.
The destinations assigned to the Initial-State only subscription using optimized Global Format buffer(s) must therefore be SIDESTINATION ONLY. It cannot be used for normal replication data (SDESTINATION is not allowed).
Attempting to use an SDESTINATION for a subscription using an optimized Global Format buffer, will result in ADAFP8 errors during session startup, or when executing an operator RPLREFRESH command.
The DCLASS specified for this new initial-state subscription
must be SAGTARG in the Event Replicator Server system file definition. This can
be overridden in the ADARIS utility to specify DCLASS=SAGTRGB to
produce output in binary raw data format
The destination must be an ETB, MQ Series, or Null destination. In the case of the ADARIS utility the sequential DDOUT file is also allowed.
This document describes the ADARIS utility in the following sections:
This section describes how to install the ADARIS utility, including any prerequisites required before you can install and use the utility. It also describes the prerequisites for using the sequential output file produced by ADARIS with the Event Replicator Target Adapter.
The following prerequisites must be met before attempting to use the ADARIS utility:
The ADARIS utility requires at least Event Replicator for Adabas Version 3.5.2.
The ADARIS utility requires a version of Adabas that is in maintenance support.
The sequential output data set produced by the ADARIS
utility must have RECFM=VB. If you specify the DDOUT control
statement in your JCL without any data set attributes, the sequential output
data set will be produced using the following attributes:
Record format: VB
Record length: 32756
Block size: 32760
You must have the Show File Source configuration file preference selected. For more information, refer to the section Setting Configuration File and Target Adapter Preferences in the Event Replicator Target Adapter Administration documentation.
To install the ADARIS utility software, copy the contents of the installation medium to disk (as described in the Event Replicator for Adabas Installation documentation) and concatenate the load library in your ADARIS JCL.
To run the ADARIS utility in batch mode:
Set up the ADARIS job. A sample JCL is provided in Sample JCL.
Verify that the following ADARUN parameters are specified in the ADARIS JCL:
ADARUN PROG=ADARIS, DBID=dbid, SVC=svc, MODE=MULTI
where dbid is the Adabas
database ID on which the file that is being replicated resides and
svc is the SVC number to be used for communications
with Adabas and the Event Replicator Server. Running this utility with
MODE=SINGLE will default to MODE=MULTI.
If universal encoding support (UES) is used by the Event Replicator Server, you must include the following additional libraries for internal products in the STEPLIB:
//STEPLIB DD DISP=SHR,DSN=ADABAS.APSvrs.LDnn // DD DISP=SHR,DSN=ADABAS.APSvrs.LD00
where nn is the load library level. If the library with a higher level is not a full replacement for the lower level load library(s), the library with the higher level must precede those with lower numbers in the STEPLIB concatenation.
If universal encoding support (UES) is used by the Event Replicator Server, you must add the following additional JCL related to internal product libraries:
//DDECSOJ DD DISP=SHR,DSN=ADABAS.ADAvrs.EC00 //SYSPARM DD * SYSTEM_ID=ADAAPS ABEND_RECOVERY=NO THREAD_ABEND_RECOVERY=NO
Specify valid values for the parameters of the ADARIS utility. Values for the FILE and SUBSCRIPTION parameter are required; all other parameter values are optional. For more information, read ADARIS Syntax and Parameters
If you are going to use the sequential output dataset
produced by the ADARIS utility as input to the Event Replicator Target Adapter, be sure to specify
DCLASS=SAGTARG or DCLASS=SAGTRGB.
Both the Adabas database and the corresponding Event Replicator Server must be active.
Run the ADARIS job.
A sequential output file is produced.
When ADARIS is used, its processing of data is done asynchronously to that of the Event Replicator. The data is then delivered to the Event Replicator Target Adapter via a file. To prevent any inconsistencies from occurring, with processing by the Event Replicator, it is important to close the Event Replicator destination(s) that send data to the Event Replicator Target Adapter. The destination(s) should be closed the entire time that the ADARIS utility runs and until the output data is processed by the Event Replicator Target Adapter. Once done, the destination(s) can be re-opened.
Note:
If the ADARIS utility is canceled via an operator command or an
abnormal termination, an operator command STOPU=job-name should be
issued to stop and delete the user queue element assigned to this job. This
will help ensure any ISNs still on hold for this job are freed.
The reason for closing the Event Replicator destination(s) is to ensure that data is processed by the Event Replicator Target Adapter in the correct sequence. Transactions will result in data being accessed randomly, but ADARIS will process data sequentially by descriptor or ISN.
Important:
If data, for the same file, is being modified when ADARIS
is processing the data, it is important to use the SLOG option for the
destination(s). This way no data should be lost for the duration of the ADARIS
initial-state.
This is the syntax of the ADARIS utility:
Each parameter is described below. Only the FILE and the SUBSCRIPTION parameters are required. All other parameters are optional.
- DARC
The DARC parameter is an optional parameter. Use it to define the data architecture for fields in the URB* control structures sent to the destination. Valid values are the integer sum of the byte order and encoding family:
Control Structure Element Values Description Byte order (b) 0 High-order byte first. 1 Low-order byte first. Encoding family (e) 0 ASCII encoding family. 2 EBCDIC encoding family. The default is 2 (byte order "0" plus encoding family "2").
- DCLASS
Use the DCLASS parameter to specify the class type for the destination definition. There are 2 possible values for this parameter:
SAGTARGorSAGTRGB. There is no default.If you want to use the sequential output data set produced by ADARIS with the Event Replicator Target Adapter, this parameter should be set to
SAGTARGorSAGTRGB.When set to
SAGTARGthe output produced is in an XML format that can be processed by the Event Replicator Target Adapter. If it is set toSAGTRGBthe output is in a binary raw data format that can be processed by the Event Replicator Target Adapter.Note:
OnlyDCLASS=SAGTARGcan be specified in subscriptions using Optimized Global Format buffers defined in the Event Replicator Server system file. This value can be overridden withDCLASS=SAGTRGBfor the ADARIS utility executions.- DCLASSPARM
The DCLASSPARM parameter is an optional parameter. Use it to specify up to 120 bytes of character data to be passed to the optional destination output user exit. Any character data is valid for this parameter and there are no defaults.
If either
DCLASS=SAGTARGorDCLASS=SAGTRGBis specified to invoke support for the Event Replicator Target Adapter, you may want to specify one or more of the following keyword parameters.Note:
These parameter keywords must be specified in uppercase and enclosed by single quotes.
- NOSPRE
The NOSPRE keyword is available for use with both
SAGTARGandSAGTRGBDCLASS exits.Specify the NOSPRE keyword in the DCLASSPARM parameter if you do not want the subscription name to prefix the names of the tables produced by the Event Replicator Target Adapter. When NOSPRE is specified, the schema file name (Predict view name) alone is used for the table names; when NOSPRE is not specified, the subscription name prefixes the schema file name in the table names.
Note:
Oracle identifiers are limited to 30 characters. If NOSPRE is not specified and an Oracle RDBMS is used by the Event Replicator Target Adapter, the identifier names may exceed 30 characters and errors may occur. We recommend using NOSPRE if an Oracle RDBMS is also used.- SPRE
Specify the SPRE keyword in the DCLASSPARM parameter if you do want the subscription name to prefix the names of the tables produced by the Event Replicator Target Adapter.
The notation is
SPRE=xxxxxxxx. Wherexxxxxxxxcan be a subscription prefix to be used instead of the subscription name used in the job execution. The prefix can be 1 to 8 characters in size.The SPRE keyword is available for use with both
SAGTARGandSAGTRGBDCLASS exits.- OPTIONS
The OPTIONS keyword parameter can be used to specify options for the destination. Specify the OPTIONS keyword parameter, using the syntax
OPTIONS=nnnn. Possible values of the OPTIONS (nnnn) are listed in the following table. However, if you want to combine options, add their values together and enter the total value.For example, if you want to combine option 32 (to send the full image on an update) and option 64 (to set the XML transaction committed time value to local time instead of GMT/UTC), specify
OPTIONS=96(with 96 being the sum of 32 and 64).
Option Value Description 1 This option is no longer supported. If specified, it will be ignored. 2 Specify OPTIONS=2to indicate that long names should be used. This option will cause long names to be sent in place of the default short names used for various elements and attributes. Short names are the default and save on the amount of data being transferred. Long names make for better readability. For example, the short name <F> would appear as <Field> using long names.4 Specify OPTIONS=4to ensure that invalid XML characters found in alphanumeric fields are not translated to spaces.8 Specify OPTIONS=8to ensure that trailing blanks in alphanumeric fields are not removed.16 Specify OPTIONS=16to ensure that characters used by XML are not replaced automatically with predefined entity references. For example, ifOPTIONS=16is set, the ampersand (&) character would not be replaced with the literal "&".32 Specify OPTIONS=32to send the full image on an update. The full before image (if available= and after image of all fields are sent for an update, even if the field values were not changed or are null.64 Specify OPTIONS=64to set the XML transaction committed time value to local time instead of GMT/UTC.- TRACE
The TRACE keyword parameter can be used to specify the contents of the trace. Specify the TRACE keyword parameter, using the syntax
TRACE=nnnn. Possible values of the TRACE (nnnn) are listed in the following table. However, if you want to trace multiple control blocks, add their trace values together and enter the total value. For example, to trace the before and after images of the URBD control blocks, you would specifyTRACE=24because the sum of 8 (URBD control block before image) and 16 (URBD control block after image) is 24.Note:
If tracing is enabled using this keyword parameter, be sure to include the following JCL statement in the ADARIS JCL://DDTRACE1 DD SYSOUT=XSettings for DCLASS=SAGTARG
Option Value Description 1 Trace the URBS control block. 2 Trace the URBT control block. 4 Trace the URBR control block. 8 Trace the URBD control block before image. 16 Trace the URBD control block after image. 32 Trace the URBF/URBG control block before image. 64 Trace the URBF/URBG control block after image. 128 Trace the send buffer. 256 Trace the URBY control block. 512 Trace the URBO control block. 1024 Trace the output parameters. 2048 Trace the subscription table. Settings for DCLASS=SAGTRGB
Option Value Description 1 Trace the output buffer. 2 Trace the URBD control block after image. 4 Trace the URBR control block. 8 Trace the URBT control block. 16 Trace the URBH control block. 32 Trace the URBF/URBG control block before image. 64 Trace the URBS control block. 128 Trace the URBY control block. 256 Trace the URBO control block. - DEXIT
The DEXIT parameter is an optional parameter. This parameter is not available for general use. At the direction of a Software AG representative, use the DEXIT parameter to specify the name of the destination output user exit. There is no default.
- DEXITWORKSIZE
The DEXITWORKSIZE parameter is an optional parameter. This parameter is not available for general use. At the direction of a Software AG representative, use the DEXIT parameter to specify the size of the destination output user exit work area. There is no default.
- DMAXOUTPUTSIZE
The DMAXOUTPUTSIZE parameter is an optional parameter. Use this parameter to specify the maximum output size (in bytes) for the destination. Valid values are 0 (zero) or an integer in the range from 4096 through 32752. If no value is specified and the LRECL and BLKSIZE parameters are not included in the JCL DD statement for DDOUT, the default value is 32752.
Note:
You can specify the value for this parameter in a purely numeric form or use the K at the end of the number to specify kilobytes. For example,DMAXOUTPUTSIZE=4Kis the same asDMAXOUTPUTSIZE=4096.The value for this parameter will be used if it is less than or equal to the record length (LRECL) of the output data set.
- FILE
The FILE parameter is a required parameter. Use it to specify the number of an input file associated with the subscription identified by the SUBSCRIPTION parameter. Valid values are any valid file number. There is no default.
Records from the specified file are replicated according to the specifications in the SUBSCRIPTION.
- HOLD
Use this optional parameter to indicate whether the record being replicated should be placed in hold status while it is being replicated. Valid values are "YES" or "NO". The default is "YES".
If ADARIS is executed while users are modifying the related file, run ADARIS with HOLD=YES. If ADARIS is executed while no modifications are being done, ADARIS may be run with HOLD=NO.
See also the explanation of the READOPTION parameter below.
- ISNLIST
Use this optional parameter to specify a list of the ISNs or the records to be processed. Valid values include a list of valid ISNs, which may be a range of ISNs. There is no default.
Separate ISN numbers with commas (no blanks) in the list. Use dashes to indicate a range of ISNs.
- LRPL
Use this optional parameter to specify the size of the replication pools. Valid values range from 300,000 bytes to 2,147,483,647 bytes. The default is 2048K.
Note:
You can specify the value for this parameter in a purely numeric form or use the K at the end of the number to specify kilobytes.- READOPTION
This optional parameter has valid values of "BLANK" or "I".
The default is "BLANK", and will cause ADARIS to issue a separate read command for each possible ISN.
Specifying the "I" value will cause ADARIS to set the ACB Command Option 2 to ‘I’, when reading through a range of ISNs. This may be used with either the HOLD=NO (L1 command) or HOLD=YES (L4 command).
Specifying "I" may improve performance by reducing the number of read commands sent to the nucleus. Reading in ISN sequence, rather than issuing a read command for each specific ISN is generally better, if there are many deleted records or gaps in the ISN ranges for that file.
READOPTION interacts with the HOLD parameter and may affect the records selected if the specified file is being modified while ADARIS is running. The following should be considered when deciding what options to use:
If no modifications are being applied to the file when ADARIS is executing, you may specify HOLD=NO and READOPTION=I.
Specify HOLD=YES and READOPTION=BLANK if the file modifications include records being deleted.
Specify HOLD=YES and READOPTION=I if the file is being modified and no records are being deleted.
- SUBSCRIPTION
The SUBSCRIPTION parameter is a required parameter. Use it to specify the name of the subscription to which the initial-state data is to be replicated. Valid values are any alphanumeric subscription names (1 - 8 characters long). The subscription must have been previously-defined in the Replicator system file. There is no default.
When an Optimized Global format buffer is used, a separate subscription for initial-state only should be used, that specifies the Optimized Global format buffer.
This section provides examples of ADARIS parameter usage.
In the following example, records in file 2 with ISNs specified in the ISNLIST parameter will be read from the database and replicated to the subscription named SUBS. Then the records will be written to the sequential file.
ADARIS FILE=2
SUBSCRIPTION=SUBS
ISNLIST=1-100,142,200-300,1000-100000
The records with ISNs of 142 or in the following ranges are processed:
1-100
200-300
1000-100000
In the following example, all the ISNs of file 2 will be read from the database and replicated to the subscription named SUBS. The sequential output file produced for the run can be used as input to the Event Replicator Target Adapter.
ADARIS FILE=2
SUBSCRIPTION=SUBS
DCLASS=SAGTARG
The following sample JCL could be used to run the ADARIS utility in z/OS environments:
//ADARIS JOB //* //* //RIS EXEC PGM=ADARUN // DD DISP=SHR,DSN=ARF.Vvrs.LOAD <=== Reptor load lib // DD DISP=SHR,DSN=ADABAS.Vvrs.LOAD <=== Adabas load lib //DDOUT DD DISP=(NEW,CATLG,CATLG) // SPACE=(TRK,(4500,1500,RLSE)UNIT=SYSDA, // DSN=<dataset.name> //DDDRUCK DD SYSOUT=X //DDPRINT DD SYSOUT=X //SYSUDUMP DD SYSOUT=X //DDCARD DD * ADARUN PROGRAM=ADARIS,DBID=dbid,SVC=svc,MODE=MULTI,DEVICE=3390 //DDKARTE DD * ADARIS SUBSCRIPTION=subscription-name,FILE=fnr //
Use the DDOUT control statement to identify the name of the sequential output data set in which the replicated initial-state data should be stored.
The sequential output data set produced by the ADARIS utility must
have RECFM=VB. If you specify the DDOUT control statement in your
JCL without any data set attributes, the sequential output data set will be
produced using the following attributes:
Record format: VB
Record length: 32756
Block size: 32760
If universal encoding support (UES) is used by the Event Replicator Server, you have to do the following:
Include the following additional libraries for internal products in the STEPLIB:
//STEPLIB DD DISP=SHR,DSN=ADABAS.APSvrs.LDnn // DD DISP=SHR,DSN=ADABAS.APSvrs.LD00
where nn is the load library level. If the library with a higher level is not a full replacement for the lower level load library(s), the library with the higher level must precede those with lower numbers in the STEPLIB concatenation.
Add the following additional JCL related to internal product libraries:
//DDECSOJ DD DISP=SHR,DSN=ADABAS.ADAvrs.EC00 //SYSPARM DD * SYSTEM_ID=ADAAPS ABEND_RECOVERY=NO THREAD_ABEND_RECOVERY=NO
In a BS2000 environment the following should be taken into consideration:
The file identified by the DDOUT link name should have a variable blocked record format:
/ CREATE-FILE F-NAME = ADARIS.OUT, SPACE=(480,48) / ADD-FILE-LINK LINK = DDOUT, F-NAME = ADARIS.out, - / RECORD-FORMAT=*VARIABLE, - / RECORD-SIZE = 32750 , - / BUFFER-LENGTH=*STD, SIZE=16
If universal encoding support (UES) is used by the Event Replicator Server, you have to do the following:
BLSLIB access to the APS module libraries is required, therefore these extras statements are required:
/SET-FILE-LINK APSLIB,$SAG.APSvrs.LIB /SET-FILE-LINK BLSLIBnn,$SAG.APSvrs.LIB
Note:
Newer APS module libraries are updates of the original. We
advise you to copy the original, merge the new library into it, and reference
the merged library in the JCL.
The job has to contain the procedure call below to access the DDECSOJ object library:
CALL-PROCEDURE ($SAG.APSvrs.LIB,LMSLINKLIB),(LNK-NAME=BLSLIBn1)
where BLSLIBn1 is last
in the BLSLIB sequence.
The DDECSOJ SET-FILE-LINK statement should point to the ECS
encoding objects
$SAG.ADAvrs.ECnn
library.
No special Software AG internal product software (APS) parameters have to be set.
The setting of extra options on the START-PROGRAM statement can be made as follows:
/START-PROGRAM ($SAG.ADAvrs.MOD,ADARUN),- / RUN-MODE=*ADVANCED(ALT-LIB=YES,LOAD-INF=*REF,UNRES=*DELAY,- / MESSAGE=*ERROR)
Use this command to display the ADARIS statistics on request.
When issued against a running ADARIS job, the current ADARIS statistics are displayed in ADAU7B messages.
The syntax for DSTAT is described under DSTAT Command in section Pertinent Operator Commandsof the Administration and Operations documentation.
To process the sequential output file in the Event Replicator Target Adapter:
Edit the configuration file preferences in the Administration Tool and verify that the Show File Source configuration file preference is selected. For more information, refer to the section Setting Configuration File and Target Adapter Preferences in About the Event Replicator Target Adapter Administration Tool in the Event Replicator Target Adapter Administration documentation.
Create a new source file definition, as follows:
Start up the Administration tool.
The Administration tool window is displayed.
On left side of the Administration tool window, expand the Configuration File node.
Expand the Sources node.
Right-click on File and select New in the resulting context menu.
Or:
In the File menu select New > File Source.
A blank file source definition tab is displayed in the Administration tool window.
Specify field values for the file source definition. Each field and option is described in the following table.
| Entry Name | Description |
|---|---|
| Description | Specify a description for your File source definition. |
| Directory | Specify the path of the directory in which the sequential output file is (or will be) stored. |
| Target | From the associated drop-down menu, select the target definition to which replicated data received from this source should be sent. |
| Autostart | Select this option to indicate that this File source definition should be automatically started when the Event Replicator Target Adapter is started. By default, this option is not selected. |
Once all fields have been specified, click on the disk symbol on the toolbar to save the file source definition.
Or:
In the File menu select Save.
A Save As pop-up window is displayed.
Specify the name of the new file source definition in the Save As pop-up window and click .
The definition is saved in the context file for the Event Replicator Target Adapter.
Using FTP in Binary Mode, transfer the sequential output file to the Event Replicator Target Adapter machine. You can do this in one of two ways:
You can transfer it using FTP from the mainframe to the Event Replicator Target Adapter machine. In this case, the Event Replicator Target Adapter machine must be an FTP server.
You can issue an ftp get
command from the Event Replicator Target Adapter machine to the mainframe.
In all cases, you should transfer the file via FTP to the directory you identified in the file source definition in Step 3.
Notes: