MODIFY_OBJECT

Use the MODIFY_OBJECT script function to modify an existing Calendar, Login or static VARA object.

Notes:

• You need write access to the object that you want to modify. For more information, see Granting Automation Engine Authorizations.
• The script statement causes all open transactions of the script to be written to the AE database. For more information, see Script Processing.

Tips:

• By default, script processing continues if the modification fails. Use the :ON_ERROR script statement to define action to take in this case. For more information, see Script Elements for Error Handling.
• Use CREATE_OBJECT when you want to create a new Calendar, Login or static VARA object.

Calendar Object

Use the MODIFY_OBJECT script function to modify the following settings of a Calendar object:

• Title
• Start date of a Calendar Event
• End date of a Calendar Event

For more information, see Calendars (CALE).

Tips:

• :SET_CALE lets you add or delete a date or time period in a Calendar Event.
• VALID_CALE lets you check if a date is included in a Calendar Event.

Syntax

MODIFY_OBJECT (Object name, [Title], [Calendar Event] [,[Date format:]Date1] [,[Date format:]Date2]])

Parameters

• Object name
  Name of the Calendar object you want to modify
  Format: script literal or script variable

• Title
  (Optional) Title of the Calendar object
  Format: script literal or script variable

• Calendar Event
  (Optional) Name of the Calendar Event
  Format: script literal or script variable

• Date format
  (Optional) Date format for the start or end date for the Calendar Event
  For more information about date formats, see Date, Time and Period Formats in Scripts.
  Default: YYMMDD or YYYYMMDD
  Note: Use : or ; as a separator between the date format and the date.

• Date1
  (Optional) Start date of the Calendar Event, respectively
  Format: script literal or script variable

• Date2
  (Optional) Start date of the Calendar Event, respectively
  Format: script literal or script variable

Notes:

• Unused parameters leave existing calendar definitions unchanged.
• If you specify a date format, use that format when you specify the date.

Return Codes

The script function has the following return codes when you modify a Calendar object:

• 0
  The Calendar object was successfully changed
• 20216
  Object '&01' cannot be modified because it is being edited by user '&03' since '&02'
• 20645
  The specified object does not exist
• 20670
  The end date for the Calendar Event is before the start date

Example

A Calendar object called FIRM.CALENDAR contains a Calendar Event called WORKDAYS. The following script changes the start and end date of the Calendar Event. The script omits the title parameter, so the calendar title remains unchanged.

:SET &RET# = MODIFY_OBJECT("FIRM.CALENDAR",,"WORKDAYS","DD.MM.YYYY:01.05.2011","DD.MM.YYYY:01.05.2012")

Login Object

Use the MODIFY_OBJECT script function to modify the following settings of a Login object:

• Title
• Login entries

For more information, see Login (LOGIN).

MODIFY_OBJECT lets you automate the administration of users, such changing Automation Engine passwords externally.

To change an existing entry, specify an Agent (and the Agent type) which is already available in the Login object. If the Agent and Agent type that you specify do not match each other, the script line has no effect.

Syntax

MODIFY_OBJECT (Object name, [Title], Agent, Agent type, Login info, [Password], [Action])

Parameters

• Object name
  Name of the Login object you want to modify
  Format: script literal or script variable

• Title
  (Optional) Title of the Login object
  Format: script literal or script variable

• Agent
  Name of the Agent
  Notes:

  • Use * to apply the login entry to all agents and systems
  • The name of backend systems is defined in the Login object of your user.
  Format: script literal or script variable

• Agent type
  Type of Agent or application
  Allowed values:

  • BS2000
    BS2000/OSD Agent
  • JMX
    Login entry for Java EE/JMX
  • MAIL
    Login entry for the mail interface
  • MVS
    z/OS or MVS Agent
  • OS400
    OS/400 Agent
  • PS
    Login entry for PeopleTools
  • R3
    Login entry for SAP
  • SIEBEL
    Login entry for Siebel
  • SQL
    Login entry for databases
  • UNIX
    Unix, Linux, or z/Linux Agent
  • VMS
    OpenVMS Agent
  • WINDOWS
    Windows Agent
  Note: Administrators can define additional agent platforms in the system settings. If additional agent platforms are available in your system, you can use them to specify the agent type for MODIFY_OBJECT. For more information, see UC_LOGIN_TYPES - Defining Additional Platform and System Types for Login Objects.

• Login info
  Login information to store in the Login object
  Note: Login information is platform and application specific. For more information, see Login (LOGIN).
  Format: script literal or script variable

• Password
  (Optional) Password for the platform of the application
  Note: There is no plausibility check when the script function MODIFY_OBJECT is executed.
  Format: script literal or script variable

• Action
  (Optional) Action to process
  An action can modify up to three passwords per login credential.
  Format: script literal or script variable
  Allowed values:

  • ADD
    Adds between one and three comma-separated passwords
    Note: Use ADD1, ADD2 and ADD3 to add passwords that include commas.
  • ADD1, ADD2, and ADD3
    Adds the first, second, and third password entry, respectively, for the specified user, or overwrites an existing entry with identical data for Agent, Agent type and login information.
  • DEL1, DEL2, and DEL3
    Deletes the first, second, or third password entry, respectively, for the specified user.
    Notes:
    • No password is necessary for deleting an entry.
    • When the last password in a credential is deleted, the whole credential entry is deleted
    • If the user entry is not available in the list, there is no error code.

Return Codes

The script function has the following return codes when you modify a Login object:

• 0
  The Login object was successfully modified
• 20645
  The specified object does not exist

Examples

A Login object called LOGIN.SMITH contains login information of a user called Smith. The following script sets two passwords for a UNIX Agent for this user. If the Login object already includes these entries, the passwords are updated to apple and ninja, respectively.

:SET &RET# = MODIFY_OBJECT("LOGIN.SMITH",,"UNIX01","UNIX","uc4","apple","ADD1")
:SET &RET# = MODIFY_OBJECT("LOGIN.SMITH",,"UNIX01","UNIX","uc4","ninja","ADD2")

The following example deletes the login data for Smith in Client 012 of an SAP system called SAP01. If this is the last password in the credential, the whole credential entry is deleted.

:SET &RET# = MODIFY_OBJECT("LOGIN.SMITH",,"SAP01","R3","012,smith","","DEL1")

Static VARA Object

Use the MODIFY_OBJECT script function to change the following settings of a static VARA object:

• Title
• Error handling
• Data type

For more information, see User-Defined VARA Objects.

Important!

• You can only change the data type when the VARA object does not contain any values.
• You cannot modify dynamic VARA objects with this script function.

Syntax

MODIFY_OBJECT (Object name, [Title], [Error handling], [Data type])

Parameters

• Object name
  Name of the VARA object you want to modify
  Format: script literal or script variable

• Title
  (Optional) Title of the VARA object
  Format: script literal or script variable

• Error handling
  (Optional) Action to take when the VARA object does not include a value at runtime
  For more information, see Script Access.
  Format: script literal or script variable
  Allowed values:

  • E
    Issues an error message
  • I
    Initializes the VARA object according to the variable type

• Data type
  (Optional) Variable data type
  For more information about date types, see Data Types and Formatting.
  Allowed values:

  • C
    Text
    Important! XML VARA objects can only have data type C.
  • N
    Number
  • TS
    Timestamp
  • TI
    Time
  • D
    Date

Return Codes

The script function has the following return codes when you modify a static VARA object:

• 0
  The VARA object was successfully modified
• 20640
  The specified data type value is invalid
• 20645
  The specified object does not exist
• 20651
  The data type cannot be changed because the VARA object contains values

Example

The following script reads the error number after the execution of an XML VARA object, and prints the error in the activation report:

:SET &HND# = MODIFY_OBJECT(VARA.XML.NEW.1, "TEST TITLE", E, C)
:SET &ERRNR# = SYS_LAST_ERR_NR()
:PRINT ">&ERRNR#<"
:IF &ERRNR# <> "0"
: SET &ERRINS# = SYS_LAST_ERR_INS()
: SET &MESSAGE# = GET_MSG_TXT (&ERRNR# ,&ERRINS#)
: PRINT &MESSAGE#
:ENDIF

See also: