ARCreateOverlayFromObject

Description

Performs the following operations:

• Converts an object into an overlay of another origin object
  The object must be one of the following types:
  • Active link
  • Active link guide
  • Escalation
  • Filter
  • Filter guide
  • Image
  • Local application
  • Menu
  • Packing list
  • Web service
    This function works only for objects whose customizations do not violate the BMC customization guidelines.
    This function does not convert forms, form views, and fields into overlays.
• Converts an object into a custom object
  This function converts an origin object to a custom object. (For a list of objects that can be overlaid, see Working with overlays and custom objects.)
  To convert views and fields from origin to custom, the associated form must be an overlay or a custom object.

• Converts a custom object into an origin object
  This function converts a custom object into an origin object.
  To convert views and fields from custom to origin, the associated form must be an overlay. Such conversion is not be supported on custom forms.

  Note

  When a form is converted to origin or custom, the server implicitly converts its views and fields. However, if required, you need to explicitly convert the associated objects (for example, workflows, menus, and so on).

  
  The Best Practice Conversion utility uses this function.

Privileges

BMC Remedy AR System administrator

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARCreateOverlayFromObject(
   ARControlStruct *control
   AROverlaidStruct *overlaid
   AROverlaidStruct *customObj
   Char *objectModificationLogLabel
   ARNameType name
   ARInternalID *overlayID
   ARStatusList *status

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, server, and overlayGroup fields are required.

overlaid

Information about the object to be overlaid, including its type (see the following table). To convert an object to a custom object, enter NULL in this parameter.

When an existing object is turned into an overlay, all grains of the overlay are overwritten — nothing is extended or inherited. As such, the inheritMask and extendMask for this call must be set to 0.

Values for object types that can be overlaid

For more information about this structure, see Overlays and structures.

customObj

Information about the object to be converted into a custom object.

objectModificationLogLabel

Version control label associated with an object in the object modification log. See Labeling a collection of objects.

Return values

name

Real name of the overlay object created by this function:

• If an object is converted into an overlay, the name of the new overlay object is composed of the name of the overlaid object plus the __o suffix:
  overlaidObjectName__o
  See Overlay object names.
• If an object is converted into a custom object, the name of the new custom object is returned, which is the same as the origin object.
  See Working with overlays and custom objects.

overlayID

ID number of the overlay object if the overlaid object is a view or a field. See Overlay object names.

status

A list of zero or more notes, warnings, or errors generated from a call to this function. See Error checking for a description of all possible values.

See also

ARCreateOverlay