ARSetImage
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
Updates the image with the indicated name on the specified server. After the image is updated, the server updates all references and object property timestamps for schemas affected by the change.
If you perform a set operation on an overlay and you provide values for an inherited grain, the values are ignored. Only values for extended or overwritten grains of the overlay are set.
Privileges
BMC Remedy AR System administrator.
Synopsis
#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"
int ARSetImage(
ARControlStruct *control,
ARNameType name,
ARNameType newName,
ARImageDataStruct *imageBuf,
char *imageType,
char *description,
char *helpText,
ARAccessNameType owner,
char *changeDiary,
ARPropList *objPropList,
char *objectModificationLogLabel,
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 and server fields are required.
If a valid overlay group is specified in the control record, the ARSet
* function operates on the object that belongs to that group. If no group is specified, the function operates on the origin object. To specify whether to use an object's real or resolved name in an operation and whether to perform the operation only on objects in a specified overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP
variable of the ARSetSessionConfiguration
function (see ARSetSessionConfiguration).
name
The name of the image to updated.
newName
The new name for the image. The names of all images on a given server must be unique. Specify NULL
to leave the name unchanged.
imageBuf
New data for the new image. See Images and structures. Specify NULL
to leave the image data unchanged.
imageType
The new image encoding type for the image. Valid values are: BMP, GIF, JPEG or JPG, and PNG. Specify NULL
to leave the type unchanged.
description
The new description for this image. Specify NULL
to leave the description unchanged.
helpText
The new help text to be associated with the image. Specify NULL
to leave the help text unchanged.
owner
The new owner for the image. Specify NULL
to leave the owner unchanged.
changeDiary
The additional change diary text to associate with the image. This text can be of any length and is appended at the end of any existing text. Existing change diary text cannot be deleted or changed. The server adds the user making the change and a time stamp when it saves the change diary. Specify NULL
for this parameter if you do not want to add to the change diary.
objPropList
A list of server object properties. If this parameter is set to NULL
, no new properties are set. See Server object properties and structures.
objectModificationLogLabel
The version control label that the API function must apply to the object. If the label name does not exist on the server, the function creates it.
Ripple actions
Rename and Delete operations typically change multiple objects in addition to their primary target object. The Rename or Delete function must apply the version control label to all the objects that it affects.
Multiple API calls for a single user action
Some user actions trigger a sequence of API calls. In that situation, the last API call in the sequence applies the version control label to the object. Thus, clients that create forms (like BMC Remedy Developer Studio does) should provide the label only to the last call. For example, when a form is created, a client might issue these calls:
ARCreateSchema
ARCreateMultipleFields
ARSetVUI
ARSetVUI
ARSetSchema
In this case, the objectModificationLogLabel
value should be passed only to the last call, ARSetSchema
, even though the user provides the label during the ARCreateSchema
operation.
Operations on label-related forms
Version control labels cannot be applied to these forms:
- AR System Version Control: Label
- AR System Version Control: Labeled Object
- AR System Version Control: Object Modification Log
Return values
status
A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error checking.
See also
ARCreateImage, ARDeleteImage, ARGetImage, ARGetListImage ARGetMultipleImages. See FreeAR for: FreeARImageDataStruct
, FreeARStatusList
.
Comments