AE DB Change

Administrators use the AE DB Change utility (ucybchng) to modify data that has been exported from the database by using the Transport Case. You can change selected object attributes and replace strings by using a specific script file for which the AE provides the two statements REPLACE and REPLACE_PART. Special keys are available that allow you to replace the usage of objects in a specific object type, change the connection, or the login of SQL-type Variable objects. You can also change object variables, folder names, condition values in workflows, or the attributes of RA Jobs. Doing so makes it easy to adjust data that should be used in a different AE system or client.

Important!

  • AE.DB Change supports UTF-8, but you have to adapt existing replacement text files (ASCII by UTF-8 content) if required. 

  • You can also use UTF-8 when specifying the INI file name and path (-I).

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 AE DB Unload utility. See Transporting Data
  2. Write one or several script files that include the commands that modify the relevant attributes. See below in the section Syntax of the Script File That Modifies Attributes
  3. Call the AE DB Change utility with the corresponding start parameters. See below in the section Starting the Utility

Make sure that the transport file contains all attributes that should be changed. Do so by setting the all_entities= parameter to "1" in the INI file of the AE DB Unload utility. In this case, all attributes are exported, even those that do not contain any values. For details, see the INI file Utility DB Unload

[TRANSPORT]
all_entities=1

Object 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 AE DB Change utility. The differences 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

  • Object type

    The short name of the object type.

    Format: Without quotation marks.

    You can use the "*" and "?" wildcard characters. "*" stands for any number of characters and "?" for exactly one character. This means that you can use the REPLACE statement for all object types.

  • Name

    The name of the object that should be modified.

    Format: Without quotation marks

    Important!

    • Objects: You must not indicate the path because object names are unique within a client.

    • Folders: Specify the whole path (\TEST\Workflow, for example). Leave out the curly brackets that represent folder titles. If you include them in the path, your modifications will be ignored.

  • Attribute

    The name of the attribute that should be modified, or a special key.

    Format: Without quotation marks

    You can use the * wildcard character . This means that you can use the REPLACE statement for all attributes.

    For information on the object attributes including their allowed values, see the Attributes Page

    For information on special keys, see below in the section Special Keys for the Attribute Parameter

    For Rapid Automation attributes, see below in the section Keys that modify Rapid Automation attributes

  • Old Value

    The attribute value that should be changed.

    Format: Use single (') or double (") quotation marks. This is important when you replace strings that contain quotation marks. You cannot use wildcard characters here.

    Upper-case and lower-case letters that are used in the value are distinguished. No distinction is made if they are replaced within a script.

  • New Value

    The attribute value that should replace the old value.

    Format: Use single (') or double (") quotation marks. This is important when you replace strings that contain quotation marks. You cannot use wildcard characters here.

Notes:

  • 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.
  • The host that you replace in a Job object must be of the same OS type as the original host.

Example

The following example script changes the existing agent from AGENT.WIN.1 to AGENT.WIN2 in the MY.JOB Job object.

REPLACE JOBS, MY.JOB, HOST, "AGENT.WIN.1", "AGENT.WIN.2"

Using REPLACE and REPLACE_PART

You can either use the REPLACE, or the REPLACE_PART script element for your script replacements. The differences are described below.

REPLACE

The parameter Old Value will only be replaced by New Value if both formats are exactly the same. An exception to this rule are modifications that are made in the script of an object. This is like the Search/Replace function of common text editors. Every string that is located within a text line will be 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 REPLACE command in combination with the SCRIPT attribute, you can only replace complete scripting lines. The utility does not replace parts of scripts. In this case, you would use REPLACE_PART. 

Changing the Attribute Values "Y" and "N"

The values "Y" and "N" cannot be assigned to the AE DB Change utility. You must use the number "1" instead of "Y" and "0" instead of "N".

Examples

In the job JOB.TEST.1, the path C:\Temp is replaced by D:\Temp using the object attribute WIN_CMD.

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

The host WIN1 is replaced by WIN2 in all Event objects. The attribute that is used for this purpose is HOST.

REPLACE EVNT, *, HOST, "WIN1", "WIN2"

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

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

The TEST string is replaced by REAL in all scripts of objects with the name EM* using the SCRIPT object attribute, see Script Attributes.

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

The calendar changes from FIRM_CALENDAR_2019 to FIRM_CALENDAR_2020 in all Notification object names that start with MM*. The attribute CALENDAR is used.

REPLACE_PART CALL, MM*, CALENDAR, "2019", "2020"

In the job SAP.Job.2, the SAP target system changes from SAP1 to SAP2 using the object attribute SAP_DST_SYSTEM.

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

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

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

Special Keys for the Attribute Parameter

Instead of specifying an object attribute in the Attribute parameter of your script file, you can use some special keys.

Keys that replace the usage of objects in a specific object type

  • OBJECT_USE and OBJECT_USE_ATTR
    These keys can be used in CALL, JOBS, EVNT, JOBP, JOBF, JSCH, JOBG, SCRI, JOBI, JOBQ, DOCU, VARA, SYNC, FILTER, CALE, and LOGIN.

    • OBJECT_USE_ATTR replaces the same fields as OBJECT_USE, except for the OT table columns (SCRIPT, PSCRIPT, OSCRIPT) in the database. You use OBJECT_USE_ATTR if you have an object that is assigned as an attribute AND as a script. In this case, OBJECT_USE would cause the object to be renamed twice.

    Specify the name of the object that is currently used in the Old value parameter, and the name of the object that should be used instead in the New value parameter.

    Examples

    The following example replaces the usage of the Job object JOB1 with JOB2 in all (*) workflows (JOBP) that use this object.

    REPLACE JOBP, *, OBJECT_USE, "JOB1", "JOB2"

    The following example changes the usage of objects with a name part TSM. by objects where TSM. is replaced by TSM.V1. in all objects that start with TSM.*.

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

    The following example replaces the Sync object SYNC1 by SYNC2 in all workflows that use this Sync object.

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

Keys that change the connection or the login of SQL-type Variable objects

  • SQL_CONNECTION and SQL_LOGIN
    You can either change the complete value with the REPLACE statement, or only part of the value with the REPLACE_PART statement.

    • Examples

    You can use REPLACE or REPLACE_PART to replace that the usage of the Connection object CONN.PG1 by CON2.PG2 in all JOBS objects that match the object name SQL.JOB.PG.*

    REPLACE JOBS, SQLJOB.PG.*, SQL_CONNECTION, "CONN.PG1", "CONN.PG2"

    REPLACE_PART JOBS, SQLJOB.PG.*, SQL_CONNECTION, "PG1", "PG2"

    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"

Notes:

  • If a script file changes the same attribute several times, you must always use the original value in the Old Value parameter. This is because the system reads the lines always from the source transport file when it modifies an attribute, and not from the output file.
  • Event Process: You can use the PSCRIPT attribute to change the Event Process page of events. For details, see Event Object Attributes

Key that modifies object variables

  • VALUE followed by a colon and the name of the object variable with a leading & character
    For more information, see User-Defined VARA Objects.

    Example

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

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

Keys that modify Rapid Automation attributes

  • CVALUE followed by a colon and the name of the Rapid Automation attribute
    This key changes the attributes of Rapid Automation jobs.

  • JPCVALUE followed by a colon and the name of the Rapid Automation attribute
    This key changes the attributes of Rapid Automation jobs in workflow tasks when the default values from the job have been overridden on workflow level.

    Examples
    The following examples change the value of the JMS queue from test.tibco.queue to prod.tibco.queue. The first line of this example changes the value in RA JMS Agent jobs. The second line changes it when RA JMS Agent jobs are included as tasks in workflows. You can use this syntax works for the jobs of all Rapid Automation agents. Just adjust the part after CVALUE: and/or JPCVALUE: and CVALUE:" and specify the 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"

    Important! If you change attributes of all Rapid Automation jobs or workflows by specifying * as the Name for the change, the AE DB Change utility 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 their specific Rapid Automation agent documentation. They are not documented in the AWA documentation because each agent has its own release cycle that does not comply with Automation Engine releases

    Another way to retrieve the Rapid Automation attribute names including their values is to run the following command in the AE database. Replace 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'

Key that changes folder names

  • FOLDER_NAME

    • This utility can change the names and paths of folders. For this purpose, you use REPLACE_PART in combination with the FOLDER_NAME key 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.

    Example

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

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

    The name of the folder SCHEDULE changes to SCHEDULE_WEEKDAYS.

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

    You cannot change a folder 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 TEST folder now has a title (TITLE) although it had no title in the beginning.

(JOBP only) Keys that change condition values

  • CONDITION_PARAMETER
    This key changes pre- and/or post-condition parameters of tasks within a workflow.

    • Examples

    The following examples changes pre- and/or post-condition parameters.
    Note: If the parameter value OLD_PARAMTER exists several times in your conditions, all of them will be changed:

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

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

Starting the Utility

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

Note: You can also use UTF-8 when specifying the INI file name and path (-I).

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

Parameters

  • -B
    Starts the program in batch mode.
  • -I
    Serves to specify the path and name of the INI file. Complete path specifications are required for the files.
  • -L
    It is used to determine the language of the log file.
  • -1
    Your script file that contains the modification commands
  • -2
    The  transport file that contains the objects that should be modified. UC_DATA.TXT is used by default.
  • -3
    The output file that includes the modified data

    • If you do no define this parameter, the name of the output file is the same as the name of the input file plus the ending "_New". For example, the input file "uc_transport" will be the output file "uc_transport_New".

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, see Utility DB Change.

Return Codes

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

  • 0
    The utility has successfully ended processing.
  • 1
    The transport file does not exist or cannot be opened.
  • 2
    The script file does not exist or cannot be opened.
  • 3
    The transport and the script file do not exist or cannot be opened.
  • 4
    The output file cannot be opened.
  • 5
    The script file includes an error (see log file).
  • 21400
    EXIT_CODE_NOT_A_TRANSPORT_FILE
  • 21424
    EXIT_CODE_NO_DATA_IN_TRANSPORT_FILE
  • 21432
    EXIT_CODE_INVALID_VERSION_TRANSPORT_CASE
  • 21433
    EXIT_CODE_TOO_FEW_PARAMETERS

See also: