ARCreateOverlayFromObject

Note

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

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.)
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

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.

Note

The overlay group must be set to 1. To specify the overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARSetSessionConfiguration). If that variable is set to a valid overlay group, this function creates an overlay or custom object that belongs to that group.

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 Adding-version-control-labels-to-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.

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.