MODIFY_OBJECT

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

Notes:

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.

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
    • SQL
      Login entry for databases
    • UNIX
      Unix, Linux, or z/Linux Agent
    • VMS
      OpenVMS Agent
    • WINDOWS
      Windows Agent
    Notes:

    • Technically, it is possible to insert invalid values for the Agent type. As the user or designer of this script function, ensure this value is valid.
    • To change an existing entry, specify an Agent (and the corresponding Agent type) already available in the Login object. If the Agent and Agent type you specify do not match, the script line has no effect. For example, this may happen if you use a WINDOWS agent but define the Agent type UNIX in this script function).
    • The login information is not updated if it differs from an existing entry.
    • Administrators can define additional agent platforms in the system settings. If other 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: