MODIFY_OBJECT

Use the MODIFY_OBJECT script function to modify an existing Calendar, Login, or static VARA object. To successfully modify an object, you must have write access to it. For more information, see Granting Automation Engine Authorizations.

This script function automatically commits all open script transactions to the AE database. For more information, see Script Processing.

Tips:

• If a modification fails, script processing continues by default. You can use the :ON_ERROR script statement to define specific actions to take in such cases. For more information, see Script Elements for Error Handling.

• If you need to create a new Calendar, Login, or static VARA object rather than modify an existing one, use the CREATE_OBJECT script function instead.

Modifying a 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

Parameter	Description	Format
Object name	Name of the Calendar object you want to modify.	Script literal or script variable
Title	(Optional) Title of the Calendar object.	Script literal or script variable
Calendar Event	(Optional) Name of the Calendar Event.	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. Note: Use : or ; as a separator between the date format and the date. Default Value: YYMMDD or YYYYMMDD	Script format
Date1	(Optional) Start date of the Calendar Event, respectively.	Script literal or script variable
Date2	(Optional) Start date of the Calendar Event, respectively.	Script literal or script variable

Notes:

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

Return Codes

The script function returns the following 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")

Modifying a 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 as changing Automation Engine passwords externally.

Syntax

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

Parameters

Parameter	Description	Format	Allowed Values
Object name	Name of the Login object you want to modify.	Script literal or script variable	n.a.
Title	(Optional) Title of the Login object.	Script literal or script variable	n.a.
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. To successfully change an existing entry, you must specify an Agent and its corresponding Agent type that are already defined in the Login object. If the specified Agent and Agent type do not match (for example, specifying a WINDOWS agent with a UNIX Agent type), the script line will have no effect.	Script literal or script variable	n.a.
Agent type	Specifies the type of Agent or application. Notes: The system does not validate the Agent type value, so you must ensure the value you provide is correct. Administrators can configure additional agent platforms in the system settings. If your system includes these custom platforms, you can use them as valid Agent types. For more information, see UC_LOGIN_TYPES - Defining Additional Platform and System Types for Login Objects.	Script literal	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. SQL: Login entry for databases. UNIX: Unix, Linux, or z/Linux Agent. VMS: OpenVMS Agent. WINDOWS: Windows Agent.
Login info	Specifies the login information to store in the Login object. Notes: Login information is platform and application specific. For more information, see Login (LOGIN). The system will not update the login information if it differs from the existing entry.	Script literal or script variable	n.a.
Password	(Optional) Password for the platform of the application. Note: There is no plausibility check when the script function MODIFY_OBJECT is executed.	Script literal or script variable	n.a.
Action	(Optional) Action to process. An action can modify up to three passwords per login credential.	Script literal or script variable	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. When using these deletion actions, you do not need to provide a password. If you delete the last password in a credential, the system removes the entire credential entry. Furthermore, if the specified user entry does not exist in the list, the system will not return an error code.

Return Codes

The script function returns the following 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")

Modifying a 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.

Note that you cannot use this script function to modify dynamic VARA objects.

Syntax

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

Parameters

Parameter	Description	Format	Allowed Values
Object name	Name of the VARA object you want to modify.	Script literal or script variable	n.a.
Title	(Optional) Title of the VARA object.	Script literal or script variable	n.a.
Error handling	(Optional) Action to take when the VARA object does not include a value at runtime. For more information, see Script Access.	Script literal or script variable	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. Important! You can only change the data type if the VARA object is completely empty and contains no values.	Script literal	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 returns the following 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.

Examples

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: