AE DB Change

Administrators use the utility AE DB Change (ucybchng) to modify exported data that has been exported from the database by using the Transport Case. For more information, see Transport Case. Selected attributes of objects can be changed and strings be replaced by using a script file for which the AE provides the two statements REPLACE and REPLACE_PART. Doing so simplifies the process of adjusting data for usage in a different AE system or client.

This page includes the following:

Overview of Required Steps

  1. Move all objects that should be adjusted to the Transport Case and unload the Transport Case by using the utility AE.DB Unload, see Transporting Data
  2. Write one or several script files that include the commands for attribute modifications, see Syntax of the Script File That Modifies Attributes
  3. Call the utility AE DB Change with the corresponding start parameters, see Start the Utility

Make sure that the transport file contains all attributes that should be changed. You can ensure this by setting the parameter all_entities= to "1" in the utility AE DB Unload's INI file (see Utility DB Unload):

[TRANSPORT]

all_entities=1

Setting this parameter means that attributes that do not contain values are also exported.

Objects Attributes That Can Be Changed

The links below guide you to topics that inform you whether a specific attribute can be changed by using this utility. If so, you can use a script file which includes commands that modify the attributes that are stored in the transport file.

Syntax of the Script File That Modifies Attributes

The Automation Engine provides the two statements REPLACE and REPLACE_PART which you can use to create a script file for the utility AE DB Change. The difference between these statements and their structures are described below.

REPLACE Object Type, Name, Attribute, Old Value, New Value

REPLACE_PART Object Type, Name, Attribute, Part of the old Value, New Value

You can include comment lines in the script file. These lines must start with a semicolon.

You cannot assign abbreviations to AE DB Change, you must use complete attribute names. For example, use "INT_ACCOUNT" instead of " INT_ACC".

Use REPLACE or REPLACE_PART

Use either the REPLACE or REPLACE_PART script elements for your script replacements. The differences are described below.

REPLACE

Old Value is only replaced by New Value if Old Value exactly equals the old value. An exception to this rule are modifications that are made in an object's script. This is like the Search/Replace function of common text editors. Every string that is located within a text line is replaced.

REPLACE_PART

REPLACE_PART can be used to replace parts of Old Value. The specified New Value is then inserted instead of the old value.

Important! When you use the command REPLACE in combination with the attribute SCRIPT, you can only replace complete scripting lines. The utility does not replace parts of scripts. Use REPLACE_PART instead for this purpose. 

Change Attribute Values for "Y" and "N"

An exception applies to attributes that include the allowed values "Y" and "N". These two letters cannot be assigned to the utility AE DB Change. Use the number "1" instead of "Y" and "0" instead of "N" in such a case.

Change Object Variables

You can modify object variables. For this purpose, select the parameter Attribute and specify the term "VALUE" followed by a colon and the name of the object variable with a leading "&" character. For more information, see VARA Objects.

Change Rapid Automation Job Attributes

You can change the specific attributes of all Rapid Automation jobs with the utility AE DB Change. Use one of the following values and change it by entering the attribute name as shown below

Important! If you change attributes of all Rapid Automation jobs or workflows by specifying * as the Name for the change, the utility AE DB Change will apply your changes to all jobs or workflows that meet the requirements you specify; even if they belong to different agents or agent types.

Many Rapid Automation agents include a list of attributes in the agent's documentation. Rapid Automation job attributes are not documented in the Automation Engine documentation, because each agent is versioned separately and released on a different schedule than the Automation Engine.

Another way to retrieve the Rapid Automation attribute names including their values is to run the following command in the AE database (replace the JOBNAME by the job's actual object name):

select OCV_VName,ocv_value from OCV,oh where OCV_OH_Idnr=OH_Idnr and oh_name='JOBNAME'

Change Object Assignments

You can replace object uses with the utility's parameters OBJECT_USE and OBJECT_USE_ATTR. They can be replaced in the following object types: CALL, JOBS, EVNT, JOBP, JOBF, JSCH, JOBG, SCRI, JOBI, JOBQ, DOCU, VARA, SYNC, FILTER, CALE, LOGIN.

OBJECT_USE_ATTR replaces the same fields as OBJECT_USE, except for OT table columns. You use OBJECT_USE_ATTR if you have an object that is assigned as an attribute and as script, because OBJECT_USE would cause it to be renamed twice.

Use the name of the object that is currently used for the Old value and the name of the object that should be used instead for the New value.

To change the connection and the login of SQL-type Variable objects, you can use the keywords "SQL_CONNECTION" and "SQL_LOGIN" for Attribute. You can either change the complete value (REPLACE) or only part of the value (REPLACE_PART).

Notes:

Change Folder Names

This utility can change the names and paths of folders. For this purpose, you use REPLACE_PART in combination with the attribute FOLDER_NAME and for the name, you specify the complete path of the folder that should be changed. For the old and new value, you can either specify an individual folder name or part of the path.

You cannot change a folder's title with this utility. The transport file shows the folder title in curly brackets within the path (for example: \OBJECTS{TITLE}\TEST{}\. The curly brackets are empty if there is no title.

If you change a folder within the path by replacing one or several folders, the titles will still be used at the old folder level.

Example


Old path: \OBJECTS{TITLE1}\TEST{}\JOBS{TITLE2}
Script command: REPLACE_PART FOLD, \OBJECTS\TEST\JOBS, FOLDER_NAME, "OBJECTS", "ARCHIV\OBJ"
New path: \ARCHIV{TITLE1}\OBJ{}\TEST{TITLE2}\JOBS{}

The new path still uses the titles at the old folder level. The folder "TEST" now has a title (TITLE") although it had no title in the beginning.

Change Conditions (only for JOBP)

You can change condition values with this utility. Use CONDITION_PARAMETER to change pre- and/or post-condition parameters of tasks within a workflow.

Examples

In the job SAP.Job.2, the SAP target system changes from SAP1 to SAP2.

REPLACE JOBS, SAP.JOB.2, SAP_DST_SYSTEM, "SAP1", "SAP2"

The target host changes from FSU to FSB in all file transfers of the name FT*.

REPLACE JOBF, FT*, FT_DST_HOST, "FSU", "FSB"

The string TEST is replaced by REAL in all scripts of objects with the name EM*.

REPLACE_PART *, EM*, SCRIPT, "TEST", "REAL"

The modifiable attribute UC100T is replaced by UC100E in all objects.

REPLACE *, *, *, "UC100T", "UC100E"

The value of the workflow's object variable "HOST#" changes from "unix01" to "unix02".

REPLACE JOBP, MM.DAY, VALUE:HOST#, "unix01",  "unix02".

In the job JOB.TEST.1, C:\Temp is replaced by D:\Temp.

REPLACE_PART JOBS, JOB.TEST.1, WIN_CMD, "C:\Temp", "D:\Temp"

The calendar changes from FIRM_CALENDAR_2016 to FIRM_CALENDAR_2017 in all Notification object names that start with MM*.

REPLACE_PART CALL, MM*, CALENDAR, "2016", "2017"

The name of the folder SCHEDULE changes to SCHEDULE_WEEKDAYS.

REPLACE_PART FOLD, \MM\SCHEDULE, FOLDER_NAME, "SCHEDULE", "SCHEDULE_WEEKDAYS"

The following example switches the folder SCHEDULE to the path TEST\JSCH.

REPLACE_PART FOLD, \MAWI\SCHEDULE, FOLDER_NAME, "SCHEDULE", "TEST\JSCH"

The specific parameter "OBJECT_USE" of the utility AE DB Change replaces used objects. The following example replaces the Sync object "SYNC1" with "SYNC2" in all workflows that use this Sync object.

REPLACE_PART JOBP, *, OBJECT_USE, "SYNC1", "SYNC2"

The specific parameter "OBJECT_USE_ATTR" of the utility AE DB Change replaces used objects except for OT table columns. The following example replaces "TSM." in object assignments with "TSM.V1.".

REPLACE_PART *, TSM.*, OBJECT_USE_ATTR, "TSM.", "TSM.V1."

The following example replaces the connection and login data of an SQL Variable object.

REPLACE VARA, VARA.SQL.TEST, SQL_CONNECTION, "CONNECTION.OLD", "CONNECTION.NEW"

REPLACE VARA, VARA.SQL.TEST, SQL_LOGIN, "LOGIN.OLD", "LOGIN.NEW"

The following examples change the value of the JMS queue from "test.tibco.queue" to "prod.tibco.queue". The first line overrides it in RA JMS Agent jobs. The second line overrides it when RA JMS Agent jobs are included as tasks in workflows. This syntax works for jobs of any Rapid Automation agent, you just switch out the Attribute name after "CVALUE:" and/or "JPCVALUE:" and specify appropriate Old Value and New Value.

REPLACE JOBS, *, CVALUE:queueName ,"test.tibco.queue","prod.tibco.queue"

REPLACE JOBP, *, JPCVALUE:queueName ,"test.tibco.queue","prod.tibco.queue"

The following example changes the SAP start mode parameter from 1 for Immediate to 0 for As Soon As Possible.

REPLACE JOBS,*,SAP_STARTMODE,"1","0"

The following examples change pre- and/or post-condition parameters:

REPLACE JOBP, *, CONDITION_PARAMETER, "OLD_PARAMTER", "NEW_PARAMETER"

REPLACE_PART JOBP, *, CONDITION_PARAMETER, "OLD", "NEW".

Start the Utility

Start the program from the command line by using the following parameters:

UCYBCHNG[.EXE] [-B] [-IPath and name of the INI file] -1Script File-2Transport File[-3Output File][-LE]

Parameters

Example

ucybchng -b -1c:\transport\uc_change.txt -2c:\transport\uc_transport.txt -3c:\transport\uc_transport_new.txt

Processing and its results are logged in a file whose name you can specify in the INI file of the utility AE DB Change, see Utility DB Change.

Return Codes

The utility returns specific return codes when processing has ended, depending on the occurred situation.

See also: