Programmers 40

December 1998 Part Number: AR-400-PG-01.
PDF
19911998 by Remedy Corporation. All rights reserved. This documentation may not be copied in whole or in part without the prior written consent of Remedy Corporation. Remedy, the Remedy Corporation logo, Action Request System, AR System, ARWeb, Flashboards, and Remedy Powered are registered trademarks or other trademarks of Remedy Corporation. HP and HP-UX are trademarks of Hewlett-Packard Company. AIX is a trademark of International Business Machines Corporation. INFORMIX is a registered trademark of Informix Software, Inc. Microsoft, MS, and MS-DOS are registered trademarks, and Windows, Windows NT, Windows 95, Windows 98 and all other Microsoft products mentioned in this document are registered or other trademarks of Microsoft Corporation. Motif, OSF, and OSF/Motif are trademarks of the Open Software Foundation, Inc. Oracle and SQL*Plus are registered trademarks, and Oracle8 is a trademark of Oracle Corporation. Silicon Graphics and IRIS are registered trademarks, and IRIX is a trademark of Silicon Graphics, Inc. Sun Microsystems, NFS, and PC-NFS are registered trademarks of Sun Microsystems, Inc. Solaris is a trademark of Sun Microsystems, Inc. SPARCstation is a trademark of SPARC International, Inc., licensed exclusively to Sun Microsystems, Inc. Sybase is a registered trademark of Sybase, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd. All other products mentioned in this document are protected by the trademarks or service marks of their respective companies or organizations. U.S. GOVERNMENT RIGHTS. Use, duplication, or disclosure by the Government is subject to Remedy Corporations commercial software license(s). If you are the U.S. government, you agree that these written materials are commercial computer software-related documentation licensed pursuant to the terms of Remedy Corporations commercial computer software license(s) in accordance with 48 C.F.R. 12.212 of the Federal Acquisition Regulations and its successors and 48 C.F.R. 227.7202-1 of the DoD FAR Supplement and its successors. Unpublished rights are reserved under the copyright laws of the United States. Part Number: AR-400-PG-01.PDF
Table of Contents
Preface....................................................................................................................................... xi Audience ....................................................................................................................xi Overview of This Document .....................................................................................xi Related Remedy Documents................................................................................... xii Conventions Used in This Document.....................................................................xiv Chapter 1 Introduction ............................................................................................................................ 1-1 Overview of the AR System API............................................................................ 1-1 When to Use API Programming ............................................................................ 1-4 Chapter 2 Getting Started ....................................................................................................................... 2-1 Environment Setup for Windows .......................................................................... 2-1 Installing the API Files ......................................................................................... 2-2 Header Files................................................................................................ 2-3 Library Files ............................................................................................... 2-5 Source Code ................................................................................................ 2-5 Makefiles ................................................................................................................ 2-6 Chapter 3 Data Structures ...................................................................................................................... 3-1 Data Types.............................................................................................................. 3-2 Lists ........................................................................................................................ 3-3 High-Level Object Relationships........................................................................... 3-4 Login and Session Information ............................................................................. 3-6 Status Information................................................................................................. 3-8 Permission Information ........................................................................................3-11 Representing Values ............................................................................................ 3-12
iii
Representing Qualifications ................................................................................ 3-15 Qualifications that Use Conditional Operators ...................................... 3-17 Qualifications that Use Relational Operators ........................................ 3-17 Schemas ................................................................................................................ 3-20 Fields .................................................................................................................... 3-21 Defining Field Limits ............................................................................... 3-21 Defining Field Display Properties ........................................................... 3-24 Mapping Fields in Join Schemas............................................................. 3-27 Entries .................................................................................................................. 3-28 Retrieving Entry Lists ............................................................................. 3-28 Manipulating Individual Entries ............................................................ 3-32 Retrieving Multiple Entries..................................................................... 3-34 Filters, Escalations, and Active Links ................................................................ 3-34 Set Fields Action....................................................................................... 3-38 Push Fields Action.................................................................................... 3-45 OLE Automation Action........................................................................... 3-46 Menus ................................................................................................................... 3-50 Containers ............................................................................................................ 3-52 Retrieving Container Lists ...................................................................... 3-52 Manipulating Individual Containers ...................................................... 3-54 Importing and Exporting ..................................................................................... 3-57 Freeing Allocated Memory................................................................................... 3-58 Chapter 4 Creating and Executing API Programs ............................................................................ 4-1 Program Structure ................................................................................................. 4-1 Performing Common Tasks ................................................................................... 4-4 Example 1Retrieving Field Properties .................................................. 4-5 Example 2Retrieving Selected Entries .................................................. 4-6 Example 3Retrieving a Server List........................................................ 4-7 Specifying Fields or Keywords .............................................................................. 4-8 Error Checking ....................................................................................................... 4-9
iv
Action Request System Programmers Guide
Executing API Programs in Workflow ................................................................ 4-12 Program Design Tips ........................................................................................... 4-14 Chapter 5 Debugging and Maintenance .............................................................................................. 5-1 Logging AR System Activity.................................................................................. 5-1 Using the Driver Program ..................................................................................... 5-2 Using print.c Routines ............................................................................... 5-3 Using driver from the Command Line ...................................................... 5-4 Creating and Using driver Scripts ............................................................ 5-8 Chapter 6 Functions ................................................................................................................................. 6-1 Object Manipulation Functions............................................................................. 6-1 Active Link.................................................................................................. 6-2 Container .................................................................................................... 6-2 Entry ........................................................................................................... 6-2 Escalation ................................................................................................... 6-3 Field ............................................................................................................ 6-3 Filter............................................................................................................ 6-3 Character Menu.......................................................................................... 6-4 Schema ........................................................................................................ 6-4 Support File ................................................................................................ 6-4 View............................................................................................................. 6-4 Other Functions ..................................................................................................... 6-5 ARCreateActiveLink .............................................................................................. 6-6 ARCreateCharMenu ............................................................................................ 6-10 ARCreateContainer.............................................................................................. 6-12 ARCreateEntry..................................................................................................... 6-15 ARCreateEscalation............................................................................................. 6-17 ARCreateField...................................................................................................... 6-19 ARCreateFilter..................................................................................................... 6-33 ARCreateSchema ................................................................................................. 6-35 ARCreateSupportFile .......................................................................................... 6-38
ARCreateVUI ....................................................................................................... 6-40 ARDecodeDiary .................................................................................................... 6-45 ARDecodeStatusHistory ...................................................................................... 6-46 ARDeleteActiveLink ............................................................................................ 6-47 ARDeleteCharMenu............................................................................................. 6-48 ARDeleteContainer .............................................................................................. 6-49 ARDeleteEntry ..................................................................................................... 6-50 ARDeleteEscalation ............................................................................................. 6-51 ARDeleteField ...................................................................................................... 6-52 ARDeleteFilter ..................................................................................................... 6-54 ARDeleteMultipleFields ...................................................................................... 6-55 ARDeleteSchema.................................................................................................. 6-57 ARDeleteSupportFile ........................................................................................... 6-59 ARDeleteVUI........................................................................................................ 6-60 ARExecuteProcess................................................................................................ 6-61 ARExpandCharMenu........................................................................................... 6-63 ARExport .............................................................................................................. 6-64 ARGetActiveLink ................................................................................................. 6-66 ARGetCharMenu ................................................................................................. 6-69 ARGetContainer................................................................................................... 6-71 ARGetEntry.......................................................................................................... 6-74 ARGetEntryBLOB ............................................................................................... 6-76 ARGetEntryStatistics .......................................................................................... 6-78 ARGetEscalation .................................................................................................. 6-80 ARGetField ........................................................................................................... 6-82 ARGetFilter .......................................................................................................... 6-85 ARGetFullTextInfo............................................................................................... 6-88 ARGetListActiveLink........................................................................................... 6-90
vi
ARGetListCharMenu ........................................................................................... 6-92 ARGetListContainer ............................................................................................ 6-93 ARGetListEntry ................................................................................................... 6-95 ARGetListEntryWithFields................................................................................. 6-97 ARGetListEscalation ........................................................................................... 6-99 ARGetListField .................................................................................................. 6-100 ARGetListFilter ................................................................................................. 6-102 ARGetListGroup ................................................................................................ 6-103 ARGetListSchema.............................................................................................. 6-104 ARGetListServer................................................................................................ 6-106 ARGetListSQL ................................................................................................... 6-108 ARGetListSupportFile ........................................................................................6-110 ARGetListUser....................................................................................................6-112 ARGetListVUI.....................................................................................................6-114 ARGetMultipleEntries........................................................................................6-115 ARGetSchema .....................................................................................................6-117 ARGetServerInfo.................................................................................................6-119 ARGetServerStatistics....................................................................................... 6-130 ARGetSupportFile.............................................................................................. 6-136 ARGetTextForErrorMessage ............................................................................. 6-138 ARGetVUI .......................................................................................................... 6-139 ARImport ............................................................................................................ 6-141 ARInitialization.................................................................................................. 6-143 ARLoadARQualifierStruct................................................................................. 6-144 ARMergeEntry ................................................................................................... 6-145 ARSetActiveLink................................................................................................ 6-147 ARSetCharMenu ................................................................................................ 6-151 ARSetContainer ................................................................................................. 6-153
vii
ARSetEntry ........................................................................................................ 6-156 ARSetEscalation ................................................................................................ 6-158 ARSetField ......................................................................................................... 6-161 ARSetFilter......................................................................................................... 6-164 ARSetFullTextInfo ............................................................................................. 6-167 ARSetSchema ..................................................................................................... 6-169 ARSetServerInfo ................................................................................................ 6-172 ARSetServerPort................................................................................................ 6-180 ARSetSupportFile .............................................................................................. 6-181 ARSetVUI ........................................................................................................... 6-182 ARTermination ................................................................................................... 6-184 ARVerifyUser...................................................................................................... 6-185 FreeAR................................................................................................................ 6-187 FreeNT................................................................................................................ 6-194 NTDeregisterServer........................................................................................... 6-195 NTGetListServer................................................................................................ 6-196 NTGetListUser................................................................................................... 6-197 NTGetTextForErrorMessage ............................................................................. 6-198 NTInitializationServer ...................................................................................... 6-199 NTNotificationServer......................................................................................... 6-200 NTRegisterServer .............................................................................................. 6-202 NTSetServerPort................................................................................................ 6-204 NTTerminationServer........................................................................................ 6-205 Appendix A Controlling Remedy User with OLE Automation...........................................................A-1 Overview................................................................................................................. A-1 Data Types.............................................................................................................. A-2 Errors......................................................................................................................A-3
viii
Sample Program..................................................................................................... A-3 Form1 ..........................................................................................................A-4 Form2 ..........................................................................................................A-7 ICOMAppObj..........................................................................................................A-8 Properties.................................................................................................... A-8 Login............................................................................................................ A-9 Logout ....................................................................................................... A-10 GetServerList ........................................................................................... A-11 GetFormList ............................................................................................. A-12 OpenForm ................................................................................................. A-13 LoadForm.................................................................................................. A-14 GetActiveForm.......................................................................................... A-15 HasDefaultSession ................................................................................... A-16 OpenGuide ................................................................................................ A-17 RunMacro.................................................................................................. A-18 ICOMFormWnd.................................................................................................... A-19 Properties.................................................................................................. A-19 Submit....................................................................................................... A-20 Modify ....................................................................................................... A-21 Close .......................................................................................................... A-22 MakeVisible .............................................................................................. A-23 GetField .................................................................................................... A-24 GetFieldById ............................................................................................ A-25 GiveFieldFocus ......................................................................................... A-26 GiveFieldFocusById ................................................................................. A-27 Query......................................................................................................... A-28 GetServerName ........................................................................................ A-29 GetFormName .......................................................................................... A-30 ICOMField ............................................................................................................ A-31 Properties.................................................................................................. A-31 MakeVisible .............................................................................................. A-32 MakeReadWrite ........................................................................................ A-33 Disable ...................................................................................................... A-34 ICOMQueryResult ............................................................................................... A-35 Properties.................................................................................................. A-35
ix
ICOMQueryResultSet.......................................................................................... A-36 Properties.................................................................................................. A-36 Item ........................................................................................................... A-37 Appendix B Migrating to the AR System 4.0 API ..................................................................................B-1 Changes that Impact Existing Programs ............................................................. B-1 ARInitialization .......................................................................................... B-1 Control Record ............................................................................................ B-1 Status Structure ......................................................................................... B-2 Windows DLL Requirements ..................................................................... B-2 UNIX Makefile Changes ............................................................................ B-3 Deleted Functions....................................................................................... B-3 Changes that Do Not Impact Existing Programs................................................. B-3 New Functions ............................................................................................ B-3 New Properties and Options ...................................................................... B-5 New Field Types ......................................................................................... B-5 New Data Types.......................................................................................... B-5 Multithreaded API Clients ........................................................................ B-5 Glossary Index
Preface
Audience
This guide is intended for software developers who want to use the Remedy Action Request System application programming interface (API) to further customize the AR System and Remedy Notifier. You should be familiar with the AR System, including the overall architecture and the information covered in the Action Request System Quick Start Guide, Action Request System Concepts Guide, and Action Request System Administrators Guide, Volume 1. In addition, you should be knowledgable about the operating system for your environment and have some experience with client/server applications. This guide assumes that you are proficient in C programming and are familiar with arrays, pointers, structure types, and using allocated memory.
Overview of This Document

Chapter 1, Introduction, presents a high-level discussion about when to use API programming and an overview of the AR System API. Chapter 2, Getting Started, describes the software requirements for using the API. It details the various files and libraries you must install and how to configure your compiler. Chapter 3, Data Structures, describes some of the key API data structures. It explains the high-level relationships between AR System objects and includes a series of data structure diagrams that identify the structures associated with common operations and illustrate the relationships between them. This chapter also addresses the need to free allocated memory and when to use the FreeAR and FreeNT functions. Chapter 4, Creating and Executing API Programs, outlines the basic API program structure and provides two examples of the high-level steps used to
Preface
xi
perform common tasks. It also discusses error checking and the various methods of executing an API program. Chapter 5, Debugging and Maintenance, describes how to use API tracing and the driver utility to debug your programs and addresses the general topic of maintenance and portability. Chapter 6, Functions, is a detailed reference section describing the use and purpose of each API call. Appendix A, Controlling Remedy User with OLE Automation, describes how to use Remedy Users Object Linking and Embedding (OLE) server capability. It includes sample code and a detailed reference section describing the use and purpose of each OLE call. Appendix B, Migrating to the AR System 4.0 API, briefly lists the additions and changes to the AR System API in version 4.0. It is a good place to start if you are familiar with version 3.2 of the API and want to see how version 4.0 affects your API programs.
Related Remedy Documents

The Action Request System Installation Guide details installing and licensing the AR System software. Installation guides are available for Windows 32-bit and UNIX platforms and are provided in both printed and online (PDF) formats. The Action Request System Quick Start Guide provides a general overview, establishes a foundation for use, documents interactive demonstrations, and describes implementing the AR System. This document pertains to Windows 32-bit platforms. It is provided in both printed and online formats. The Action Request System Concepts Guide defines the key components of the AR System and explains how they work together to address your organizations needs. Read the Action Request System Concepts Guide before undertaking any of the procedures described in the Action Request System Administrators Guide, Volume 1. This document pertains to Windows 32-bit and UNIX platforms. It is provided in both printed and online formats. The Action Request System Administrators Guide, Volume 1: Using Remedy Administrator describes how to use Remedy Administrator (the Administrator tool) to set up the AR System and define its local operations. This document
xii
Related Remedy Documents
focuses on the Administrator tools control over forms and applications. It also describes using workflow to create filters, escalations, active links, and guides. This document pertains to Windows 32-bit platforms. It is provided in both printed and online formats. The Action Request System Administrators Guide, Volume 2: Performance and Configuration is an online document that discusses advanced AR System administration topics such as performance issues, database servers, log files, full text searches, ODBC drivers, and advanced active links. This document pertains to Windows 32-bit platforms for Remedy Administrator and includes information for both the Windows and UNIX versions of the AR System server. It is provided in online format only. The Action Request System Programmers Guide (this document) is a reference guide for programming with the AR System application programming interfaces (APIs), based on C, and its Object Linking and Embedding (OLE) Automation interfaces, based on the Microsoft Component Object Model (COM). This document pertains to Windows 32-bit and UNIX platforms. It is provided in online format only. The Action Request System Error Messages Guide provides information about AR System exception messages that helps you identify and solve problems within the AR System. This documentation pertains to Windows 32-bit and UNIX platforms. It is provided in online format only. The Action Request System Distributed Server Option Administrators Guide provides information about operating the AR System in a distributed, multiple-server environment. This document pertains to Windows 32-bit and UNIX platforms and is available by contacting your authorized Remedy representative.
Preface
xiii
Conventions Used in This Document

Some terminology has changed in the user interface of the Remedy client tools in this release of the AR System. In particular, schemas are now called forms, and entries are now called requests. Because the AR System API calls and data structures documented here have not changed to match the new client terminology, this document continues to use the terms schema and entry. However, Appendix A uses the term form to document Remedy Users OLE Automation server, which has adopted the new terminology. For a complete description of new AR System terminology, see the online reference Whats New in Remedy User 4.0, available on Windows systems in the Action Request System 4.0 program group. This document uses the following formatting conventions: bold italic Indicates a new or important term. Example: filters Indicates a reference to another document. Example: See AR System Documents. Italic type is also used for emphasis. Example: All users will have access.
courier
Indicates computer output and names of various infrastructure components (such as files, directories, machines, and underlying data structures). Example: # Remedy AR System Daemons Indicates a variable directory, file name, or string that users replace with the actual directory, file name, or string. Example: <ar_install_directory> Indicates data to be entered by the user. Example: Type <ar_install_directory>/bin/aruser. Indicates a series of menu selections. Example: Choose File Exit. Used in the left margin to indicate a step-by-step procedure.
<italic_courier>
bold courier
xiv
Chapter 1 Introduction
This chapter shows you how the AR System API works with the AR System.
Overview of the AR System API

As illustrated in Figure 1-1, the Remedy API is an interface layer between the AR System server and a variety of client processes. Clients include Remedy User, Remedy Administrator, Remedy Notifier, and Remedy Import, as well as API programs. The Remedy client tools perform all database operations through this interface.
Remedy User Remedy Administrator Remedy Import MS / UNIX Mail API Program Remedy Notifier
AR System mail process
AR System API
Remedy Notifier API
AR System server process
Remedy Notifier server process
Database
Notification files
Figure 1-1
Overview of AR System and Remedy Notifier Architecture
Introduction
1-1
Note:
The arrows in Figure 1-1 identify the directions in which each program or process can initiate API function calls. Data may flow in any direction.
Although you can use the API in either a UNIX or Windows NT environment, the server processes shown in Table 1-1 are associated with different executable files on the two platforms. Table 1-1 Process AR System server Remedy Notifier server AR System mail UNIX file
arserverd ntserverd armaild
Windows NT file
arserver.exe ntservd.exe armail.exe
Note:
You can find additional information about these processes in the Action Request System Administrators Guide, Volume 2.
The API consists of a set of 85 function calls, most of which perform a specific database operation. For example, you can create an entry or retrieve information about a particular AR System object. Chapter 6 describes the purpose and use of each function. In addition, almost all of the API functions accept one or more structure-type parameters. Chapter 3 explains some of the most common structures and the operations they apply to. By understanding the functions and structures that comprise the API, you can interact with the AR System server to customize and extend your applications. Understanding how the AR System server processes an incoming function call is helpful before you start writing an API program. Figure 1-2 illustrates the sequence of high-level activities that occur for every API call. See the Filter Processing section of the Action Request System Administrators Guide, Vol. 1 for more explanation of this process.
1-2
Overview of the AR System API
User Tool Client Request
API Program
Others Server Response
Action or Data if successful
Access IfControl fails Parameter Validation If fails
Error message, and filter stops
Error message, and filter stops
If qualification met, execute Phase 1 If and Push Field actions, and queue up Phase 2 actions.
Execution Order [EO] 0: If qualification met, execute Goto Log to File Message Set Fields Push Fields EO 1... EO 2... If error Error message, and filter stops
Perform database operations Database error message If error

and filter stops Phase 2 Executeexecutionactions for filters from step 3 (in filter order) EO 0: Run Process Notify Direct SQL EO 1.. EO 2... If error Error message, and filter stops
Database
arserverd
server process
EO = Execution order
Figure 1-2
Overview of AR System Server Processing
Introduction
1-3
When to Use API Programming

The primary reason to write an API program is to satisfy a business requirement that cannot be accomplished by using the Remedy client tools. API programming gives you greater flexibility in customizing your application than is possible by using the graphical interface tools. The trade-off, however, is increased time and development cost. API solutions are more complex to design, implement, and maintain. In addition, the client tools provide built-in portability across platforms. Writing an API program requires you to manage all cross-platform issues. Sometimes, however, writing an API program is the best solution. The following examples illustrate cases in which you might use the API:
s
When you need to access multiple AR System components at the same time or integrate with programs or data outside the AR System When you need to perform complex operations involving multiple schemas When you need a two-way interface (gateway) between the AR System and another application When the values you want to specify for $PROCESS$ or the Run Process action (see Chapter 4) exceed the size limitation of the command line On some systems, for example, the command-line area for $PROCESS$ or Run Process parameters is limited to 256 bytes (expandable to 4 KB). You can get around this limitation by passing a parameter to an API program and manipulating larger-sized data within the program.
When you need to create reports or log files in a format not compatible with standard report writing tools The API is enhanced at each release to support new product functionality. In some cases, you may have to rewrite existing API programs to compile them with newer releases. See Appendix B, Migrating to the AR System 4.0 API, for highlevel information about the changes made to the API for version 4.0.
Note:
1-4
Chapter 2 Getting Started
This chapter tells you what you need to do before you can start writing your API program. It has information about setting up a Windows environment, required API files, and makefiles.
Environment Setup for Windows

The following information applies to Windows NT, Windows 95, and Windows 98 environments: Compiler
s
s s
Requires Microsoft Visual C++ version 5.0 or later, or a compatible compiler. The AR System API libraries were coded in Microsoft Visual C++ version 5.0. Set code generation to Multithreaded DLL. Set struct member alignment to 8 bytes (default). Specify the full path to the AR System and Remedy Notifier libraries. Requires linking of wsock32.lib. Requires arrpc40.dll, arutl40.dll, and arapi40.dll in the path (you can either add <ar_install_dir> to your path or put your executable file in <ar_install_dir>).
Libraries
DLLs
Getting Started
2-1
Note:
Ensure you have the arcatalog_eng.dll and ntcatalog_eng.dll files in your path. Without these .dll files, errors generated by the API will not display the appropriate messages. Although it is still possible to run API programs without these files in place, debugging is more difficult.
When performing debug builds you must still set code generation to Multithreaded DLL, not Debug Multithreaded DLL. Where other included libraries cause conflicts, add /nodefaultlib:MSVCRTD to the project options to avoid using the Debug C runtime library. If your program references this library at runtime, memory management errors will occur when memory pointers are referenced by both the Debug and Release C runtime libraries.
Installing the API Files

Before you can start writing API programs you must install the API package. This package contains the following components:
s s s
Header files Library files Source code for daysOpen (UNIX only) and driver sample programs.
You can either install the API files when you are first installing the AR System server or reinstall them later. Note: If you have already installed the AR System server and want to add the API package, ensure that you select the option to upgrade the database rather than overwrite it. For complete instructions, see the Action Request System Installation Guide.
As illustrated in Figure 2-1, installing the API package creates a series of directories under the AR System installation directory (<ar_install_dir>).
2-2
Header Files
UNIX
<ar_install_dir>
Windows NT
<ar_install_dir>
api
arserver
api
include (header files)
lib (library files)
src (source code)
include (header files) daysOpen driver
lib (library files)
driver (source code)
Figure 2-1
Directory Structure for API Files
Header Files
The include directory contains the nine API header files shown in Table 2-1. Table 2-1 AR System
ar.h arextern.h arfree.h arerrno.h arstruct.h nt.h ntsextrn.h ntfree.h nterrno.h
API Header Files Remedy Notifier
Getting Started
2-3
With the exception of arstruct.h, each of the AR System header files has a Remedy Notifier counterpart:
ar.h nt.h
These are the primary include files for the AR System and Remedy Notifier. These files contain data type and structure definitions, size limits, and constant definitions. You must include the appropriate file when calling an API function. These files contain the external declarations for the API functions, specified with and without prototypes for use with standard C, ANSI C, or C++ compilers. You must include the appropriate file when calling an API function. These files contain the external declarations for the FreeAR and FreeNT functions. These functions recursively free all allocated memory associated with a particular data structure. Like arextern.h and ntsextrn.h, declarations are specified with and without prototypes. You must include the appropriate file when calling a FreeAR<data structure> or FreeNT<data structure> function. These files contain error code definitions. You must include the appropriate file if you check for particular error conditions (not required if you simply report errors or do not handle them). This file contains core and reserved field ID definitions, database separator characters, and labels for exporting structure definitions.
arextern.h ntsextrn.h
arfree.h ntfree.h
arerrno.h nterrno.h
arstruct.h
2-4
Library Files
Library Files
The lib directory contains the API library files. As shown in Table 2-2, the library names depend on your environment: Table 2-2 System AR System Remedy Notifier API Library Files Windows NT files
arapi40.dll, arapi40.lib nts.lib
UNIX files
libar.a
libnts.a
Note:
In HP/UX environments, libar.a is actually a symbolic link to either libarst.a or libarmt.a depending on your version of the operating system. If you upgrade from HP/UX 10 to version 11 and want to write multithreaded API programs, you must either change the symbolic link to refer to libarmt.a or refer to it directly from your AR System API programs. If you do not need multi-threading you can continue using the existing link.
Source Code
The API includes source code for two sample programs in UNIX environments. As shown in Figure 2-1, the daysOpen and driver programs are located in separate subdirectories under the src directory. In Windows NT environments, the API includes source code for the driver program only. The daysOpen directory contains source code for the daysOpen program. This program determines the number of business days that a request has been open by subtracting weekends and specified holidays. For additional information, see the associated README file in the daysOpen directory. The driver directory contains source code for the driver program. This program provides a command line interface for calling AR System API functions. The driver program also includes print routines for every data structure in the API, making it a useful debugging tool. See Using the Driver Program on page 5-2 for additional information about this topic.
Getting Started
2-5
Makefiles
While makefile content is generally the same in both UNIX and Windows NT environments, the process of creating and editing makefiles is quite different. Both the daysOpen and driver program source code include makefiles that you can use as templates for creating your own makefiles.
UNIX
The sample makefile shown in Figure 2-2 comes with the daysOpen program and illustrates a typical set of flags in the UNIX environment.
# Makefile.hp # Parameters PROGRAM = daysOpen SOURCES = daysOpen.c OBJECTS = daysOpen.o # Compiler CC = DEBUG = CFLAGS = flags c89 -g $(DEBUG) -DHP -D_REENTRANT -Wc,-DA1.0,-DS1.0,-Aa \ -I/usr/ar/api/include -I../include -I../../include -I../../../include LDLIBS = -L../lib -L../../lib -L../../../lib ARCHLIBS = -ldce ARLIB = -lar # Standard targets all: $(PROGRAM) objects: $(OBJECTS) $(PROGRAM): $(OBJECTS) $(CC) -o $(PROGRAM) $(OBJECTS) $(LDLIBS) $(ARCHLIBS) $(ARLIB) clean: $(RM) $(OBJECTS) core /* sample makefile for H-P platform */
Figure 2-2
Sample Makefile for daysOpen Program
Note:
In some circumstances, the order in which you specify library files may be important.
2-6
Makefiles
Windows NT
Creating and editing makefiles in the Windows NT environment is considerably more simple. The Microsoft Visual C++ compiler creates makefiles for you and provides a graphical interface for specifying the options you want. You specify the appropriate makefile when you compile your program:
nmake /f <filename>.mak
To see a sample makefile for this environment, see the driver.mak file that comes with the driver program.
Getting Started
2-7
2-8
Chapter 3 Data Structures
This chapter describes both the elements and functions of some of the key data structures used in the AR System and Remedy Notifier. Complete specifications for all data types and structures are located in the ar.h and nt.h header files (see Header Files on page 2-3). Note: The only data structures and constant definitions that are supported public interfaces are those documented in this manual. Additional structures or constants in ar.h or nt.h are not currently supported.
As you will see in the header files, the AR System API contains a large number of structures. Some of the structures are generic data containers designed to store low-level information: for example, any type of value (ARValueStruct) or any arithmetic operation (ARArithOpStruct). These structures, in turn, form the building blocks of higher-level structures. This chapter contains a series of data structure diagrams that illustrate these hierarchical relationships. The diagrams also identify which structures, or groups of structures, are used to manipulate different AR System objects. Figure 3-1 defines the notation used to represent the possible data relationships.
Data Structures
3-1
Person
HS Diploma Zero or One
Example A particular person may have no high school diploma (optional relationship) or a maximum of one high school diploma. Conversely, a particular high school diploma must belong to one and only one person.
Person
Birth Date One Only
Example A particular person must have one and only one birth date (required relationship). Conversely, a particular birth date must belong to at least one person and may belong to any number of people.
Person
Credit Cards Zero or More
Example A particular person may have no credit cards (optional relationship) or any number of credit cards. Conversely, a particular credit card must belong to one and only one person.
Person
Names One or More
Example A particular person must have at least one name (required relationship) and may have any number of names. Conversely, a particular name may belong to no person or any number of people.
Figure 3-1
Notation Used to Represent Data Relationships
Note:
For all data structure diagrams in this chapter, lack of notation indicates a one only relationship.
Data Types
In addition to the simple C data types, the API uses the following nine data types defined by Remedy (in ar.h and nt.h, respectively):
typedef typedef typedef typedef typedef typedef unsigned char char unsigned long char char long ARBoolean; AREntryIdType[AR_MAX_ENTRYID_SIZE+1]; ARInternalId; ARNameType[AR_MAX_NAME_SIZE+1]; ARServerNameType[AR_MAX_SERVER_SIZE+1]; ARTimestamp; NTBoolean; NTNameType[NT_MAX_NAME_SIZE+1]; NTServerNameType[NT_MAX_SERVER_SIZE+1];
typedef unsigned char typedef char typedef char
The legend in Figure 3-2 applies to all data structure diagrams in this chapter. Structure types are distinguished from simple data types by being shaded. For simplicity, the data types defined by Remedy are considered simple types.
3-2
Lists
Structure Simple Data Type
Figure 3-2
Legend for Data Structure Diagrams
The purpose of the following structure diagrams is to illustrate the relationships between various data structures. Some of the simple data elements contained within a structure are not shown. Not all structures are broken down to the level of simple data types. Unless otherwise specified, refer to ar.h and nt.h for complete structure and variable definitions.
Lists
Lists are used throughout the API to manipulate sets of objects of a particular type. For example, ARNameList is used to manipulate any set of names. ARDiaryList is used to manage the group of entries contained in a diary field. AREntryListList is used to represent any group of entries in a schema. ARFilterActionList is used to define the set of actions to be performed when a filter or escalation is executed. While each type of list has its own data structure, all list structures have the same form:
typedef struct { unsigned int AR<xxx>Struct } AR<xxx>List; numItems; *<xxx>List;
Each list structure consists of an integer that identifies the number of items in the list and a pointer to the allocated memory containing those items. If the number of items is zero, the pointer is ignored (and is usually set to NULL). An example that uses the ARFilterActionList structure is shown in Figure 3-3.
Data Structures
3-3
unsigned int ARFilterActionList

Pointer
ARFilterActionStruct
Figure 3-3
Generic List Structure
Note:
For simplicity, subsequent structure diagrams do not illustrate the numItems element (unsigned int) for any list structures. All list structures in the API have the number of items in the list as their first component.
In general, lists are handled as arrays instead of linked lists. All items in the structure are stored in a single area of memory, with the pointer identifying the memory address of the first item in the array. If the item structure itself (ARFilterActionStruct in Figure 3-3) contains a pointer, the nested memory is not contained within the array but is allocated separately.
High-Level Object Relationships

Before discussing specific data structures, it is helpful to understand the high-level relationships between AR System objects (see the Action Request System Administrators Guide, Volume 1 for definitions and descriptions of these objects). As illustrated in Figure 3-4, the foundation of all client programs built on the AR System is the schema (though the AR System API still uses this term, the Remedy client tools now refer to schemas as forms). A client program must access at least one and can access many schemas.
3-4
API Program
Applications
Schemas
Guides
Menus
Views
Fields
Entries
Filters
Escalations
Active links
subtype
Nondata fields
Data fields
Figure 3-4
Your client program can also have any number of menus and containers. Unlike schemas, however, menus and containers are not required. Containers, which are used to create guides and applications, can be owned by either a server or a given schema. Applications can contain one to many schemas. Guides are associated with one schema, but can contain one to many active links. There are three types of schemas. The most common, data schemas, contain data in the AR System database. Join schemas show data from two or more data schemas with a common matching field, and display-only schemas show data from one data schema. These latter two schema types do not contain data themselves. When you modify values in a join or display-only schema, you are changing the data in its parent data schemas. Each schema must have at least one view (the default view) but can have many views. Similarly, each data schema must have at least one field but is likely to have many fields. (In actual practice, every data schema is
Data Structures
3-5
automatically created with nine core fields that cannot be deleted. Refer to the Action Request System Administrators Guide, Volume 1 for more information about core fields.) Fields actually come in two typesdata fields and nondata (trim, control, page, and table) fields. A schema must have at least one data field. Nondata fields are optional. Although most schemas have many entries, a schema can exist without an entry (though the AR System API still uses this term, the Remedy client tools now refer to entries as requests). Similarly, any number of filters, escalations, or active links can be associated with a schema, but these objects are not required. Both active links and menus can be associated with a field. While active links can be associated with either data or control fields, menus can only be associated with data fields. The relationships between them, however, are exactly reversed. An active link must be associated with a particular schema. An active link can be associated with only one data or control field. However, a data or control field can have any number of active links associated with it. A menu can be associated with any number of data fields, both within an individual schema and across multiple schemas. However, a data field can have only one menu associated with it.
Login and Session Information

Almost every AR System API function has a control parameter as its first input argument. This parameter contains the login and session information necessary for connecting to an AR System server and, thus, is required for almost every operation. The control parameter is a pointer to an ARControlStruct structure, shown in Figure 3-5.
3-6
Login and Session Information
ARControlStruct Operation Time
Cache ID
User
Password
Language
Session ID
Server
long
ARTimestamp
ARNameType
ARNameType
char[ ]
unsigned long
char[ ]
Figure 3-5
Structure Used to Provide Required Login Information
This structure consists of seven elements: Cache ID Identifies the cache area allocated by the server to store user information. It should be initialized to zero before the first API call. This value is assigned by the server and should not be changed, enabling the server to use the cache instead of reloading user information for each API call. A time stamp identifying the date and time the operation occurred on the server. The server assigns this value for each API call. The login name to use when connecting to the server. The privileges associated with this user determine whether the API function call can be performed. The password for the specified user name, in clear text. The API encrypts this parameter before sending it to the server. A string specifying the language to use when returning error messages (if a message catalog exists), formatting date/time information, and sorting or comparing values. It should match language strings used by setlocale. Specifying C or an empty string specifies the default language. An identifier for the session control block. The session control block is a structure containing all data needed to maintain the state of API operations. Each API session has a unique session control block, created when you initialize the session by calling ARInitialization. A string specifying the name of the server to connect to.
Operation Time User
Password Language
Session ID
Server
Data Structures
3-7
Nearly all function calls require the login and session information contained in ARControlStruct (stored in both single- and multiple-server environments) because the API does not always maintain a server connection between calls. When you call ARInitialization at the beginning of your program, an ARControlStruct is returned. This is the structure that you pass as an input parameter in subsequent API calls.
Status Information
Nearly every API function has a status parameter as its last return value. This parameter contains status information about the success or failure of the call. The status variable is a pointer to an ARStatusList structure, shown in Figure 3-6 (NTStatusList has an identical form).
ARStatusList Message Type
Pointer
ARStatusStruct Message Text

Pointer
Message Number
Appended Text
Pointer
unsigned int
long char char
Figure 3-6
Structure Used to Return Function Status
Like all list structures in the AR System and Remedy Notifier (see Lists on page 3-3), ARStatusList consists of zero or more ARStatusStruct items. Each ARStatusStruct item represents a message generated by the function call and consists of four elements:
3-8
Status Information
Message Type Message Number Message Text
An integer value indicating the type of message being returned. Table 3-1 describes the possible values. The error number associated with the message (defined in
arerrno.h and nterrno.h).
The message text in the language specified in ARControlStruct (if possible). The message length is limited by AR_MAX_MESSAGE_SIZE (255 bytes) and NT_MAX_MESSAGE_SIZE (256 bytes). To get the text of the message in the local language, call ARGetTextForErrorMessage. Text that augments the message text. This text may come from the AR System server, the operating system, or database management system. The length is limited by AR_MAX_MESSAGE_SIZE (255 bytes) and NT_MAX_MESSAGE_SIZE (256 bytes). In previous releases of the AR System, this information was appended to the message text. Message Type Values for AR/NTStatusStruct Operation successfulstatus may contain one or more informational messages. Operation successful, but some problem encounteredstatus contains one or more warning messages and may also contain informational messages. Operation failedstatus contains one or more error messages and may also contain warning or informational messages. Operation failedstatus may contain one or more messages.
Appended Text
Table 3-1
0 1 AR_RETURN_OK NT_RETURN_OK
AR_RETURN_WARNING NT_RETURN_WARNING
AR_RETURN_ERROR NT_RETURN_ERROR AR_RETURN_FATAL NT_RETURN_FATAL
3 4
AR_RETURN_BAD_STATUS Invalid status parameteroperation cancelled. NT_RETURN_BAD_STATUS
The example shown in Figure 3-7 illustrates the physical layout of the ARStatusList structure.
Data Structures
3-9
main() { ARStatusList status; int rtn; rtn = ARGetEntry(..., &status); ... ... } status numItems statusList
Stack Heap
messageType messageNum
2 197 Unrecognized keyword
[0]
messageText appendedText
2 90 Cannot establish a network connection to the AR System server MYSERVER : RPC: Name to address translation failed - No such hostname 1 51 Field ID specified does not exist in this form 99 Example of ARStatusList Structure
[1]
[2]
Figure 3-7
3-10
Permission Information
In this example, the status parameter is defined as a stack variable of type ARStatusList and consists of an integer value identifying the number of messages in the list (three in this case) and a pointer to their location on the heap. This memory space is allocated dynamically by the system based on the size and number of messages being returned. The messages themselves are stored in an array of ARStatusStruct structures, each of which contains the message type, the message number, and pointers to the message text and any appended text. The messages are sorted in decreasing order of severity, based on the message type value (see Error Checking on page 4-9). The return value for the function is the message type associated with the first (most recent and most serious) message in the list. In this case, the function return value is 2. Use standard array notation to access individual elements in the list. For example, status.statusList[0].messageText identifies the message text associated with the first message, while status.statusList[1].messageNum gives you the message number for the second message.
Permission Information
Permission for an AR System object is generally defined by simply specifying the list of groups that can access it (by using the ARInternalIdList structure). The groupList parameter for the active link functions is of this type. For schemas, fields, and containers, however, you can assign different levels of access to different groups. Permission for these objects is defined by the groupList (schemas and containers) and permissions (fields) parameters, both of which are pointers to structures of type ARPermissionList, shown in Figure 3-8.
ARPermissionList
Pointer
ARPermissionStruct
Group ID
Permission Level
ARInternalId
unsigned int
Figure 3-8
Structures Used to Define Field and Schema Permissions
Data Structures
3-11
Each ARPermissionStruct in the list represents a particular access control group and consists of two elements: Group ID Permission Level The internal ID of the group. An integer value indicating the access privileges for the group. Tables 3-2 and 3-3 describe the possible values for schemas, containers, and fields. Schema/Container Permission Values for ARPermissionStruct Group has no access to the schema or container. Group cannot see the schema or container.
Table 3-2
0 1 2
AR_PERMISSIONS_NONE
AR_PERMISSIONS_VISIBLE Group can see the schema or container. AR_PERMISSIONS_HIDDEN
Table 3-3
0 1 2
Field Permission Values for ARPermissionStruct Group has no access to the field. Group has read-only access to the field. Group has read-write access to the field.
AR_PERMISSIONS_NONE AR_PERMISSIONS_VIEW AR_PERMISSIONS_CHANGE
Different privileges are associated with the possible values, depending on whether you are assigning permission to a schema or a field.
Representing Values
One of the most frequently used data structures in the API is ARValueStruct. This structure stores values of any data type.
ARCreateField, ARGetField, and ARSetField all take parameters of type ARValueStruct directly. Many other API functions use parameters of types that can contain ARValueStruct, for example:
s s s s
ARQualifierStruct (see Figure 3-10) ARFieldValueList (see Figure 3-16) ARDisplayInstanceList (see Figure 3-13) ARFilterActionList (see Figure 3-20)
3-12
Representing Values
s s
ARActiveLinkActionList (see Figure 3-21) ARReferenceStruct (see Figure 3-29)
ARValueStruct Data Type
unsigned int
Keyword
Integer
Real
Character
Pointer
}
union
}
Diary
Pointer
Enumerated
unsigned int
long
double char char
unsigned long
Time
Bitmask
Byte List
Pointer
Decimal
Pointer
Attachment
Pointer
Unsigned Long
Coordinate List
Pointer
ARTimestamp
unsigned long
ARByteList
char
ARAttachStruct
unsigned long
ARCoordList
Pointer
ARCoordStruct
Figure 3-9
Structures Used to Represent Any Value
As shown in Figure 3-9, ARValueStruct consists of two elements: Data Type Value An integer value indicating the data type of the value being passed. Table 3-4 describes the possible values. The value itself (represented by using data types or structures appropriate to the type of value).
Data Structures
3-13
Table 3-4
0 1 2 3 4 AR_DATA_TYPE_NULL
Data Type Values for ARValueStruct Specifies NULL value. An integer identifying the particular keyword (defined in ar.h). A 32-bit signed integer value. A 64-bit floating-point value. A null-terminated string that requires freeing allocated space. A NULL pointer of this type is equivalent to using AR_DATA_TYPE_NULL. A null-terminated string that requires freeing allocated space. A NULL pointer of this type is equivalent to using AR_DATA_TYPE_NULL. A set of integer values (beginning with zero) that represents possible selection values as an indexed list. You must specify a field limit by using ARNameList to define string values for each selection (see Table 3-12 on page 3-22). A UNIX-style date/time stamp (number of seconds since midnight January 1, 1970). A 32-bit unsigned integer value in which each bit represents a flag turned on or off. A list of bytes containing binary data (represented by using the ARByteList structure). A fixed-point decimal field. Values must be specified in C locale, for example 1234.56 An attachment field. A 32-bit unsigned integer value. A list of (x,y) coordinate pairs.
AR_DATA_TYPE_KEYWORD AR_DATA_TYPE_INTEGER AR_DATA_TYPE_REAL AR_DATA_TYPE_CHAR
AR_DATA_TYPE_DIARY
AR_DATA_TYPE_ENUM
7 8 9
AR_DATA_TYPE_TIME AR_DATA_TYPE_BITMASK AR_DATA_TYPE_BYTES
10 AR_DATA_TYPE_DECIMAL 11 AR_DATA_TYPE_ATTACH 40 AR_DATA_TYPE_ULONG 41 AR_DATA_TYPE_COORDS
3-14
Representing Qualifications
Note:
When passing a diary value to ARCreate or ARSet<object> functions, the ARValueStruct value is the additional text to append to the diary field. When retrieving diary values or passing a diary value to ARMergeEntry, the ARValueStruct value is a diary-formatted string containing the full diary text. Use the ARDecodeDiary function to decode this string into an array of time-stamped entries.
Representing Qualifications
Many tasks in the AR System use qualifications. For example, a qualification (or lack thereof) determines which entries to retrieve when creating a query list (ARGetListEntry) or computing entry statistics (ARGetEntryStatistics). A qualification also determines whether an active link or filter is executed and which entries an escalation acts upon. Every qualification is composed of a set of zero or more conditions that limit the set of entries retrieved. As shown in Figure 3-10, ARQualifierStruct represents each individual condition by using a tree structure comprised of an operation and one or two operands (depending on the type of operation). The operands can point to other structures of type ARQualifierStruct. This recursion allows you to represent any qualification by using a series of nested ARQualifierStruct structures. You can avoid the complexity of storing a qualification in this structure by using ARLoadARQualifierStruct (see page 6-144). This function takes the specified qualification string and loads it into an ARQualifierStruct.
Data Structures
3-15
ARQualifierStruct Operation
unsigned int And/Or Conditions Left Operand

Pointer
Not Condition
Pointer
}
union
}
Relational Operator
Pointer
Right Operand
Pointer
ARQualifierStruct
ARRelOpStruct Right Operand
ARQualifierStruct
ARQualifierStruct
Left Operand
ARFieldValueOrArithStruct
}
union
}
Field ID Value Arith Op
Pointer
Status History
ARInternalId
ARValueStruct See Figure 3-9
ARArithOpStruct Left Operand
ARStatHistoryValue
Right Operand
Figure 3-10
Structures Used to Represent Any Qualification
3-16
Qualifications that Use Conditional Operators
The ARQualifierStruct structure consists of two elements: Operation Operands An integer value indicating the type of conditional operation to perform. Table 3-5 describes the possible values. The components of the operation (represented by using structures appropriate to the type of value). Table 3-5
0 1 2 3 4 AR_COND_OP_NONE AR_COND_OP_AND AR_COND_OP_OR AR_COND_OP_NOT AR_COND_OP_REL_OP
Operation Values for ARQualifierStruct No qualification A qualification using the AND operator A qualification using the OR operator A qualification using the NOT operator A qualification using a relational operator
If a query has no qualification criteria, you can either set the operation type to zero (AR_COND_OP_NONE) or pass NULL for the qualifier parameter.
Qualifications that Use Conditional Operators

Qualifications that use the AND or OR operators require two operands, while qualifications that use the NOT operator require one. In both cases, the operands consist of pointers to nested ARQualifierStruct structures.
Qualifications that Use Relational Operators

Qualifications that use a relational operator require one operand, consisting of a pointer to an ARRelOpStruct structure. The ARRelOpStruct structure consists of a tag identifying the operation type and two operands specifying the values to compare: Operation Operands An integer value indicating the type of relational operation to perform. Table 3-6 describes the possible values. The components of the operation (represented by using the ARFieldValueOrArithStruct structure).
Data Structures
3-17
Table 3-6
1 2 3 4 5 6 7 AR_REL_OP_EQUAL AR_REL_OP_GREATER
Operation Values for ARRelOpStruct Tests whether the left operand is equal to the right operand Tests whether the left operand is greater than the right operand Tests whether the left operand is greater than or is equal to the right operand Tests whether the left operand is less than the right operand Tests whether the left operand is less than or is equal to the right operand Tests whether the left operand is not equal to the right operand Tests whether the left operand is LIKE the pattern defined by the right operand
AR_REL_OP_GREATER_EQUAL AR_REL_OP_LESS AR_REL_OP_LESS_EQUAL AR_REL_OP_NOT_EQUAL AR_REL_OP_LIKE
Defining Operands for a Relational Operation

The values to compare in a relational operation are represented by using the ARFieldValueOrArithStruct structure. This structure has two elements: Tag Value An integer value indicating the type of value. Table 3-7 describes the possible values. The value itself (represented by using data types or structures appropriate to the type of value). Table 3-7
1 2 3 AR_FIELD AR_VALUE AR_ARITHMETIC
Value Types for ARFieldValueOrArithStruct A schema field value A constant or keyword value represented by using ARValueStruct (see page 3-12) A result value from an arithmetic operation represented by using ARArithOpStruct (see Defining an Arithmetic Result Value) A value from the Status-History core field represented by using ARStatHistoryValue (see Defining a Status History Value)
AR_STAT_HISTORY
3-18
Qualifications that Use Relational Operators
Defining an Arithmetic Result Value

ARArithOpStruct represents the result value from an arithmetic operation. Similar in form to ARRelOpStruct (see page 3-17), this structure consists of a tag identifying the operation type and two operands specifying the values:
Operation Operands
An integer value indicating the type of arithmetic operation to perform. Table 3-8 describes the possible values. The components of the operation (represented by using the ARFieldValueOrArithStruct structure). Table 3-8 Operation Values for ARArithOpStruct Add the left and right operands Subtract the right operand from the left operand Multiply the left and right operands Divide the left operand by the right operand Find the remainder after dividing the left operand by the right operand Change the sign of the right operand (left operand is ignored)
1 2 3 4 5 6
AR_ARITH_OP_ADD AR_ARITH_OP_SUBTRACT AR_ARITH_OP_MULTIPLY AR_ARITH_OP_DIVIDE AR_ARITH_OP_MODULO AR_ARITH_OP_NEGATE
Defining a Status History Value The Status History core field is a special selection field that stores user and time stamp information for each of the defined status values. You can specify a value from this field by using the ARStatHistoryValue structure. This structure consists of two elements: Index Tag An enumerated value identifying the particular status value to use in the operation. An integer value indicating which information (about that status) to use. Table 3-9 describes the possible values. Table 3-9
1 2
Tag Values for ARStatHistoryValue The user who assigned the specified status The time when the status was assigned
AR_STAT_HISTORY_USER AR_STAT_HISTORY_TIME
Data Structures
3-19
Schemas
Compound schemas are represented by using the ARCompoundSchema structure, shown in Figure 3-11. The structure can also represent a base schema.
ARCompoundSchema
Schema Type
unsigned int
Join
}
union
}
View ARViewSchema
ARJoinSchema Join Criteria
Schema A
Schema B
Option
ARNameType
ARNameType
ARQualifierStruct See Figure 3-10
unsigned int
Figure 3-11
Structures Used to Create Join Schemas
The ARCompoundSchema structure consists of two elements: Schema Type Join Definition An integer value indicating the type of schema. Table 3-10 describes the possible values. A union that defines the schema. Join schemas, the only member of the union currently supported, are defined by an ARJoinSchema structure containing the names of the two member schemas (either of which could also be join schemas), the criteria for joining them, and a bitmask indicating various join options.
3-20
Fields
Table 3-10
1 2 4
Schema Type Values for ARCompoundSchema Base schema Join schema (has two base schemas) Display-only schema (contains only display-only fields)
AR_SCHEMA_REGULAR AR_SCHEMA_JOIN AR_SCHEMA_DIALOG
The join options, shown in Table 3-11, define the join type and the action to take when users modify entries (see ARSetEntry on page 6-156). Table 3-11
0 1 0 1 AR_JOIN_OPTION_NONE AR_JOIN_OPTION_OUTER AR_JOIN_SETOPTION_NONE AR_JOIN_SETOPTION_REF
Join Options for ARJoinSchema Inner join Outer join Allow users to update fields used in the join criteria Do not allow users to update fields used in the join criteria
Fields
The following section describes some of the structure types related to creating, retrieving, and modifying field definitions. Each of these structures is used as a parameter type for the ARCreateField, ARGetField, and ARSetField functions (see pages 6-19, 6-82, and 6-161, respectively).
Defining Field Limits

The limit parameter defines the value limits for a data field, with the data type of the field determining the type of limits you can specify. This parameter is a pointer to an ARFieldLimitStruct structure, shown in Figure 3-12.
Data Structures
3-21
ARFieldLimitStruct Data Type
unsigned int
Integer
Real
Character
}
union
}
Diary Enum Bitmask
ARIntegerLimitsStruct
ARRealLimitsStruct
ARCharLimitsStruct
ARDiaryLimitsStruct
ARNameList
ARNameList
Pointer
Pointer
ARTableLimitsStruct Table
ARColumnLimitsStruct Column
ARAttachLimitsStruct Attachment
ARDecimalLimitsStruct Decimal
ARNameType ARNameType
Figure 3-12
Structures Used to Define Field Value Boundaries
ARFieldLimitStruct enables you to define value limits for data fields of any type, much like ARValueStruct enables you to specify values of any data type (see Figure 3-9). This structure consists of two elements:
Data Type Limit
An integer value indicating the data type of the field. Table 3-12 describes the possible values. The actual limits to assign (represented by using structures appropriate to the type of value).
Table 3-12
0 2 3
Data Type Values for ARFieldLimitStruct (1 of 2) Field has no defined limits. Lower- and upper-range limits, defined by using ARIntegerLimitsStruct. Lower- and upper-range limits, defined by using ARRealLimitsStruct. You can also specify the display precision to use.
AR_FIELD_LIMIT_NONE AR_DATA_TYPE_INTEGER AR_DATA_TYPE_REAL
3-22
Defining Field Limits
Table 3-12
4
Data Type Values for ARFieldLimitStruct (2 of 2) Maximum field length, defined by using ARCharLimitsStruct. Specify zero to indicate no maximum.a You can also specify a character menu to attach (and whether selecting from the menu appends or overwrites text already in the field), a default query-by-example qualification type, a field character pattern, and whether the field is indexed for Full Text Search. Specifies whether the field is indexed for Full Text Search by using ARDiaryLimitStruct. String values for an enumerated list, defined by using ARNameList (see Table 3-4 on page 3-14) (required). Values for a bitmask, defined by using ARNameList (not supported by Remedy at this time). Lower- and upper-range limits, defined by using ARDecimalLimitsStruct. You can also specify the precision to use. Maximum size of the attachment and attachment type (embedded is the only type supported by Remedy at this time), defined by using ARAttachLimitsStruct. Number of columns, search qualification, maximum number of rows to retrieve, schema name, and server name of the table, defined by using ARTableLimitsStruct. Parent field ID, parent schema ID, and number of characters to display, defined by using ARColumnLimitsStruct.
AR_DATA_TYPE_CHAR
5 6
AR_DATA_TYPE_DIARY AR_DATA_TYPE_ENUM
AR_DATA_TYPE_BITMASK
10 AR_DATA_TYPE_DECIMAL
11 AR_DATA_TYPE_ATTACH
33 AR_DATA_TYPE_TABLE
34 AR_DATA_TYPE_COLUMN
a. See the Input Length database property in in the Action Request System Administrators Guide, Volume 1 for more information about storing long character strings.
Data Structures
3-23
Defining Field Display Properties

The display properties associated with a field fall into two categoriesthose that are common to all schema views and those that are specific to a particular schema view. Both types are represented as lists of zero or more properties by using the ARPropList structure. The common display properties are collected in one ARPropList structure. The display instance properties are collected in a series of additional ARPropList structures, but each of these is linked to a particular view (VUI). These view-specific property lists are represented by zero or more ARDisplayInstanceStruct structures. All of these structures are then collected in an ARDisplayInstanceList structure, shown in Figure 3-13.
ARDisplayInstanceList Common Properties Instance Properties
Pointer
ARPropList ARDisplayInstanceStruct Display Properties
Pointer
ARPropStruct
VUI ID
ARInternalId Property Tag Value
ARPropList
unsigned long
Figure 3-13
Structures Used to Define Field Display Properties
The dInstanceList parameter is a pointer to a structure of this type and is used to pass all field display properties when creating, retrieving, or modifying field definitions. The common display properties are represented by using an embedded ARPropList. This list contains zero or more ARPropStruct items, each of which
3-24
Defining Field Display Properties
represents one display property. The ARPropStruct structure contains two elements: Property Tag Value An integer value identifying the particular display property. See Display Properties on page 6-22 for a description of the possible values. The value for the property represented by using
ARValueStruct (see page 3-12).
The instance display properties are represented as a series of ARDisplayInstanceStruct structures, each of which also consists of two components: VUI ID Display Properties The internal ID associated with the view. The field display properties specific to that view represented by using ARPropList.
Each ARDisplayInstanceStruct represents a display instance for the field. Specifying a view in the ARDisplayInstanceList structure includes the field in the view, even if you do not define any display properties specific to that view. In this case, the system uses properties defined in the common properties list. Note: The ARPropList structure is also used by the ARCreateVUI, ARGetVUI, and ARSetVUI functions (see pages 6-40, 6-139, and 6-182, respectively). The dPropList parameter is a pointer to a structure of this type and is used to pass view-type display properties.
Data Structures
3-25
Using ARCoordList to Specify Field Size and Location

The ARCoordList data type is used to specify the size and location of certain fields and their components. These values are scaled by the AR System client tools so that fields display consistently across different user environments. Bounding Boxes and Coordinate Lists The AR_DPROP_*_BBOX and AR_DPROP_COORDS display properties are all ARCoordList structures (documented beginning on page 6-23). The AR_DPROP_*_BBOX properties identify the bounding box, or screen boundaries, for screen elements. AR_DPROP_COORDS identifies the screen location for lines and boxes. When specifying coordinate values for either of these properties, remember that:
s s
The order in which you specify coordinate pairs is important. Horizontal and vertical are the only line orientations currently supported by Remedy Administrator and Remedy User. Neither of the client tools display diagonal lines for lines or boxes if you specify coordinates that are not on the same x- or y-axis.
Coordinate Value Scaling To minimize display differences across a variety of operating systems and screen resolutions, the AR System client tools normalize all coordinate values before storing them in the database and then map these values to pixels in the current environment upon retrieval. You must apply the same translation algorithms when specifying or retrieving coordinate data in order for Remedy Administrator and Remedy User to display the field correctly. Use this algorithm to normalize coordinate values before storing them:
Normalized = (Pixel * AR_FIXED_POINT_PRECISION * Static Font Metric) / (Dynamic Font Metric * Platform Scale)
Use this algorithm to map coordinate values to pixels upon retrieval:

Pixel = ((Normalized * Dynamic Font Metric / Static Font Metric / Platform Scale) + (AR_FIXED_POINT_PRECISION / 2)) / AR_FIXED_POINT_PRECISION
3-26
Mapping Fields in Join Schemas
The value for AR_FIXED_POINT_PRECISION is 100 on all platforms. The other equation values are platform-specific. The Windows values are shown in Table 3-13. Table 3-13 Equation Component Static Font Metric Dynamic Font Metric (using System font style) Platform Scale 9 (Average character width + maximum character width) / 2 1.0 Coordinate Scaling for Windows x-value 13 Font height y-value
1.0
Mapping Fields in Join Schemas

Because join schemas are logical objects instead of actual data tables, you must map each field in a join schema to a field in an underlying base schema. This mapping is specified by the fieldMap parameter, defined as a pointer to an ARFieldMappingStruct structure, shown in Figure 3-14.
ARFieldMappingStruct Field Type
unsigned int
Join
}
union
}
View ARViewMappingStruct Field ID
ARJoinMappingStruct Schema Index
unsigned int
ARInternalId
Figure 3-14
Structures Used to Map Join Fields to Schema Fields
Data Structures
3-27
The ARFieldMappingStruct structure consists of two elements: Field Type Join Mapping An integer value indicating the type of field. Table 3-14 describes the possible values. A union that defines the field mapping. Join fields, the only union member supported at this time, are defined by an ARJoinMappingStruct structure containing the index of the base schema and the ID of the field to map to this field. Field Type Values for ARFieldMappingStruct Field in a base schema Field in a join schema
Table 3-14
1 2
AR_FIELD_REGULAR AR_FIELD_JOIN
The ARJoinMappingStruct structure also contains two components: Schema Index Field ID An integer value identifying the member schema the field maps to. Table 3-15 describes the possible values. The internal ID associated with the field. Schema Index Values for ARJoinMappingStruct Primary schema in a join Secondary schema in a join
Table 3-15
0 1
AR_FIELD_MAPPING_PRIMARY AR_FIELD_MAPPING_SECONDARY
If the member schema is also a join schema, you must create fields in all nested join schemas until you can map the field to an underlying base schema.
Entries
The most common operations in the AR System involve creating, retrieving, or updating entries. The following section describes some of the structures used to perform these tasks.
Retrieving Entry Lists

The first group of structures relate to retrieving a list of entries. You can retrieve entry lists in two ways: with the fields of each entry as one
3-28
concatenated string (ARGetListEntry on page 6-95) or as field/value pairs (ARGetListEntryWithFields on page 6-97). In both cases, the function performs the query specified by the qualifier parameter (of type ARQualifierStruct) and returns the list of entries that match the search criteria. Note: The system identifies entries in join schemas by concatenating the entry IDs from the member schemas. As a result, an entry ID can consist of one or more values of type AREntryIdType and, therefore, is represented by using the AREntryIdList structure.
Entries Returned as Concatenated Strings

The ARGetListEntry function returns an entryList output parameter that is a pointer to an AREntryListList structure, illustrated in Figure 3-15.
AREntryListList
Pointer
AREntryListStruct Short Description

Pointer
Entry ID
AREntryIdList char
Pointer
AREntryIdType
Figure 3-15
Structures Used to Represent List of Entries as Concatenated Strings

AREntryListList consists of zero or more AREntryListStruct items, each of which represents a matching entry. The AREntryListStruct structure consists of two elements:
Entry ID Short Description
The ID associated with the entry A 128-character string containing data concatenated from the fields specified by the getListFields parameter.
Data Structures
3-29
Entries Returned as Field/Value Pairs

The ARGetListEntryWithFields function returns an entryList output parameter that is a pointer to an AREntryListFieldValueList structure, illustrated in Figure 3-16.
AREntryListFieldValueList
Pointer
AREntryListFieldValueStruct
Entry ID AREntryIdList
Pointer
ARFieldValueList
Pointer
AREntryIdType Field ID
ARFieldValueStruct Value
ARInternalId
ARValueStruct
Figure 3-16
Structures Used to Represent List of Entries as Field/Value Pairs
AREntryListFieldValueList consists of zero or more AREntryListFieldValueStruct items, each of which represents a matching entry. The AREntryListFieldValueStruct structure consists of an Entry ID and a list of ARFieldValueStruct structures, each of which represents a field in the entry. An ARFieldValueStruct structure consists of two elements:
Field ID Value
The internal ID associated with the field The value for the field represented by using ARValueStruct (see page 3-12)
Specifying Fields to Retrieve

The getListFields parameter of both ARGetListEntry and ARGetListEntryWithFields identifies the fields to return with each entry. It also defines the column width and column separator for each field, which are used by ARGetListEntry but ignored by ARGetListEntryWithFields. This
3-30
parameter is a pointer to an AREntryListFieldList structure, shown in Figure 3-17.

AREntryListFieldList
Pointer
AREntryListFieldStruct Column Width
Field ID
Separator
ARInternalId
unsigned int
char[10]
Figure 3-17
Structures Used to Define Column Fields in Entry List
Each AREntryListFieldStruct item specifies a particular field and associated display information: Field ID Column Width Separator The internal ID associated with the field. An integer value indicating the number of characters to display for the field (ARGetListEntry only). For ARGetListEntryWithFields, set this value to 0. The characters to display after the field data (ARGetListEntry only). The separator can contain from zero to 10 characters. For ARGetListEntryWithFields, set this value to one blank space.
Note:
For ARGetListEntry, the combined length of all specified fields, including separator characters, can be up to 128 bytes (limited by AR_MAX_SDESC_SIZE).
Sorting a List of Entries

The sortList parameter of both ARGetListEntry and ARGetListEntryWithFields specifies the sort order for a list of entries. This parameter is a pointer to an ARSortList structure.
Data Structures
3-31
ARSortList
Pointer
ARSortStruct
Field ID
Sort Order
ARInternalId
unsigned int
Figure 3-18
Structures Used to Define Sort Fields in Entry List
As shown in Figure 3-18, ARSortList contains zero or more ARSortStruct items. Each ARSortStruct consists of two elements: Field ID Sort Order The internal ID associated with the field. An integer value indicating the sort order for the field. Table 3-16 describes the possible values. Table 3-16
1 2 AR_SORT_ASCENDING AR_SORT_DESCENDING
Sort Order Values for ARSortStruct Sort values in field in ascending order Sort values in field in descending order
The overall order of entries in the list is determined by the value you specify for each field and the order of ARSortStruct items in the ARSortList structure.
Manipulating Individual Entries

The ARGetListEntry and ARGetListEntryWithFields functions (see pages 6-95 and 6-97) return a list of entries that match specified criteria. This list contains the Entry IDs for the matching entries but does not contain all field values. To retrieve or modify individual entries, you must pass the entry ID as an input argument to the ARGetEntry or ARSetEntry functions (see pages 6-74 and 6-156). Both of these functions, as well as the ARCreateEntry (see page 6-15) and ARGetListEntryWithFields functions, use the ARFieldValueList structure to pass field values for individual entries. The ARFieldValueList structure,
3-32
Manipulating Individual Entries
shown in Figure 3-16, consists of zero or more ARFieldValueStruct items. Each of these structures contains a field and its value (a field/value pair): Field ID Value The internal ID associated with the field. The value for the field represented by using ARValueStruct (see page 3-12). This value must be of the same data type as the field or have the data type set to zero (AR_DATA_TYPE_NULL).
All entry data, whether being submitted, retrieved, or modified, is represented by using this structure. Figure 3-19 shows a code fragment that loads data into this structure.
#include "arstruct.h" /* symbolic constants for core field IDs */
int main( int argc, char *argv[] ) { ARFieldValueList fieldList; ARFieldValueStruct *fldStrcp; ... ...
/* structure to populate /* working pointer
*/ */
/****************************************************************/ /* Populate fieldList with data */ /****************************************************************/ fieldList.numItems = 3; fieldList.fieldValueList=malloc(3*sizeof(ARFieldValueStruct)); fldStrcp = fieldList.fieldValueList; if( fldStrcp == NULL){ fprintf(stderr,"Out of memory, malloc failure\n"); exit(1); } fldStrcp[0].fieldId = AR_CORE_SUBMITTER; fldStrcp[0].value.dataType = AR_DATA_TYPE_CHAR; fldStrcp[0].value.u.charVal = "Bob"; fldStrcp[1].fieldId = AR_CORE_STATUS; fldStrcp[1].value.dataType = AR_DATA_TYPE_ENUM; fldStrcp[1].value.u.enumVal = STATUS_NEW; fldStrcp[2].fieldId = AR_CORE_SHORT_DESCRIPTION; fldStrcp[2].value.dataType = AR_DATA_TYPE_CHAR; fldStrcp[2].value.u.charVal = "Broken computer"; ... ... }
Figure 3-19
Example of Populating ARFieldValueList
Data Structures
3-33
Note:
In this example, the charVal members for the Submitter and Short Description fields are on the stack. As a result, you cannot use the FreeARFieldValueList function to free this structure, because the FreeAR routines assume that all structure components are in allocated memory (on the heap). For more information, see Freeing Allocated Memory on page 3-58.
Retrieving Multiple Entries

The ARGetMultipleEntries function (see page 6-115) returns a list of entries with the specified Entry IDs. You can retrieve data for specific fields or all (accessible) fields. ARGetMultipleEntries performs the same action as ARGetEntry but is easier and more efficient than retrieving multiple entries one by one. This function uses the ARFieldValueListList structure to return field values for the specified entries. This structure consists of zero or more ARFieldValueList structures, shown in Figure 3-16.
ARGetMultipleEntries uses the AREntryIdListList structure to pass Entry IDs for the specified entries. This structure consists of zero or more AREntryIdList structures, shown in Figure 3-16.
You can also use the ARGetMultipleEntries function to check whether the entries in the AREntryIdListList exist without transferring any field data, conserving network traffic. The function has an existList parameter that returns a pointer to an ARBooleanList structure. Each ARBoolean flag in that list specifies whether a given Entry ID exists in the database.
Filters, Escalations, and Active Links

The ARCreate<object>, ARGet<object>, and ARSet<object> functions for filters, escalations, and active links all have an actionList parameter that defines the set of one or more actions performed for entries that match the associated qualification. Because the actions available for filters and escalations are different than those for active links, the actions associated with these objects are represented by using different data structures.
3-34
For filters and escalations, the actionList parameter is a pointer to an ARFilterActionList structure, shown in Figure 3-20.
ARFilterActionList
Pointer
ARFilterActionStruct
Filters only
Notify
Message
}
union
}
Log to File
Pointer
Set Fields
Run Process
pointer
ARFilterActionNotify
ARStatusStruct See Figure 3-6
char
ARFieldAssignList See Figure 3-22
char
ARInternalIdList
Pointer Pointer
ARPushFieldsList Push Fields
ARSQLStruct Direct SQL
ARGotoActionStruct Go To
ARInternalId ARPushFieldsStruct See Figure 3-23
Figure 3-20
Structures Used to Define Filter or Escalation Actions
ARFilterActionList contains zero or more ARFilterActionStruct items. Each ARFilterActionStruct represents one filter or escalation action and consists of two elements:
Action Type Action Definition
An integer value indicating the type of action. Table 3-17 describes the possible values. The specific action to perform (represented by using data types or structures appropriate to the type of action). Action Values for ARFilterActionStruct (1 of 2) No action Send a notification to the specified user Return the specified message (filters only) Write the specified text to a log file
Table 3-17
0 1 2 3
AR_FILTER_ACTION_NONE AR_FILTER_ACTION_NOTIFY AR_FILTER_ACTION_MESSAGE AR_FILTER_ACTION_LOG
Data Structures
3-35
Table 3-17
4 5 6
Action Values for ARFilterActionStruct (2 of 2) Update values for the specified fields Execute the specified command Push data from the current operation to a field in another schema on the same server Perform the specified SQL statements execution order
AR_FILTER_ACTION_FIELDS AR_FILTER_ACTION_PROCESS AR_FILTER_ACTION_FIELDP
7 8
AR_FILTER_ACTION_SQL
AR_FILTER_ACTION_GOTOACTION Go to the filter with the specified
For active links, the actionList parameter is a pointer to an ARActiveLinkActionList structure, shown in Figure 3-21.
ARActiveLinkActionList ARActiveLinkActionStruct
Pointer
Push Fields
}
union
}
DDE
Run Macro
Set Fields
Run Process
Pointer
Message
Change Field
ARPushFieldsList
Pointer
ARActiveLinkMacroStruct
ARFieldAssignList See Figure 3-22
char
ARStatusStruct See Figure 3-6
ARDDEStruct
ARFieldCharacteristics
ARMacroParmList ARPushFieldsStruct See Figure 3-23

Pointer
ARPropList ARSQLStruct Direct SQL ARGotoActionStruct Go To ARAutomationStruct OLE Automation See Figure 3-24
Pointer
ARMacroParmStruct
ARPropStruct
Call Guide ARCallGuideStruct
Exit Guide ARExitGuideStruct
Open Dialog AROpenDlgStruct
Close Window ARCloseWndStruct
Commit Changes
Wait ARValueStruct
ARCommitARWaitStruct ChangesStruct
See Figure 3-9
Figure 3-21
Structures Used to Define Active Link Actions
The ARActiveLinkActionList structure contains zero or more ARActiveLinkActionStruct items. Like ARFilterActionStruct, each
3-36
ARActiveLinkActionStruct represents one active link action and has two
components: Action Type Action Definition An integer value indicating the type of action. Table 3-18 describes the possible values. The specific action to perform (represented by using data types or structures appropriate to the type of action). Action Values for ARActiveLinkActionStruct (1 of 2) No action Execute the specified macro Set values for the specified fields Execute the specified command Display the specified message Set characteristics for the specified field Perform the specified DDE action Transfer, or push, data from a field in the current schema to another schema Perform the specified SQL statements Perform the specified OLE automation Open a schema as a modal dialog Commit changes from a dialog to the parent schema window Close a dialog or schema window Perform the specified guide
Table 3-18
0 1 2 3 4 5 6 7
AR_ACTIVE_LINK_ACTION_NONE AR_ACTIVE_LINK_ACTION_MACRO AR_ACTIVE_LINK_ACTION_FIELDS AR_ACTIVE_LINK_ACTION_PROCESS AR_ACTIVE_LINK_ACTION_MESSAGE AR_ACTIVE_LINK_ACTION_SET_CHAR AR_ACTIVE_LINK_ACTION_DDE AR_ACTIVE_LINK_ACTION_FIELDP
8 9
AR_ACTIVE_LINK_ACTION_SQL AR_ACTIVE_LINK_ACTION_AUTO
10 AR_ACTIVE_LINK_ACTION_OPENDLG 11 AR_ACTIVE_LINK_ACTION_COMMITC
12 AR_ACTIVE_LINK_ACTION_CLOSEWND 13 AR_ACTIVE_LINK_ACTION_CALLGUIDE
Data Structures
3-37
Table 3-18
Action Values for ARActiveLinkActionStruct (2 of 2) Exit the current guide or all guides within current guide
14 AR_ACTIVE_LINK_ACTION_EXITGUIDE
15 AR_ACTIVE_LINK_ACTION_GOTOGUIDELABEL Go to the specified active link 16 AR_ACTIVE_LINK_ACTION_WAIT 17 AR_ACTIVE_LINK_ACTION_GOTOACTION
Cause the current guide to wait for user input Go to the active link with the specified execution order
Set Fields Action

The Set Fields action is one of the most complex of the filter, escalation, or active link actions. The ARFieldAssignList structure, shown in Figure 3-22, is a list of ARFieldAssignStruct items, each of which identifies a field/value pair to update. Each ARFieldAssignStruct structure contains the internal ID of the field to update (not shown) and the value to assign, specified by using ARAssignStruct, which is one of the more complex structures in the API.
ARFieldAssignList
Pointer
ARFieldAssignStruct
ARAssignStruct
}
union
}
DDE
Pointer
Value
Field
Pointer
Process
Pointer
Arith Op
Pointer
Function
Pointer
SQL Call
Pointer
ARAssignFieldStruct See Figure 3-23
char
ARArithOpAssignStruct Left Operand
ARFunctionAssignStruct
Pointer
ARDDEStruct
ARAssignSQLStruct
Right Operand
ARAssignStruct
ARAssignStruct ARAssignStruct
Active links only
Figure 3-22
Structures Used to Define Set Fields Action
3-38
Set Fields Action
The ARAssignStruct structure contains two elements: Assign Type Value An integer value indicating the type of value to assign. Table 3-19 describes the possible values. The actual value to assign (represented by using data types or structures appropriate to the type of value). Table 3-19
0 1
Assign Type Values for ARAssignStruct No value. A constant or keyword value represented by using ARValueStruct (see page 3-12). The data type of the value must match the data type of the specified field. A schema field value represented by using ARAssignFieldStruct (see Assigning a Schema Field Value). An output value from successful execution of an operating system process or command. The system generates an error if the process return code is not zero. This option is not available for active links on Windows or Macintosh clients. A result value from an arithmetic operation represented by using ARArithOpAssignStruct (see Assigning an Arithmetic Result Value).
AR_ASSIGN_TYPE_NONE AR_ASSIGN_TYPE_VALUE
AR_ASSIGN_TYPE_FIELD
AR_ASSIGN_TYPE_PROCESS
AR_ASSIGN_TYPE_ARITH
AR_ASSIGN_TYPE_FUNCTION A return value from a function represented by using ARFunctionAssignStruct (see
Assigning a Function Return Value).

6 AR_ASSIGN_TYPE_DDE
A result value from a DDE request to another application represented by using ARDDEStruct (see Assigning a DDE Result Value). This option is available for active links on Windows clients only. A result value from an SQL command represented by using ARAssignSQLStruct (see Assigning an SQL Result Value).
AR_ASSIGN_TYPE_SQL
Data Structures
3-39
Assigning a Schema Field Value

The ARAssignStruct structure contains an ARAssignFieldStruct structure that identifies a schema field value to assign in a Set Fields or Push Fields action. You can specify a value from any entry in any schema on a particular server. In a Push Fields action, an independent ARAssignFieldStruct structure identifies the schema field that is set by the operation. You can specify a field from any entry in any schema on a particular server. This structure consists of seven elements: Server A string specifying the name of the server where the schema is located. The ARGetListServer function retrieves a list of available servers (see page 6-106). For filters and escalations, specify the server where the filter or escalation is located (either by name or by passing @). For active links, specify * to retrieve the value from the current window. The name of the schema containing the field value to assign. For filters and escalations, specify @ to retrieve or set the value from the current transaction. For active links, specify * to retrieve or set the value from the current window. A qualification that identifies the entries to retrieve or set (optional). Specify the search criteria by using ARQualifierStruct (see Figure 3-10). An integer value indicating the type of field value to retrieve or set. Table 3-20 describes the possible values. The field containing the value to assign or set. Specify the field by using either the field ID or the ARStatHistoryValue structure (see Defining a Status History Value on page 3-19).
Schema
Search Criteria Tag Field
3-40
Set Fields Action
No Match Option Multiple Match Option
An integer value indicating the action to take if no entries match the search criteria. Table 3-21 describes the possible values. An integer value indicating the action to take if multiple entries match the search criteria (Set Fields) or if any entry matches the search criteria (Push Fields). Table 3-22 describes the possible values. Tag Values for ARAssignFieldStruct Value from a regular schema field Value from the Status History core field No Match Options for ARAssignFieldStruct Return an error Assign NULL (Set Fields action only) Do nothing (Push Fields action only) Submit a new entry (Push Fields action only)
Table 3-20
1 4 AR_FIELD AR_STAT_HISTORY
Table 3-21
1 2 3 4
AR_NO_MATCH_ERROR AR_NO_MATCH_SET_NULL AR_NO_MATCH_NO_ACTION AR_NO_MATCH_SUBMIT
Table 3-22
1 2 3 4 5 6
Multiple Match Options for ARAssignFieldStruct Return an error Assign NULL (Set Fields action only) Assign a value from the first matching entry Display a selection list (active links only) Modify all matching entries (Push Fields action only) Do nothing (Push Fields action only)
AR_MULTI_MATCH_ERROR AR_MULTI_MATCH_SET_NULL AR_MULTI_MATCH_USE_FIRST AR_MULTI_MATCH_PICKLIST AR_MULTI_MATCH_MODIFY_ALL AR_MULTI_MATCH_NO_ACTION
Assigning an Arithmetic Result Value

The ARArithOpAssignStruct structure defines an arithmetic result value to assign in a Set Fields action. This structure is very similar to the ARArithOpStruct structure and uses the same set of operation values (see Defining an Arithmetic Result Value on page 3-19). Like ARArithOpStruct,
Data Structures
3-41
ARArithOpAssignStruct consists of a tag identifying the type of arithmetic operation and two operands specifying the values. In this case, however, the operands are represented by using ARAssignStruct instead of ARFieldValueOrArithStruct.
Assigning a Function Return Value

The ARFunctionAssignStruct structure specifies a function return value to assign in a Set Fields action. This structure consists of three elements: Function Type Number of Parameters Parameter List Table 3-23 An integer value indicating the type of function to perform. Table 3-23 describes the possible values. An integer value identifying the number of function input parameters. A pointer to the parameter values to use (represented in an ARAssignStruct structure). Function Type Values for ARFunctionAssignStruct (1 of 2) Input
1 2 3 4 5 6 7 8 9 AR_FUNCTION_DATE AR_FUNCTION_TIME AR_FUNCTION_MONTH AR_FUNCTION_DAY AR_FUNCTION_YEAR AR_FUNCTION_WEEKDAY AR_FUNCTION_HOUR AR_FUNCTION_MINUTE AR_FUNCTION_SECOND timestamp timestamp timestamp timestamp timestamp timestamp timestamp timestamp timestamp real real char char char
Return Value
char char long long long long long long long long long long char char
Date Time Month (1-12) Day (1-31) Year Weekday (1-7) Hour (0-23) Minute (0-59) Second (0-59) Truncated value Rounded value Length of string Uppercase string Lowercase string
10 AR_FUNCTION_TRUNC 11 AR_FUNCTION_ROUND 13 AR_FUNCTION_LENGTH 14 AR_FUNCTION_UPPER 15 AR_FUNCTION_LOWER
3-42
Set Fields Action
Table 3-23
Function Type Values for ARFunctionAssignStruct (2 of 2) Input Return Value

char char char char char
16 AR_FUNCTION_SUBSTR 17 AR_FUNCTION_LEFT 18 AR_FUNCTION_RIGHT 19 AR_FUNCTION_LTRIM 20 AR_FUNCTION_RTRIM 21 AR_FUNCTION_LPAD 22 AR_FUNCTION_RPAD 23 AR_FUNCTION_REPLACE 24 AR_FUNCTION_STRSTR 25 AR_FUNCTION_MIN 26 AR_FUNCTION_MAX
char, long [, long] char, long char, long char char
Substring from long1 to long2 (inclusive) Left-most n bytes Right-most n bytes Leading blanks removed Trailing blanks removed
char1 left-padded with char2 to n bytes char1 right-padded with char2 to n bytes char1 with char2 replaced by char3
char, long, char char char, long, char char char, char, char char char, char int
Position of char2 in char1 (-1 = not found) Minimum value Maximum value
<x>, <x>, <x> [, <x>] ... <x>, <x>, <x> [, <x>] ...
Note:
If necessary, the system automatically converts all input parameters to the correct data type.
Assigning a DDE Result Value

The ARDDEStruct structure defines a DDE result value to assign in a Set Fields action. This option is available for active links on Windows clients only. This structure consists of six elements: Service Name Topic Item A string specifying the service to use. A string specifying the topic to use. A string specifying the item to retrieve.
Data Structures
3-43
Action Path Command
An integer value identifying the type of DDE action. Specify AR_DDE_REQUEST for this item. A string specifying the path to the application. A string specifying the command to execute. Specify NULL for this item.
Assigning an SQL Result Value

The ARAssignSQLStruct structure specifies an SQL result value to assign in a Set Fields action. Use this option to assign a value from any SQL database. This structure consists of five elements: Server A string specifying the name of the server where the database is located. The ARGetListServer function retrieves a list of available servers (see page 6-106). A string specifying the SQL query to execute. An integer value indicating which of the selected columns contains the value to assign. An integer value indicating the action to take if no rows match the selection criteria. Table 3-21 describes the possible values. An integer value indicating the action to take if multiple rows match the selection criteria. Table 3-22 describes the possible values.
SQL Command Value Index No Match Option Multi-Match Option
3-44
Push Fields Action
Push Fields Action

Where the Set Fields action sets the value of a field in the current schema, the Push Fields action modifies or submits entries in any schema. When Push Fields is used in an active link, the schema can be on any server. The ARPushFieldsList structure, shown in Figure 3-23, is a list of ARPushFieldsStruct items. Each item contains an ARAssignFieldStruct structure specifying the field to update and an ARAssignStruct structure specifying the value to push there. These data structures are also used in Set Fields actions and are explained in that section of this manual. Note: You can force a Push Fields action to perform a submit by setting the Qualifier to AR_COND_OP_NONE, the No Match option to AR_NO_MATCH_SUBMIT, and the Multiple Match option to AR_MULTI_MATCH_NO_ACTION.
ARPushFieldsList
Pointer
ARPushFieldsStruct
ARAssignFieldStruct
ARAssignStruct See Figure 3-22
Server
Pointer
Schema
Tag
Qualifier
No Match Opt.
Multi-Match Opt.
}
union
char
ARNameType
unsigned int
ARQualifierStruct See Figure 3-10
Field ID
ARInternalId
unsigned int
unsigned int
Status History
ARStatHistoryValue
Acta as any match for Push Fields actions
Figure 3-23
Structures Used to Define Push Fields Action
Data Structures
3-45
OLE Automation Action

The OLE Automation active link action enables a Windows client to control OLE Automation servers on the same machine, accessing the data and methods that those servers have made available. For more information about how to use the OLE Automation action, see the Action Request System Administrators Guide, Volume 1. The data structure used to define an OLE Automation action is the ARAutomationStruct structure, shown in Figure 3-24.
ARAutomationStruct Server Name
Pointer
Class ID
Pointer
Action
Pointer
Visible
Methods
char
char
char
ARBoolean
ARCOMMethodList
Pointer
ARCOMMethodStruct See Figure 3-25
Figure 3-24
Structures Used to Define OLE Automation Action
This structure consists of five elements: Server Name Class ID Action A string specifying the name of the OLE Automation server, length limited by AR_MAX_COM_NAME (64 bytes) A string specifying the unique ID assigned to this server in the registry, length limited by AR_MAX_COM_ID_SIZE (128 bytes) A string specifying the equation defined by this action, including nested methods and the assignment if any. For example, $Status$ = MethodA().MethodB(MethodC()). It is used for display only, and limited by AR_MAX_AUTOMATION_SIZE (2000 bytes). Not used. Specify 0. A list of the methods called by this active link action, specified by using an ARCOMMethodList structure. The methods must be listed in order of execution. Therefore, if Method B is passed as a parameter to Method A, Method B should be listed first so that its result value will be available when Method A is called.
Visible Methods
3-46
Each method in an ARCOMMethodList structure is specified by using the ARCOMMethodStruct structure, shown in Figure 3-25.
ARCOMMethodStruct Name
Pointer
Interface ID
Pointer
Type
Value
Parameters
char
char
unsigned int
ARCOMValueStruct See Figure 3-26
ARCOMMethodParmList
Pointer
ARCOMMethodParmStruct Name
Pointer
Type
Value
char
unsigned int
ARCOMValueStruct
Figure 3-25
Structures Used to Define OLE Automation Method
This structure consists of five elements: Name Interface ID Type Value The name of the method, length limited by
AR_MAX_COM_METHOD_NAME (128 bytes)
The ID of the interface that owns the method, length limited by AR_MAX_COM_ID_SIZE (128 bytes) The type of value returned by the method, if any. Possible values are all OLE variant types. The AR System field to set to the methods return value, if any. This is specified by using an ARCOMValueStruct structure, shown in Figure 3-26. A list of the parameters passed to this method, specified by using an ARCOMMethodParmList structure.
Parameters
Data Structures
3-47
Each parameter in an ARCOMMethodParmList structure is specified by using the ARCOMMethodParmStruct structure, shown in Figure 3-25, which consists of three elements: Name Type Value The name of the parameter The data type of the parameter. Possible values are all OLE variant types. The value of the parameter, specified by using an ARCOMValueStruct structure
The value returned by a method and the value passed in a parameter are each specified by using the ARCOMValueStruct structure, shown in Figure 3-26.
ARCOMValueStruct Interface ID
Pointer
Transient ID
Value Type
char
ARInternalId
unsigned int
}
union
}
Value ARValueStruct See Figure 3-9
Field ID
ARInternalId
Figure 3-26
Structures Used to Define OLE Method and Parameter Values
3-48
This structure consists of four elements: Interface ID When this ARCOMValueStruct structure is used to define the return value of a method, specify the ID of the interface returned by the method. When used to define the value of a parameter that is an OLE interface, specify the ID of that interface. Otherwise, specify NULL. The Transient ID links a method that takes another method as a parameter to the method that is used as that parameter. For example, Method A takes Method B as a parameter. Use the same integer value here for the ARCOMValueStruct structure that defines the return value for Method B as you do for the structure that defines the parameter value of Method A. An integer specifying the type of value represented by the structure. Table 3-24 and Table 3-25 describe the possible values. For Value Type 0, set the other members of the structure to NULL or 0. A union that defines either the field ID or value, depending on the structures type. For Value Type 1, this is the ID of the field to set to the return value of this method or the field to pass as this parameter, specified by using an ARInternalId structure. For Value Type 2, this is the value to pass as this parameter, specified by using an ARValueStruct structure. Table 3-24
0 1
Transient ID
Value Type
Field ID/Value
Method Return Value Types for ARCOMValueStruct No value returned for this method Set the specified AR System field to the value returned by this method
AR_COM_METHOD_NULL AR_COM_METHOD_FIELDID
Table 3-25
0 1 2
Parameter Value Types for ARCOMValueStruct No value for this parameter Pass the specified AR System field as the parameter Pass the specified value as the parameter
AR_COM_PARM_NULL AR_COM_PARM_FIELDID AR_COM_PARM_VALUE
Data Structures
3-49
Menus
All character menu definitions in the AR System are represented by using the ARCharMenuStruct structure, illustrated in Figure 3-27.
ARCharMenuStruct Menu Type
unsigned int
List
Query
}
union
}
File SQL
ARCharMenuFileStruct ARCharMenuSQLStruct
ARCharMenuList
Pointer
ARCharMenuQueryStruct
ARQualifierStruct
ARCharMenuItemStruct
See Figure 3-10
Label
Type
ARNameType
unsigned int
Value
Pointer
}
union
}
Child Menu
Pointer
char
ARCharMenuStruct
Figure 3-27
Structures Used to Define Character Menus
Most of the character menu functions have a menuDefn parameter that is a pointer to a structure of this type (for example, see ARCreateCharMenu on page 6-10 or ARExpandCharMenu on page 6-63).
3-50
Menus
The ARCharMenuStruct structure defines both the content and organization of the menu and consists of two elements: Menu Type Menu Definition An integer value indicating the type of character menu. Table 3-26 describes the possible values. The specific menu content (represented by using structures appropriate to the type of menu). Table 3-26
0 1 AR_CHAR_MENU_NONE AR_CHAR_MENU_LIST
Menu Type Values for ARCharMenuStruct No character menu Menu items based on definitions in ARCharMenuList (see The ARCharMenuList structure consists of zero or more ARCharMenuItemStruct items. Each ARCharMenuItemStruct represents an individual menu item. In this context, a menu item can be a value (a leaf-level item) or another menu (a top- or intermediate-level item). This structure consists of three elements:) Menu items based on schema query defined in
ARCharMenuQueryStruct
2 3 4
AR_CHAR_MENU_QUERY AR_CHAR_MENU_FILE AR_CHAR_MENU_SQL
Menu items based on formatted flat file defined in ARCharMenuFileStruct Menu items based on SQL query defined in
ARCharMenuSQLStruct
The ARCharMenuList structure consists of zero or more ARCharMenuItemStruct items. Each ARCharMenuItemStruct represents an individual menu item. In this context, a menu item can be a value (a leaf-level
Data Structures
3-51
item) or another menu (a top- or intermediate-level item). This structure consists of three elements: Label Type Menu Definition The label that identifies the menu item. An integer value indicating the type of menu item. Table 3-27 describes the possible values. The value associated with the menu item. For leaf-level items, the definition is a string containing the item text. For top- or intermediate-level items, the definition is a pointer to a child menu (represented by using ARCharMenuStruct). Menu Type Values for ARCharMenuItemStruct No menu item Leaf-level menu item Top- or intermediate-level menu item
Table 3-27
0 1 2
AR_MENU_TYPE_NONE AR_MENU_TYPE_VALUE AR_MENU_TYPE_MENU
Containers
Containers are generic lists of references that are used to define guides and applications. For information about the purpose and use of guides and applications, see the Action Request System Administrators Guide, Volume 1.
Retrieving Container Lists

The first group of structures relate to retrieving a list of containers. You can retrieve entry lists by using the ARGetListContainer function (see page 6-93). The function returns the list of containers that match the specified type, owning object, and modification time stamp.
3-52
Retrieving Container Lists
The ARGetListContainer function uses the ARContainerInfoList structure to specify the containers it returns. The ARContainerInfoList structure consists of zero or more ARContainerInfo structures, shown in Figure 3-29.
ARContainerInfoList Name
Pointer
ARContainerInfo Type Owner Name Owner Type
ARNameType
unsigned int
ARNameType
unsigned int
Figure 3-28
Structures Used to Define Container Lists
This structure consists of four elements: Name Type Owner Name Owner Type An ARNameType structure that specifies the name of the container An integer value indicating the type of container. Table 3-28 describes the possible values. An ARNameType structure that specifies the name of the object that owns the container, if any An integer value indicating the type of owning object. Table 3-29 describes the possible values. Table 3-28
1 2 ARCON_GUIDE ARCON_APP
Container Type Values for ARContainerInfo Guide Application Owner Type Values for ARContainerInfo The container is globally owned The owner object is a schema
Table 3-29
0 2 ARCONOWNER_NONE ARCONOWNER_SCHEMA
Data Structures
3-53
Manipulating Individual Containers

The ARGetListContainer function (see page 6-93) returns a list of containers that match specified criteria. This list contains the names of the matching containers but does not contain their reference lists and other attributes. To retrieve or modify individual containers, you must pass the name as an input argument to the ARGetContainer or ARSetContainer functions (see pages 6-71 and 6-153). Both of these functions, as well as the ARCreateContainer (see page 6-12) functions, use the ARReferenceList structure to specify the objects referenced by a container. Guides reference active links and applications reference schemas and other objects, both internal and external. The ARReferenceList structure consists of zero or more ARReferenceStruct structures, shown in Figure 3-29.
ARReferenceList Label
Pointer Pointer
ARReferenceStruct Type Reference
Description
Pointer
char
char
unsigned int
ARReferenceUnion
Data Type
unsigned int Name
ARNameType
}
union Permitted Groups ARInternalIdList
}
External Reference ARExtReferenceStruct Value ARValueStruct
Figure 3-29
Structures Used to Define Container References
3-54
Manipulating Individual Containers
This structure consists of four elements: Label Description A string specifying a display-only label for the reference. Its length is limited by ARMAX_CON_LABEL_LEN (255 bytes). A string specifying a display-only description for the reference. Its length is limited by ARMAX_CON_DESCRIPTION_LEN (2000 bytes). An integer specifying the type of reference represented by the structure. Table 3-30 describes the possible values. Values above 32767 define external reference types. A union that defines either an internal or external reference depending on its Data Type, which is either 0 (ARREF_DATA_ARSREF) or 1 (ARREF_DATA_EXTREF). Internal references (0) are specified by using an ARInternalId structure. External references (1) are specified by using an ARExtReferenceStruct structure, shown in Figure 3-29. Table 3-30
0 1 2 3 4 5 6 ARREF_NONE ARREF_ALL ARREF_SCHEMA ARREF_FILTER ARREF_ESCALATION ARREF_ACTLINK ARREF_CONTAINER
Type
Reference
Type Values for ARReferenceStruct (1 of 2) No reference All reference types Reference to a schema Reference to a filter Reference to an escalation Reference to an active link Reference to a container Reference to an icon Reference to a small icon Reference to a boolean value that specifies whether to maximize the forms of an application Specifies that the next reference in the list is a schema. Use this reference in front of each schema reference in your application except the primary schema.
32768 ARREF_ICON 32769 ARREF_SMALL_ICON 32770 ARREF_MAXIMIZE_FORMS
32771 ARREF_APPLICATION_FORMS
Data Structures
3-55
Table 3-30
Type Values for ARReferenceStruct (2 of 2) Reference to an About box image Reference to a null string help filename extension
32772 ARREF_ABOUT_BOX_IMAGE 32774 ARREF_NULL_STRING
32775 ARREF_APPLICATION_HELP_EXT Reference to a string that specifies the 32776 ARREF_APPLICATION_HELP_ FILE
Reference to a bytelist that specifies the contents (not the name) of the help file to use with this application
32777 ARREF_APPLICATION_PRIMARY_ Specifies that the next reference in the FORM list is the primary schema for this
application. Use this reference in front of only one schema reference in your application.
32778 ARREF_APPLICATION_FORM_VUI Reference to the ID of the schema view to
use with the previous schema referenced in the list. Use this reference after each schema reference in your application.
32779 ARREF_APPLICATION_DISABLE_ Reference to a boolean value that BEGIN_TASK specifies whether the Begin a Task menu
item is disabled for this application. The default is false (not disabled). The ARExtReferenceStruct structure, shown in Figure 3-29, defines external references. This structure consists of two elements: Permitted Groups Value An ARInternalIdList specifying the groups that have access to the referenced object An ARValueStruct specifying the external reference
3-56
Importing and Exporting
Importing and Exporting

Both the ARExport and ARImport functions (see pages 6-64 and 6-141) use the ARStructItemList structure to represent the AR System objects to export or import. As illustrated in Figure 3-30, this list contains zero or more ARStructItemStruct items.
ARStructItemList
Pointer
ARStructItemStruct
Type
Name
unsigned int
ARNameType
Figure 3-30
Structures Used to Import and Export AR System Objects
Each ARStructItemStruct represents a particular object to export or import: Item Type Item Name An integer value indicating the type of AR System object. Table 3-31 describes the possible values. The name associated with the AR System object. Object Type Values for ARStructItemStruct (1 of 2) Schema definition, including views, help text, and change diary information Remedy User cache (special purpose export)
3 AR_STRUCT_ITEM_SCHEMA_VIEW Display definition for configuring
Table 3-31
1 2
AR_STRUCT_ITEM_SCHEMA
AR_STRUCT_ITEM_SCHEMA_DEFN Structure definition for configuring
Remedy User cache (special purpose export)

4 5 6 8 AR_STRUCT_ITEM_SCHEMA_MAIL Email template for submitting requests
(special purpose export)

AR_STRUCT_ITEM_FILTER
Filter definition Character menu definition
AR_STRUCT_ITEM_ACTIVE_LINK Active link definition AR_STRUCT_ITEM_CHAR_MENU
Data Structures
3-57
Table 3-31
9
Object Type Values for ARStructItemStruct (2 of 2) Escalation definition Mapping definition for Distributed Server Option Container definition
AR_STRUCT_ITEM_ESCALATION
10 AR_STRUCT_ITEM_DIST_MAP 12 AR_STRUCT_ITEM_CONTAINER
Note:
To import all structures in the import buffer, specify NULL for the structItems parameter or an ARStructItemList with zero items.
Freeing Allocated Memory

Many of the AR System data structures use allocated memory. In the case of input parameters, allocate the necessary space by using the malloc function. Memory for output parameters is allocated dynamically by the system based on their content. You (the caller of the API function) are the only one who knows whether you allocated space for input parameters, and when you are finished with output parameters, you are responsible for freeing all allocated memory. To avoid a buildup of allocated space, free memory as soon as you no longer need it. To ease the process of freeing memory, the API includes a series of FreeAR and FreeNT functions, each of which is specialized to free all allocated memory associated with a particular data structure. These functions assume that all structure components are in allocated memory and should not be used if any components of a structure are on the stack. In this case, you must free the memory manually by using the free function. All of the Free functions accept two input arguments. The value parameter is a pointer to the structure you want to free. The function recursively frees all allocated memory within that structure. If you specify NULL for this parameter (or the structure is a list with zero items), the function performs no operations. The freeStruct parameter is a Boolean that indicates whether you need to free the top-level structure. If you allocated memory for the top-level structure, specify TRUE to free both the structure and its contents. If you used a stack variable for the top-level structure, specify FALSE to free only the
3-58
Freeing Allocated Memory
contents of the structure. Figure 3-31 provides an example that illustrates this difference.
main() { ARStatusList int
*status; rtn;
main() { ARStatusList int
status; rtn;
status = malloc(sizeof(ARStatusList)); rtn = ARGetEntry(..., status); ... ... FreeARStatusList(status, TRUE); }
rtn = ARGetEntry(..., &status); ... ... FreeARStatusList(&status, FALSE); }
status status numItems statusList
numItems statusList
2
[0]
messageText messageType appendedText messageNum
[0]
messageText appendedText messageType
[1]
messageNum
[1]
messageText
Stack
appendedText
Heap
Figure 3-31
Specifying TRUE or FALSE for freeStruct Parameter
Data Structures
3-59
Note:
Depending on your compiler, you may need to explicitly discard unused return values by casting them to void when calling the FreeAR and FreeNT functions.
When an API function fails (that is, status greater than one), the system initializes all output parameters other than ARStatusList or NTStatusList. As a result, the only Free function you must call is FreeARStatusList (or FreeNTStatusList). Calling FreeAR<data structure> or FreeNT<data structure> for the other parameters is not necessary in this situation but causes no harm. Note: For additional information about the FreeAR<data structure> and FreeNT<data structure> functions, see the arfree.h and ntfree.h header files or pages 6-187 and 6-194, respectively.
3-60
Chapter 4 Creating and Executing API Programs
This chapter explains how to perform system initialization, shutdown, and other tasks common to most AR System API programs.
Program Structure
As illustrated in Figure 4-1, all AR System API programs follow the same basic outline:
s s s s
Perform generic system startup and initialization Perform program-specific work Free memory associated with performing that work Perform generic system shutdown and cleanup
ARInitialization and NTInitializationServer Startup
AR System and Remedy Notifier function calls
... ... ...
Perform system work
FreeAR and FreeNT function calls
Free allocated memory
ARTermination and NTTerminationServer
Cleanup
Figure 4-1
Generic API Program Structure
Creating and Executing API Programs
4-1
Startup
Call ARInitialization or NTInitializationServer to perform server- and network-specific initialization operations for connecting to the AR and Remedy Notifier servers (required).
Perform System Work Free Allocated Memory
Call one or more API functions to perform the specific work of your program. Call one or more of the FreeAR or FreeNT functions (or use the free function) to free all allocated memory associated with a specific data structure (see Freeing Allocated Memory on page 3-58). Call ARTermination or NTTerminationServer to perform environment-specific cleanup routines and disconnect from the AR and Remedy Notifier servers (required). If you are using floating licenses and do not disconnect from the server, your license token is unavailable for other users for the defined time-out interval.
Cleanup
The code fragment in Figure 4-2 gives you an example of the generic program structure. Because almost every AR System API function has a control parameter as its first input argument, the template includes code for loading the ARControlStruct structure (see Login and Session Information on page 3-6).
4-2
Program Structure
{ ARControlStruct ARStatusList int ... ...
control; status; rtn;
/****************************************************************/ /* Remedy Startup */ /****************************************************************/ if (ARInitialization(&control, &status) >= AR_RETURN_ERROR){ printf("\n **** initialization error ****\n"); PrintARStatusList(&status); exit(3); } FreeARStatusList(&status, FALSE); /****************************************************************/ /* Load ARControlStruct */ /****************************************************************/ strcpy(control.user, "Demo"); /* use Demo user */ strcpy(control.password, ""); /* could load from file */ strcpy(control.language, ""); /* use default language */ strncpy(control.server, argv[1], AR_MAX_SERVER_SIZE); control.server[AR_MAX_SERVER_SIZE] = \0; /****************************************************************/ /* Perform System Work */ /****************************************************************/ rtn = ARGetEntry(&control, ..., &status); if( rtn ... ) ... ... /****************************************************************/ /* Remedy Cleanup */ /****************************************************************/ (void) ARTermination(&control, &status); FreeARStatusList(&status, FALSE); }
Figure 4-2
Example of Generic Program Structure
4-3
Performing Common Tasks

Each object in the AR System has an ARGetList<object> function that returns a list of records that match the specified criteria. Depending on the object, this list contains zero or more names or IDs (or both) that uniquely identify the record. The unique identifier for each AR System object is shown in Table 4-1. Table 4-1 AR System Object Active link Character menu Container Entry Escalation Field Filter Group Schema Server User View (VUI) Return Values for ARGetList<object> Functions Return Parameter
nameList nameList conList entryList nameList idList nameList groupList nameList serverList userList idList
Parameter Type
ARNameList * ARNameList * ARContainerInfoList * AREntryListList * ARNameList * ARInternalIdList * ARNameList * ARGroupInfoList * ARNameList * ARServerNameList * ARUserInfoList * ARInternalIdList *
Unique Identifier Name Name Name ID Name ID Name ID Name Name Name ID
These names or IDs can then be passed as input arguments to the ARGet<object>, ARSet<object>, or ARDelete<object> functions to perform the corresponding operation on those records. Unqualified ARGetList<object> calls generate a complete list of records (for a particular object). You can select a subset of these records by using a qualification. When retrieving a list of entries, you can specify any set of selection conditions by using ARQualifierStruct (see Representing
4-4
Example 1Retrieving Field Properties
Qualifications on page 3-15). For other objects, you can retrieve lists limited to records modified after a specified date and time value. For fields, views, filters, escalations, and active links, you can also limit it to items associated with a specified schema. The following examples use common tasks to illustrate these concepts. Each of the first two examples include a brief task description, an outline of the conceptual steps involved, and a diagram of the API functions and parameters used to accomplish the task. These examples also demonstrate the general problem-solving approach of breaking tasks into conceptual steps. This approach may help you identify the sequence of API functions needed to solve your programming problem. The third example consists of a small sample program that retrieves and prints a list of available AR System servers.
Example 1Retrieving Field Properties

The goal in this example is to retrieve selected properties for a particular schema field. In this case, the field is a data or control field, and the properties shown are the field name, data type, access control information, and display properties. The following high-level steps are illustrated in Figure 4-3.
To retrieve selected properties for a field: 1. Retrieve a list of available schemas (ARGetListSchema), and select the desired schema name (schema) from the list (nameList). 2. Retrieve a list of data, trim, and control fields (fieldType) associated with the schema (ARGetListField). 3. Select the desired field (fieldId) from the list (idList), and retrieve the specified properties for that field (ARGetField).
4-5
ARGetListSchema
field type
AR_FIELD_TYPE_DATA | AR_FIELD_TYPE_CONTROL
Function Parameter
nameList
schema
ARGetListField
fieldName
idList
fieldId
dataType
ARGetField
permissions
dInstanceList
Figure 4-3
Functions Used to Retrieve Field Properties
Example 2Retrieving Selected Entries

The goal in this example is to retrieve the set of schema entries that match specified query conditions. The selection criteria are those entries that are either New or Open and were created more than two weeks ago. The following high-level steps are illustrated in Figure 4-4.
To retrieve selected entries from a schema: 1. Retrieve a list of available schemas (ARGetListSchema), and select the desired schema name (schema) from the list (nameList). 2. Create a string with the desired query conditions (qualString), and place it into the proper structure (ARLoadARQualifierStruct). 3. Retrieve a list of entries (ARGetListEntry) from the schema that match the query conditions (qualifier). 4. If desired, select a particular entry (entryId) from the list (entryList), and retrieve the field data (fieldList) for that entry (ARGetEntry).
4-6
Example 3Retrieving a Server List
ARGetListSchema
qualstring "Status < 2 AND Create-date < ($DATE$-(60*60*24*14))" Function Parameter
nameList
schema
ARLoadARQualifierStruct
qualifier
ARGetListEntry
entryList
entryId
ARGetEntry
fieldList
Figure 4-4
Functions Used to Retrieve Qualified Entries
Example 3Retrieving a Server List

/* ** ** ** File: GetListServer.c Description: Prints list of availble servers from /etc/ar (UNIX) or the registry (NT) Usage: GetListServer */ <stdlib.h> <stdio.h> "ar.h" "arerrno.h" "arextern.h"
#include #include #include #include #include
void printStatusList(ARStatusList theList); int main(void) { ARServerNameList serverList; ARStatusList status; int i; ARControlStruct control; if(ARInitialization(&control, &status) > AR_RETURN_OK) printStatusList(status); FreeARStatusList(&status, FALSE);
4-7
if(!(ARGetListServer(&control, &serverList, &status) > AR_RETURN_OK)) for(i = 0; i < serverList.numItems; i++) printf("%s\n", serverList.nameList[i]); else printStatusList(status); FreeARStatusList(&status, FALSE); FreeARServerNameList(&serverList, FALSE); if(ARTermination(&control, &status) > AR_RETURN_OK) printStatusList(status); FreeARStatusList(&status, FALSE); return 0; } void printStatusList(ARStatusList theList) { int i; for(i = 0; i < theList.numItems; i++) printf("%s: %s (ARERR %d)\n", theList.statusList[i].messageText, theList.statusList[i].appendedText, theList.statusList[i].messageNum); }
Specifying Fields or Keywords

The AR System and Remedy Notifier include several actions that involve text:
s s s s
Sending a notification (filters and escalations) Sending a message (filters and active links) Running a process (filters, escalations, and active links) Specifying a macro parameter (active links)
Because Remedy User and Remedy Administrator run in a localized environment, you can include a field or keyword value in a character string by specifying the name of the desired field or keyword. An API program, however, can operate in multiple environments. Because field names and keywords vary across environments, you must specify the
4-8
Error Checking
field ID or keyword code (which are environment-independent) to include one of these values in a character string. The syntax for specifying a field or keyword value is shown in Table 4-2. Table 4-2 Field Keyword
$id$ $-code$
Syntax for Specifying Fields and Keywords ID of the desired field (for example, $7$). Code associated with the desired keyword in ar.h (for example, $-5$ for the current schema). Use $--1$ to specify NULL. A hyphen is required to distinguish a keyword code from a field ID.
Note:
Field IDs and keyword codes are not required when specifying a qualification string for the ARLoadARQualifierStruct function because it automatically translates all values for you (see page 6-119).
Error Checking
All the API functions (except FreeAR and FreeNT) return a status parameter (ARStatusList/NTStatusList) that consists of zero or more notes, warnings, or errors generated from the function call (see Status Information on page 3-8). Each message consists of a value indicating the type of message, the message number, and the message text (in the language specified in the control structure). More serious errors are listed first with lesser warnings and informational messages following. Within each category, messages are listed in reverse chronological order, with the most recent message first.
4-9
The return of the function itself is an integer value indicating the success or failure of the call (see Table 4-3). This value represents the status associated with the first (most recent and most serious) message in the list. Table 4-3 0 AR_RETURN_OK
NT_RETURN_OK
Status Return Values
Operation successfulstatus may contain one or more informational messages. Operation successful, but a problem was encounteredstatus contains one or more warning messages and may also contain informational messages. Operation failedstatus contains one or more error messages and may also contain warning or informational messages. Operation failedstatus may contain one or more messages. Invalid status parameteroperation canceled.
1 AR_RETURN_WARNING
NT_RETURN_WARNING
2 AR_RETURN_ERROR
NT_RETURN_ERROR
3 AR_RETURN_FATAL
NT_RETURN_FATAL
4 AR_RETURN_BAD_STATUS
NT_RETURN_BAD_STATUS
You can ignore warnings and informational messages, although reporting warnings is often helpful. Because the API returns all errors in a common structure, you can perform all error handling by using a single, generic routine. Figure 4-5 provides a sample routine for checking return values.
4-10
Error Checking
ARStatusList char int
status; apicall[ar_MAX_APICALL_SIZE]; /* function name */ rtn; /* function return value*/
rtn = ARGetEntry(&control, ..., &status); strcpy(apicall,"ARGetEntry"); switch( rtn ){ case AR_RETURN_OK: printf("\t%s: Successful\n", apicall); PrintARStatusList( &status ); break; case AR_RETURN_WARNING: printf("\t%s: Warning\n", apicall); PrintARStatusList( &status ); break; case AR_RETURN_ERROR: printf("\t%s: Error\n", apicall); PrintARStatusList( &status ); exit(3); break; case AR_RETURN_FATAL: printf("\t%s: Fatal\n", apicall); exit(3); break; case AR_RETURN_BAD_STATUS: printf("\t%s: Bad Status\n", apicall); exit(3); break; default: printf("\t%s: Invalid return value: %d\n", apicall, rtn); exit(3); }
Figure 4-5
Sample Routine for Checking Return Values
Because the status structure uses allocated memory, you must free that memory after every API call by using FreeARStatusList or FreeNTStatusList. You can call these functions regardless of whether the status structure contains any messages, because they perform no action if there are no messages to free (for more information, see Freeing Allocated Memory on page 3-58).
4-11
Executing API Programs in Workflow

The most obvious way to execute an API program is from the command line. You can execute an API program directly, integrate it with other processes or commands in a shell script, or schedule it for regular execution by using a UNIX cron job or the Windows NT Scheduler. The second way to execute an API program is through workflow. You can call an API program in a filter, escalation, or active link to perform the Set Fields, Push Fields, or Run Process actions.
Set Fields and Push Fields

The Set Fields and Push Fields actions assign a specified value to a particular schema field. You can assign a constant, a value from another field, or an operation result value (see Set Fields Action on page 3-38 or Push Fields Action on page 3-45). To assign the result of an operating system process or command (including an API program), specify the following field value:
$PROCESS$ <API program> <parameter(s)>
The Set Fields and Push Fields operations block the AR System server (the server waits for the operation to complete before performing any other actions). If the Set Fields or Push Fields action calls an API program that executes on the same AR System server, an impasse occurs, because the server cannot execute the API program until it completes the operation but the server cannot complete the operation until it executes the API program. This impasse causes a time-out, and the Set Fields or Push Fields operation fails. To avoid this problem, run your API program against a different AR System server. If you have a Multi-Processing Server license, you can also use a separate instance of the AR System server process to execute your API program. Note: The default process time-out interval is five seconds. You can adjust this setting by using the Server Information option in Remedy Administrator. Valid values are from 1 to 20 seconds.
4-12
Executing API Programs in Workflow
Run Process
The Run Process action executes the specified operating system process or command. To execute an API program, specify the following as the command value:
<API program> <parameter(s)>
Unlike a Set Fields operation, the Run Process action does not block the AR System server. The system places these tasks in the Run Process queue, where they are deferred until the server has completed all database transactions. If the specified process requires a field value (for example, sending a pager message to the user to whom a particular ticket has been assigned), the server may use different values depending on the type of database operation and whether it was successful. Table 4-4 summarizes the possible scenarios. Table 4-4 Database Transaction Succeeds Fails Run Process Actions Requiring Field Values Submit Uses new database value Action not performed Modify Uses new database value Uses old database value
If the specified process does not require a field value (for example, sending a pager message to a particular user), the server does not execute the queued processes after an unsuccessful database transaction.
4-13
Program Design Tips

s
Use industry-standard tools. Use a C or C++ compiler adhering to the ANSI standard. If you are using the API under Windows NT, you must use Microsoft Visual C++ (version 5.0 or later). Use POSIX routines for system calls if the program will run on both UNIX and Windows NT, Windows 95, or Windows 98.
Use variables (instead of hardcoding) for more flexibility and less maintenance. Use symbolic constants (#define values from ar.h or nt.h). Use environment variables. Use files to store menu or selection values instead of writing them into your program.
Minimize network traffic. Use bulk transfer to retrieve data and to cache the information locally. Omit unnecessary fields when retrieving data.
4-14
Chapter 5 Debugging and Maintenance
This chapter explains how to solve problems with your API program by using logging and the driver program.
Logging AR System Activity

Log files are a useful debugging tool when your API program does not produce the expected results. Turning on API logging causes the server to record all API calls it receives in the log file you specify. Each entry in the log file identifies the function name, key parameter values, and the return value. Similarly, turning on filter logging causes the system to record all filter actions in a specified log file. Note: Choosing File Server Information in Remedy Administrator enables you to turn logging on and off. To avoid log file overflow, turn logging off when you have finished your debugging activities. For additional information about log files, see the Action Request System 4.0 Administrators Guide, Volume 1.
The system automatically renames your log files to <logfile>.bak each time you start a new trace. For example, the file arapi.log is renamed arapi.log.bak. The system also renames your log files if the AR System server fails while logging is turned on.
Debugging and Maintenance
5-1
Each log file entry begins with one of the tags shown in Table 5-1. The tag identifies the action associated with the entry and helps you determine the sequence of events when a log file contains output from multiple traces. Table 5-1 Tag
<API> <ESCL> <FLTR> <SQL> <USER> <CACHE>
Log File Tags Source Action
API function call Escalation Filter SQL command Login and logout Shared cache change
Logging the actions of your API program can help you determine why your program is not performing the operation you expect. In some cases, you may discover that a filter or escalation is interfering with your program, thereby causing unexpected results.
Using the Driver Program

Installing the API package creates a series of directories in the AR System installation directory. In UNIX environments, the src directory contains two subdirectories with source code for the daysOpen and driver sample programs. In Windows NT environments, the API includes source code for the driver program only (see Installing the API Files on page 2-2). The driver program provides a command line interface for calling every API function. It also includes print routines for every data structure in the API, making it a useful debugging tool. Note: The driver program is provided as sample source code only and is not a supported AR System utility.
5-2
Using print.c Routines
After compiling the source code, you can use driver for a number of purposes:
s s s
To identify function input parameters and how to load them To examine the content and structure of function output parameters To experiment with different parameter values
Using print.c Routines

One of the most helpful components of the driver program is the set of print routines located in the print.c file. These routines enable you to print the contents of any data structure in the API. The routines themselves provide code examples for accessing the various structure members. In addition, printing the contents of a structure before and after an API call is a useful debugging tool. Note: Refer to the function definitions in print.c to determine the specific parameters (and their types) for these routines.
The following example illustrates the use of these routines. Figure 5-1 shows a code fragment that calls three print.c functions. Executing the command print_entry fred EX000003 (where the server name is fred and the entry ID is EX000003) produces the output shown in Figure 5-2.
main() { ... PrintARFieldValueList(&fieldList); PrintReal("header", &value); PrintAREntryIdList("header", "header2", &value); ... }
Figure 5-1
Sample Code Using print.c Functions
5-3
numItems = 9 ID = FIELD VALUE ---------------------------1 = (char) EX000003 2 = (char) snoopy 3 = (timestamp) 11/22/94 4 = (char) snoopy 5 = (char) Demo 6 = (timestamp) 11/23/94 7 = (selection) 2 8 = (char) TESTING 15 (S.H.) 5 stat hist items 0 - 1/18/95 Demo 1 - 1/19/95 Demo 2 3 4 - 1/26/95 Demo
Figure 5-2
Sample print.c Output
The print.h file contains a complete list of these routines. Some of the more commonly used routines are as follows:
s s s s s s s s s s s s s
PrintAREntryIdList PrintAREntryListFieldList PrintAREntryListFieldStruct PrintAREntryListList PrintAREntryListStruct PrintARFieldValueList PrintARInternalIdList PrintARNameList PrintARPermissionList PrintARQualifierStruct PrintARStatusHistoryList PrintARStatusList PrintARStatusStruct
Using driver from the Command Line

After compiling the source code, you are ready to use the driver program. When you execute the program, the system displays the list of driver commands, shown in Table 5-2.
5-4
Table 5-2 Container

get set create delete getlist (gco) (sco) (cco) (dco) (glco)
Commands for Using the driver Program (1 of 2) Schema (Form) Menu

create delete get get list set expand (cc) (dc) (gc) (glc) (sc) (ec) create delete get get list set del multi
Field
(csf) (dsf) (gsf) (glsf) (ssf) (dmsf)
get set create delete get list
(gs) (ss) (cs) (ds) (gls)
Active Link
create delete get get list set (cal) (dal) (gal) (glal) (sal) create delete get
Filter
(cf) (df) (gf) (glf) (sf)
Escalation
create delete get get list set (ces) (des) (ges) (gles) (ses)
Info
get svr set svr get FT set FT get stat (gsi) (ssi) (gft) (sft) (gss)
get list set
Entry
create delete get get list set merge get multi stats (ce) (de) (ge) (gle) (se) (me) (gme) (stat)
Initialization and Termination

init term help exit login (init) (term) (h, ?) (e, q) (log)
Control and Logging

record stop rec open out close out execute (rec) (srec) (oout) (cout) (ex)
Miscellaneous
ver user export import load qual exec proc set port get file set file getBLOB (ver) (exp) (imp) (lqs) (proc) (ssp) (gfl) (sfl) (geb)
getlistw/f (glewf)
get errmsg (gem)
5-5
Table 5-2 VUI

get set create delete getlist (gv) (sv) (cv) (dv) (glsv)
Commands for Using the driver Program (2 of 2) Thread

launch launch waiting release waiting sleep timer (lt) (lwt) (rwt) (st)
Miscellaneous Lists
server group user SQL (svr) (glg) (glu) (glsql)
As in all API programs, you must provide the necessary login information and perform initialization operations for connecting to the AR System server. You can then call any number of API functions by using the commands in Table 5-2. When you are finished, you must terminate your interaction with the AR System server and exit the driver program. Figure 5-3 illustrates these high-level steps by using sample driver commands.
5-6
Command: log Command: init Startup
... ... ... ... ... ...

Figure 5-3
Command: gle
Command: ge
Perform system work
Command: h
Command: term Command: q Cleanup
High-Level Steps for Using the driver Program
Note:
Use the help command (h or ?) to display the driver commands.
Unlike calling the API functions directly, the driver interface prompts you for each input parameter. You can also specify driver login information in other ways:
s
By using the following command line options:

-u -p -l -s
user password language server
For example:
driver -u Demo -p "fun4me" -s fred
s
By using the log command before or after using the init command
5-7
Creating and Using driver Scripts
To create a driver script, perform the following steps: 1. Start the driver program. 2. Enter rec, and provide <script file> when prompted. 3. Enter log, and provide login information when prompted. 4. Enter init (initialize AR System connection). 5. Enter the desired driver commands. 6. Enter term (terminate AR System connection). 7. Enter srec (stop recording). Because driver scripts are stored as text files, you can edit them by using a text editor (which is sometimes easier than rerecording). Blank lines indicate default or skipped values and should not be deleted. You have three options for executing a driver script: Interactive
s s
Start the driver program. Enter ex, and provide <script file> when prompted. Enter driver < script.filename. The driver program will terminate at the end of the script.
Command Line
Command Line or Shortcut
Enter driver -x script.filename. The driver program will remain running at the end of the script unless the script terminates it. To create a shortcut or application icon that will execute your script from a double-click, use this syntax for the shortcuts Target or Command property. It also works directly from the command line.
5-8
Chapter 6 Functions
The Action Request System (AR System) API functions are used to perform operations on all AR System and Remedy Notifier objects and are defined in arextern.h and ntsextrn.h, respectively. The associated routines for freeing allocated memory are defined in arfree.h and ntfree.h (see Freeing Allocated Memory on page 3-58). Warning: The only function definitions that are supported public interfaces are those documented in this manual. Additional functions in arextern.h or ntsextrn.h are not currently supported.
Object Manipulation Functions

You can perform five primary operations for each of the following objects: Active links Containers Entries Escalations Fields Filters Menus Schemas Support files Views
Functions
6-1
These primary operations are create, delete, get (retrieve), get list (retrieve a list), and set (modify). For example, you can retrieve field properties or create entries for a specified schema. Users with administrator capability can create or delete schemas or other objects on a specified server. Some server objects can also be manipulated in other ways by additional functions. Specifically, these are the AR System functions associated with each object.
Active Link
s s s s s
ARCreateActiveLink ARDeleteActiveLink ARGetActiveLink ARGetListActiveLink ARSetActiveLink
Container
s s s s s
ARCreateContainer ARDeleteContainer ARGetContainer ARGetListContainer ARSetContainer
Entry
s s s s s s s s
ARCreateEntry ARDeleteEntry ARGetEntry ARGetEntryBLOB ARGetEntryStatistics ARGetListEntry ARGetListEntryWithFields ARGetMultipleEntries
6-2
Escalation
s s
ARMergeEntry ARSetEntry
Escalation
s s s s s
ARCreateEscalation ARDeleteEscalation ARGetEscalation ARGetListEscalation ARSetEscalation
Field
s s s s s s
ARCreateField ARDeleteField ARGetField ARGetListField ARSetField ARDeleteMultipleFields
Filter
s s s s s
ARCreateFilter ARDeleteFilter ARGetFilter ARGetListFilter ARSetFilter
Functions
6-3
Character Menu
s s s s s s
ARCreateCharMenu ARDeleteCharMenu ARGetCharMenu ARGetListCharMenu ARSetCharMenu ARExpandCharMenu
Schema
s s s s s
ARCreateSchema ARDeleteSchema ARGetSchema ARGetListSchema ARSetSchema
Support File
s s s s s
ARCreateSupportFile ARDeleteSupportFile ARGetListSupportFile ARGetSupportFile ARSetSupportFile
View
s s s s s
ARCreateVUI ARDeleteVUI ARGetListVUI ARGetVUI ARSetVUI
6-4
Other Functions
Other Functions
The API also includes functions for a variety of other operations, such as initializing and terminating interaction with the AR System, verifying users, using complex data structures, or importing and exporting object definitions. These functions are shown in Table 6-1. Table 6-1 Access Control
ARGetListGroup ARGetListUser ARVerifyUser
Other AR System Functions Housekeeping

ARInitialization ARTermination FreeAR<data structure>
Data Structure Help

ARDecodeDiary ARDecodeStatusHistory ARLoadARQualifierStruct
Object Definitions
ARExport ARImport
Server
ARGetListServer ARGetServerInfo ARGetServerStatistics ARSetServerInfo ARSetServerPort
Other
ARExecuteProcess ARGetFullTextInfo ARSetFullTextInfo ARGetListSQL
ARGetTextForErrorMes sage
Table 6-2 identifies the Remedy Notifier functions. All of these functions relate to sending and receiving notifications.
Table 6-2 Housekeeping

NTInitializationServer NTTerminationServer FreeNT<data structure>
Remedy Notifier Functions Notification Other

NTGetListServer
NTDeregisterServer NTNotificationServer NTRegisterServer
Functions
6-5
ARCreateActiveLink
Description ARCreateActiveLink creates a new active link with the indicated name on the specified server. The active link is added to the server immediately and returned to users who request information about active links. Because active links operate on clients, individual clients do not receive the new definition until they reconnect to the schema (thus reloading the schema from the server).
Privileges
This operation can be performed by users with AR System administrator privileges only.
#include #include #include #include "ar.h" "arerrno.h" "arextern.h" "arstruct.h"
Synopsis
int ARCreateActiveLink( ARControlStruct ARNameType unsigned int ARNameType ARInternalIdList unsigned int ARInternalId ARInternalId unsigned int ARQualifierStruct ARActiveLinkActionList ARActiveLinkActionList char ARNameType char ARStatusList Input Arguments control *control, name, order, schema, *groupList, executeMask, *controlField, *focusField, enable, *query, *actionList, *elseList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the active link to create. The names of all active links on a given server must be unique.
name
6-6
ARCreateActiveLink
order
A value between 0 and 1000 (inclusive) that determines the active link execution order. When multiple active links are associated with a schema, the value associated with each active link determines the order in which they are processed (from lowest to highest). The name of the schema the active link is linked to. The active link must be associated with a single schema that currently exists on the server. A list of zero or more groups who can access this active link. Users can execute an active link if they belong to a group that has access to it. Specifying an empty group list defines an active link accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. A bitmask indicating the schema operations that trigger the active link.
Bit 0:
schema groupList
executeMask
Bit 1:
Bit 2: Bit 3:
Bit 4:
Bit 7:
Bit 9:
Bit 10:
Bit 11:
Bit 12:
Execute the active link when a user selects a button, toolbar button, or menu item specified by the controlField parameter (AR_EXECUTE_ON_BUTTON). Execute the active link when a user presses Return in field specified by the focusField parameter (AR_EXECUTE_ON_RETURN). Execute the active link when a user submits an entry (before data is sent to the AR System server) (AR_EXECUTE_ON_SUBMIT). Execute the active link when a user modifies an individual entry (before data is sent to the AR System server) (AR_EXECUTE_ON_MODIFY). Execute the active link when a user displays an entry (after data is retrieved from the AR System server) (AR_EXECUTE_ON_DISPLAY). Execute the active link when a user selects an item from a character menu associated with a field specified by the focusField parameter or selects a row in a table field specified by the focusField parameter (AR_EXECUTE_ON_MENU_CHOICE). Execute the active link when a user sets default values (either manually or through preference settings) (AR_EXECUTE_ON_SET_DEFAULT). Execute the active link when a user retrieves one or more entries (before the query is sent to the AR System server) (AR_EXECUTE_ON_QUERY). Execute the active link when a user modifies an individual entry (after data is committed to the database) (AR_EXECUTE_ON_AFTER_MODIFY). Execute the active link when a user submits an entry (after data is committed to the database) (AR_EXECUTE_ON_AFTER_SUBMIT).
Functions
6-7
Bit 14:
Bit 15:
Execute the active link when a user opens any schema window or changes its mode (AR_EXECUTE_ON_WINDOW_OPEN). Execute the active link when a user closes any schema window or changes its mode (AR_EXECUTE_ON_WINDOW_CLOSE).
controlField The ID of the field that represents the button, toolbar button, or menu item
associated with executing the active link. This parameter is ignored if you do not specify the AR_EXECUTE_ON_BUTTON condition (see the executeMask parameter).
focusField
The ID of the field associated with executing the active link by pressing Return, selecting a character menu item, or gaining or losing focus. You must create another active link to specify a different field for each condition. This parameter is ignored if you do not specify either the AR_EXECUTE_ON_RETURN or AR_EXECUTE_ON_MENU_CHOICE conditions (see the executeMask parameter). A flag to enable or disable this active link. A value of 0 disables the active link, causing it to be invisible to the user and unavailable for use. A value of 1 enables the active link, causing it to be visible and available for use. A qualification that determines whether the active link is executed. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to execute the active link unconditionally. The set of actions performed if the condition defined by the query parameter is satisfied. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). The set of actions performed if the condition defined by the query parameter is not satisfied. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter (or zero actions) if you do not want to define any else actions. The help text associated with the active link. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object. The owner for the active link. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the active link. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
enable
query
actionList
elseList
helpText
owner changeDiary
6-8
ARCreateActiveLink
Return Values status
A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARDeleteActiveLink, ARDeleteField, ARGetActiveLink, ARGetField, ARGetListActiveLink, ARGetListField, ARSetActiveLink, ARSetField, FreeARActiveLinkActionList, FreeARInternalIdList, FreeARQualifierStruct, FreeARStatusList
See Also
Functions
6-9
ARCreateCharMenu
Description ARCreateCharMenu creates a new character menu with the indicated name on the specified server.
Privileges
Synopsis
int ARCreateCharMenu( ARControlStruct ARNameType unsigned int ARCharMenuStruct char ARNameType char ARStatusList Input Arguments control *control, name, refreshCode, *menuDefn, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the character menu to create. The names of all character menus on a given server must be unique. A value indicating when the menu is refreshed. This parameter enables you to balance menu consistency with performance.
1: 2: 3:
name refreshCode
Refresh only when schema opened (AR_MENU_REFRESH_CONNECT). Refresh every time menu opened (AR_MENU_REFRESH_OPEN). Refresh first time menu opened and every 15 minutes thereafter (AR_MENU_REFRESH_INTERVAL).
menuDefn helpText
The definition of the character menu. The help text associated with the character menu. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object.
6-10
ARCreateCharMenu
owner changeDiary
The owner for the character menu. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the character menu. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
ARDeleteCharMenu, ARExpandCharMenu, ARGetCharMenu, ARGetListCharMenu, ARSetCharMenu, FreeARCharMenuStruct, FreeARStatusList
See Also
Functions
6-11
ARCreateContainer
Description ARCreateContainer creates a new container with the indicated name on the specified server. Use this function to create applications and guides, the two Remedy-defined container types. A container can also be a custom type that you define.
Privileges
Synopsis
int ARCreateContainer( ARControlStruct ARNameType ARPermissionList ARInternalIdList ARContainerOwnerObj char char unsigned int ARReferenceList ARBoolean char ARNameType char ARStatusList Input Arguments control *control, name, *groupList, *admingrpList, *ownerObj, *label, *description, *type, *references, removeFlag, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the container to create. The names of all containers on a given server must be unique. A list of zero or more groups who can access this container. Specifying an empty group list defines a container accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. The
name groupList
6-12
ARCreateContainer
permission value you assign for each group determines whether users in that group see the container in the container list.
1: 2:
Users see the container in the container list (AR_PERMISSIONS_VISIBLE). Users do not see the container in the container list (AR_PERMISSIONS_HIDDEN).
admingrpList
A list of zero or more groups who can administer this container (and the referenced objects). If ownerObj is not NULL, this parameter is ignored and the Subadministrator group list of the owning schema is used instead. Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specifying an empty administrator group list defines a container that can be administered by users with administrator capability only. Specifying group ID 0 (Public) provides subadministrator capability to all members of the Subadministrator group. The schema that owns this container. Specify NULL for this parameter if you want the container to exist globally. The label for this container. It can be as many as 255 characters long or NULL. The description for this container. It can be as many as 2000 characters long or NULL. The type for this containereither guide (ARCON_GUIDE), application (ARCON_APP), or a custom type you have defined. A list of pointers to the objects referenced by this container. References can be to internal AR System objects (for example, guides reference active links and applications reference schemas) or to external objects such as URLs or file names. Specify NULL for this parameter if you do not want to associate any objects with this container. A flag specifying how invalid object references are removed when the container is created. If FALSE, references to nonexistent AR System objects will be removed with no error generated. If TRUE, an error will be generated. The help text associated with the container. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object. The owner for the container. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the container. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
ownerObj label description type references
removeFlag
helpText
owner changeDiary
Functions
6-13
ARCreateSchema, ARDeleteContainer, ARGetContainer, ARGetListContainer, ARGetListEntry, ARSetContainer, FreeARContainerInfoList, FreeARInternalIdList, FreeARPermissionList, FreeARReferenceList, FreeARStatusList
See Also
6-14
ARCreateEntry
ARCreateEntry
Description ARCreateEntry creates a new entry in the indicated schema on the specified server. You can create entries in base schemas only. To add entries to join schemas, create them in one of the underlying base schemas.
Privileges
The system creates data based on the access privileges of the user you specify for the control parameter and the createMode setting for each field (see ARCreateField on page 6-19). User permissions are verified for each specified field. The system generates an error if the user does not have write permission for a field or a field does not exist.
Synopsis
int ARCreateEntry( ARControlStruct ARNameType ARFieldValueList AREntryIdType ARStatusList Input Arguments control *control, schema, *fieldList, entryId, *status)
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, sessionId, and server fields are required. The name of the schema to create the entry in. A list of one or more field/value pairs (specified in any order) that identifies the data for the new entry. You must specify values for all required fields that do not have defined defaults. Values must be of the data type defined for the field or have a data type of 0 (AR_DATA_TYPE_NULL). NULL values can be specified for optional fields only, and assigning NULL overrides any defined field default. An error is generated if a field does not exist or the user specified by the control parameter does not have write permission for a field.
schema fieldList
Return Values entryId
The unique identifier for the new entry (system-generated).
Functions
6-15
status
ARDeleteEntry, ARGetEntry, ARGetListEntry, ARMergeEntry, ARSetEntry, FreeARFieldValueList, FreeARStatusList
See Also
6-16
ARCreateEscalation
ARCreateEscalation
Description ARCreateEscalation creates a new escalation with the indicated name on the specified server. The escalation condition is checked regularly based on the time structure defined when it is enabled.
Privileges
Synopsis
int ARCreateEscalation( ARControlStruct ARNameType AREscalationTmStruct ARNameType unsigned int ARQualifierStruct ARFilterActionList ARFilterActionList char ARNameType char ARStatusList Input Arguments control *control, name, *escalationTm, schema, enable, *query, *actionList, *elseList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the escalation to create. The names of all escalations on a given server must be unique. can take one of two forms: a time interval that defines how frequently the server checks the escalation condition (in seconds) or a bitmask that defines a particular day (by month or week) and time (hour and minute) for the server to check the condition.
name
escalationTm The time specification for evaluating the escalation condition. This parameter
schema
The name of the schema the escalation is linked to. The escalation must be associated with a single schema that currently exists on the server.
Functions
6-17
enable
A flag to enable or disable this escalation. A value of 0 disables the escalation, causing its condition checks and associated actions to not be performed. A value of 1 enables the escalation, causing its conditions to be checked at the specified time interval. A query operation performed when the escalation is executed that determines the set of entries to which the escalation actions (defined by the actionList parameter) are applied. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to match all schema entries. The set of actions performed for each entry that matches the criteria defined by the query parameter. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). The set of actions performed if no entries match the criteria defined by the query parameter. These actions are not performed for all nonmatching entries. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter (or zero actions) if you do not want to define any else actions. The help text associated with the escalation. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object. The owner for the escalation. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the escalation. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
query
actionList
elseList
helpText
owner changeDiary
ARDeleteEscalation, ARGetEscalation, ARGetListEscalation, ARSetEscalation, FreeARFilterActionList, FreeARQualifierStruct, FreeARStatusList
See Also
6-18
ARCreateField
ARCreateField
Description ARCreateField creates a new schema field with the indicated name on the specified server. Schemas can contain data and nondata fields. Nondata fields serve several purposes. Trim fields enhance the appearance and usability of the schema (for example, lines, boxes, or static text). Control fields provide mechanisms for executing active links (for example, menus, buttons, or toolbar buttons). Other nondata fields organize data for viewing (for example, pages and page holders) or show data from another schema (for example, tables and columns).
An active link can be associated with only one control field (you can, however, choose any combination of screen appearances for that field). A particular control field, however, can be associated with multiple active links. While information about nondata fields is stored on the server, they do not require storage space in the underlying database.
Privileges
Synopsis
int ARCreateField( ARControlStruct ARNameType ARInternalId ARBoolean ARNameType ARFieldMappingStruct unsigned int unsigned int unsigned int ARValueStruct ARPermissionList ARFieldLimitStruct ARDisplayInstanceList char ARNameType char ARStatusList *control, schema, *fieldId, reservedIdOK, fieldName, *fieldMap, dataType, option, createMode, *defaultVal, *permissions, *limit, *dInstanceList, *helpText, owner, *changeDiary, *status)
Functions
6-19
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, sessionId, and server fields are required. The name of the schema the field is linked to. The field must be associated with a single schema that currently exists on the server. The internal ID of the field to create. The IDs of all fields and schema views (VUIs) associated with a given schema must be unique. Specify 0 for this parameter if you want the system to generate and return the ID. Otherwise, specify a value between 536870912 and 2147483647 (limited by AR_MAX_RESERVED_FIELD_ID in arstruct.h). If you specify a reserved ID, the system generates an error unless the reservedIdOK parameter is set to 1 (TRUE) (see the Action Request System Administrators Guide, Volume 1 for restrictions on using reserved IDs). A flag indicating whether you can create the field with a reserved ID. Specify 1 (TRUE) for this parameter if you want to allow reserved IDs. Specify 0 (FALSE) if you want the system to generate an error when you specify a reserved ID for the fieldId parameter. The name of the field to create. The names of all fields and VUIs associated with a given schema must be unique. The system uses this name when it creates the SQL view of the schema for report writing purposes (applicable for SQL databases only). See the dInstanceList parameter for information about how to specify a field label. The underlying schema in which to create the field (applicable for join schemas only). If you are creating a field in a base schema, specify a field type of 1 (AR_FIELD_REGULAR). Otherwise, specify a field type of 2 (AR_FIELD_JOIN), and identify the member schema (primary or secondary) and field ID for the new field. If the member schema is also a join schema, create fields in all nested join schemas until you can map the field to an underlying base schema. The data type of the field to create.
2: 3: 4: 5: 6: 7:
schema fieldId
reservedIdOK
fieldName
fieldMap
dataType
Integer (AR_DATA_TYPE_INTEGER). Real (AR_DATA_TYPE_REAL). Character (AR_DATA_TYPE_CHAR). Diary (AR_DATA_TYPE_DIARY). Selection (AR_DATA_TYPE_ENUM). Date/time (AR_DATA_TYPE_TIME).
6-20
ARCreateField
10:
11: 31: 32: 33: 34: 35: 36:
Fixed-point decimal (AR_DATA_TYPE_DECIMAL). Values must be specified in C locale, for example 1234.56 Attachment (AR_DATA_TYPE_ATTACH). Trim (AR_DATA_TYPE_TRIM). Control (AR_DATA_TYPE_CONTROL). Table (AR_DATA_TYPE_TABLE). Column (AR_DATA_TYPE_COLUMN). Page (AR_DATA_TYPE_PAGE). Page holder (AR_DATA_TYPE_PAGE_HOLDER). Required (data fields only) (AR_FIELD_OPTION_REQUIRED). Optional (data fields only) (AR_FIELD_OPTION_OPTIONAL). Display-only (data fields only). Works like an optional field but doesnt write to the database (AR_FIELD_OPTION_DISPLAY).
option
A flag indicating whether users must enter a value in the field.

1: 2: 4:
createMode
A flag indicating the permission status for the field when users submit entries. This parameter is ignored for display-only fields.
1: 2:
Any user (including guest users) can enter data in the field when submitting (AR_FIELD_OPEN_AT_CREATE). Only users who have been granted permission can enter data in the field when submitting (AR_FIELD_PROTECTED_AT_CREATE).
defaultVal
The value to apply if a user submits an entry with no field value (applicable for data fields only). The default value can be as many as 255 bytes in length (limited by AR_MAX_DEFAULT_SIZE) and must be of the same data type as the field. Specify NULL (or AR_DEFAULT_VALUE_NONE) for trim, control, page, and page holder fields or if you do not want to define a default value. A list of zero or more groups who can access this field. Specifying an empty permission list defines a field accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. The permission value you assign for each group determines whether users in that group can modify the field.
1: 2:
permissions
Users can view but not modify the field (AR_PERMISSIONS_VIEW). Users can view and modify the field (AR_PERMISSIONS_CHANGE).
limit
The value limits for the field and other properties specific to the fields type. See the ARFieldLimitStruct definition in ar.h to find the contained structure that applies to the type of field you are creating. The limits and properties you define must be of the same data type as the field. Specify NULL (or
Functions
6-21
AR_FIELD_LIMIT_NONE) for trim and control fields or if you do not want to define any limits or properties.
dInstanceList
A list of zero or more display properties to associate with the field (see Display Properties below). You can define both display properties common to all schema views (VUIs) and display properties specific to particular views. The system includes the field in each view you specify, regardless of whether you define any display properties for those views. If you do not specify a property for a particular view, the system uses the default value (if defined). Specify NULL for this parameter if you do not want to define any display properties. The help text associated with the field. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object. The owner for the field. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the field. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
helpText
owner changeDiary
Return Values fieldId status
The internal ID of the new field. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values). You can specify the following display properties in any order. Avoid specifying a property more than once, because the system then chooses one of your definitions at random.
AR_DPROP_NONE:
Display Properties
Indicates the NULL display property. You can specify no display properties by passing an empty property list. This property will be ignored if the list also contains other display properties.
AR_DPROP_TRIM_TYPE (unsigned long):
A value indicating the type of trim field.

1: 2: 3:
Horizontal or vertical line (AR_DVAL_TRIM_LINE). Box (rectangle) (AR_DVAL_TRIM_SHAPE). One or more rows of text (AR_DVAL_TRIM_TEXT).
6-22
ARCreateField
AR_DPROP_CNTL_TYPE (unsigned long):
A bitmask indicating the screen appearance for a control field.

Bit 0: Bit 1: Bit 2:
Button (AR_DVAL_CNTL_BUTTON). Menu item (AR_DVAL_CNTL_MENU). Toolbar button (AR_DVAL_CNTL_TOOLBAR).
AR_DPROP_BBOX (ARCoordList):
A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field (applicable for all fields except page and column fields). The first coordinate pair identifies the upper-left corner for the field. The second coordinate pair identifies the lower-right corner (see also AR_DPROP_COORDS).
AR_DPROP_VISIBLE (unsigned long):
A flag indicating the visibility of the field. Valid values for this property are 0 (hidden) and 1 (visible). The default value is 1 (visible). For control fields, this setting applies to all specified screen appearances (see AR_DPROP_CNTL_TYPE).
AR_DPROP_ENABLE (unsigned long):
A value identifying the enabled/disabled status of the field. For control fields, this setting applies to all specified screen appearances (see AR_DPROP_CNTL_TYPE).
1:
2: 3:
View and select only (data); disabled (trim or control) (AR_DVAL_ENABLE_READ_ONLY). View, select, and change (data); enabled (trim or control) (AR_DVAL_ENABLE_READ_WRITE) (default setting). Disabled (data, trim, or control) (AR_DVAL_ENABLE_DISABLE).
AR_DPROP_Z_ORDER (unsigned long):
A value that determines the field drawing order. The value associated with each field in a view (VUI) determines the back-to-front layering of the fields on the screen (from lowest to highest). The Z-order values of all fields associated with a given view must be unique. If two or more fields have duplicate Z-order values, the system will order them at random. Note: Remedy User 4.0 for Windows will display table fields, page holder fields, and buttons with images in front of other fields regardless of their Z-order.
Functions
6-23
AR_DPROP_TAB_ORDER (unsigned long):
A value that determines the field tab order (from lowest to highest).
AR_DPROP_DEPTH_EFFECT (unsigned long):
A value indicating the three-dimensional style for the field. This property, in conjunction with the AR_DPROP_LINE_WIDTH property, determines the overall look of line- and box-type trim fields.
0: 1: 2:
4:
No three-dimensional effect (AR_DVAL_DEPTH_EFFECT_FLAT). Field appears to lie above screen surface (AR_DVAL_DEPTH_EFFECT_RAISED). Field appears to lie below screen surface (AR_DVAL_DEPTH_EFFECT_SUNKEN). Field appears to be etched into screen surface (AR_DVAL_DEPTH_EFFECT_ETCHED).
AR_DPROP_LABEL (character string):
The screen label for the field (applicable for data fields only). This label can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
AR_DPROP_LABEL_BBOX (ARCoordList):
A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the field label (applicable for data fields only). The first coordinate pair identifies the upper-left corner for the label. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the fields location as specified in its AR_DPROP_BBOX property, not to the window or page containing it.
AR_DPROP_LABEL_COLOR_TEXT (character string):
The color of the field label. Specify the color as #BBGGRR, a string concatenating the two-digit hexadecimal values for blue, green, and red.
AR_DPROP_LABEL_POS_SECTOR (unsigned long):
A value indicating the label position relative to the field. This property, in conjunction with the AR_DPROP_LABEL_POS_JUSTIFY and AR_DPROP_LABEL_POS_ALIGN properties, determines the specific placement and alignment of the screen label (see the Note that follows AR_DPROP_LABEL_POS_ALIGN).
0: 2: 16:
Suppress label display (AR_DVAL_SECTOR_NONE). Above the field (AR_DVAL_SECTOR_NORTH). Left of the field (AR_DVAL_SECTOR_WEST) (default setting).
6-24
ARCreateField
AR_DPROP_LABEL_POS_JUSTIFY (unsigned long):
A value indicating the horizontal alignment of the label within the sector (see the Note that follows AR_DPROP_LABEL_POS_ALIGN).
1: 2: 4:
Left-justified (AR_DVAL_JUSTIFY_LEFT). Center-justified (AR_DVAL_JUSTIFY_CENTER). Right-justified (AR_DVAL_JUSTIFY_RIGHT).
AR_DPROP_LABEL_POS_ALIGN (unsigned long):
A value indicating the vertical alignment of the label within the sector (see the Note that follows).
1: 2: 4:
Top-aligned (AR_DVAL_ALIGN_TOP). Middle-aligned (AR_DVAL_ALIGN_MIDDLE). Bottom-aligned (AR_DVAL_ALIGN_BOTTOM).
Note:
The following two combinations of values for the

AR_DPROP_LABEL_POS_SECTOR, AR_DPROP_LABEL_POS_JUSTIFY, and AR_DPROP_LABEL_POS_ALIGN properties provide the best-
looking views in Remedy User.

SECTOR JUSTIFY ALIGN
north west
left left
bottom top
Label Position top left
AR_DPROP_COORDS (ARCoordList):
A set of coordinates (X,Y) that specify the vertex location (applicable for line- and box-type trim fields only). For line-type trim fields, identify the vertices of the line segment by using two coordinate pairs. For box-type trim fields, identify the corners of the box (clockwise from the upper-left corner) by using four coordinate pairs (see also AR_DPROP_BBOX). To minimize display differences across a variety of operating systems and screen resolutions, the AR System client tools standardize all coordinate values before storing them in the database and then map these values to the current environment upon retrieval. When specifying (or retrieving) coordinate data for any property with ARCoordList, you must apply the same translation algorithms in order for Remedy Administrator and Remedy User to display the field correctly. For additional information, see Using ARCoordList to Specify Field Size and Location on page 3-26.
Functions
6-25
AR_DPROP_LINE_WIDTH (unsigned long):
The line width for the field (applicable for line- and box-type trim fields only). The default value is 3 pixels.
AR_DPROP_DATA_ROWS (unsigned long):
The number of text rows to display for the field (applicable for data fields only).
AR_DPROP_DATA_COLS (unsigned long):
The number of text columns to display for the field (applicable for data fields only). AR_DPROP_DATA_BBOX overrides this value.
AR_DPROP_DATA_SPIN (unsigned long):
A flag indicating whether the field has a numeric spinner (applicable for integer fields only). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (no numeric spinner).
AR_DPROP_DATA_MENU (unsigned long):
A flag indicating whether the field has a drop-down list (applicable for selection fields only). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (no drop-down list).
AR_DPROP_DATA_RADIO (unsigned long):
A flag indicating whether the field uses radio option buttons (applicable for selection fields only). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (does not use option buttons).
AR_DPROP_DATA_MENU_BBOX (ARCoordList):
A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the fields menu button (applicable for character fields with an attached menu only). The first coordinate pair identifies the upper-left corner for the button. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the fields location as specified in its AR_DPROP_BBOX property, not to the window.
AR_DPROP_DATA_EXPAND_BBOX (ARCoordList):
A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the fields text editor button (applicable for diary and long character fields only). The first coordinate pair identifies the upper-left corner for the button. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the fields location as specified in its AR_DPROP_BBOX property, not to the window.
6-26
ARCreateField
AR_DPROP_TEXT (character string):
The text for a text-type trim field. Text that does not fit within its bounding box causes the schema window to scale up to accommodate it (see AR_DPROP_BBOX).
AR_DPROP_TEXT_FONT_STYLE (character string):
The name of the font style to use for a text-type trim field. Font used for data fields. Optional: Font used for optional data field labels. PushButton: Font used for button labels. System: Font used for system-generated data field labels. RadioButton: Font used for option button choices. Required: Font used for required data field labels. Header1: Font used for titles. Header2: Font used for major headings. Header3: Font used for minor headings. Note: Font used for notes. Detail: Font used for detail information.
Editor: AR_DPROP_HTML_TEXT (character string):
The text for a text-type trim field that includes a URL. The string must include a standard HTML anchor tag (<A>) that encloses the text to be linked and specifies the URL to link to. Text that does not fit within its bounding box causes the schema window to scale up to accommodate it (see AR_DPROP_BBOX).
AR_DPROP_HTML_TEXT_COLOR (character string):
The color of the linked text for a text-type trim field that includes a URL (see AR_DPROP_HTML_TEXT). Use one of the values listed for AR_DPROP_LABEL_COLOR_TEXT or specify a custom color as 0xBBGGRR, a string concatenating the two-digit hexadecimal values for blue, green, and red. The default value is the link color specified in the users web browser preferences.
AR_DPROP_JUSTIFY (unsigned long):
A value indicating the horizontal justification of text within its bounding box.
1: 2: 4:
Left-aligned (AR_DVAL_JUSTIFY_LEFT) Centered (AR_DVAL_JUSTIFY_CENTER) Right-aligned (AR_DVAL_JUSTIFY_RIGHT)
Functions
6-27
AR_DPROP_ALIGN (unsigned long):
A value indicating the vertical alignment of text within its bounding box.
1: 2: 4:
Top-aligned (AR_DVAL_ALIGN_TOP). Centered (AR_DVAL_ALIGN_MIDDLE) (default setting). Bottom-aligned (AR_DVAL_ALIGN_BOTTOM).
AR_DPROP_IMAGE (ARByteList):
The icon image for a toolbar-type control field. Specify a byte list type of 1 (AR_BYTE_LIST_WIN30_BITMAP) for images in Windows 3.0 bitmap (.bmp) and DIB (.dib) format. Specify 0 (AR_BYTE_LIST_SELF_DEFINED) for all other image formats. Note: The only image formats currently supported on toolbar control fields are Windows 3.0 bitmap and DIB. The only image size currently supported is 16 pixels wide by 15 pixels high. Images of other sizes are not scaled to fit. When creating images, use simple images and the 216-color Web palette for best results.
AR_DPROP_PUSH_BUTTON_IMAGE (ARByteList):
The icon image for a button. Specify a byte list type of 1 (AR_BYTE_LIST_WIN30_BITMAP) for images in Windows 3.0 bitmap (.bmp) and DIB (.dib) format. Specify 2 (AR_BYTE_LIST_JPEG) for JPEG (.jpg or .jpeg) format. Note: The only image formats currently supported on button fields are JPEG, Windows 3.0 bitmap, and DIB. There is no limit to the pixel dimensions or file size of a button image, but large images can slow down your systems performance. When creating images, use simple images and the 216-color Web palette for best results.
AR_DPROP_BUTTON_TEXT (character string):
The button label for the field (applicable for control fields only). This label can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
6-28
ARCreateField
AR_DPROP_BUTTON_2D (unsigned long):
A flag indicating whether the button appears as a two-dimensional image with no border (applicable for control fields only). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (threedimensional with borders).
AR_DPROP_BUTTON_IMAGE_POSITION (unsigned long):
A value that determines the position of the button image relative to the button label (applicable for control fields only). The default value is 0 (centered, no label).
0: 1: 2: 3: 4:
AR_DVAL_IMAGE_CENTER (centered, no label). AR_DVAL_IMAGE_LEFT (to the left of the label). AR_DVAL_IMAGE_RIGHT (to the right of the label). AR_DVAL_IMAGE_ABOVE (above the label). AR_DVAL_IMAGE_BELOW (below the label).
AR_DPROP_BUTTON_SCALE_IMAGE (unsigned long):
A flag indicating whether the button image will shrink or grow to fill the space available after allocating space for the button label (applicable for control fields only). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (leave image at original size).
AR_DPROP_BUTTON_MAINTAIN_RATIO (unsigned long):
A flag indicating whether a scaled button image will preserve its original width-to-height ratio (applicable for control fields only). Valid values for this property are 1 (TRUE) and 0 (FALSE). The default value is 0 (do not preserve ratio). This property only affects the image when AR_DPROP_BUTTON_SCALE_IMAGE is TRUE.
AR_DPROP_MENU_TEXT (character string):
The menu item text for the field (applicable for control fields only). This text can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
AR_DPROP_MENU_POS (unsigned long):
A value that determines the menu position for the field (applicable for control fields only). For leaf- or intermediate-level menu items, the value associated with each field in a view (VUI) determines the top-to-bottom order of the items in the menu (from lowest to highest, starting with one). For top-level menu items, this value determines the left-to-right order of the items in the menu bar.
Functions
6-29
AR_DPROP_MENU_MODE (unsigned long):
A value indicating the type of menu item (applicable for control fields only).
0: 2: 5:
Leaf-level menu item (AR_DVAL_CNTL_ITEM). Separator item (AR_DVAL_CNTL_SEPARATOR). Top- or intermediate-level menu item (AR_DVAL_CNTL_A_MENU).
AR_DPROP_MENU_PARENT (unsigned long):
A value identifying the parent menu item for the field (applicable for control fields only). Specify the field ID of the parent control field for leafor intermediate-level menu items. Specify 0 for top-level menu items.
AR_DPROP_MENU_HELP (character string):
The help text for a menu-type control field. This text can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
AR_DPROP_TOOLTIP (character string):
The tooltip text for a toolbar-type control field. This text can be as many as 30 bytes in length (limited by AR_MAX_NAME_SIZE).
AR_DPROP_TOOLBAR_POS (unsigned long):
A value that determines the toolbar position for the field (applicable for control fields only). The value associated with each field in a view (VUI) determines the left-to-right order of the icons in the toolbar (from lowest to highest, starting with one).
AR_DPROP_TOOLBAR_MODE (unsigned long):
A value indicating the type of toolbar item (applicable for control fields only).
0: 2:
Toolbar button (AR_DVAL_CNTL_ITEM). Toolbar separator (AR_DVAL_CNTL_SEPARATOR).
AR_DPROP_DATETIME_POPUP (unsigned long):
A value indicating the display type of a date/time field. The default value is 0 (both date and time).
0: 1: 2:
Both date and time (AR_DVAL_DATETIME_BOTH) (default setting). Time only (AR_DVAL_DATETIME_TIME). Date only (AR_DVAL_DATETIME_DATE).
6-30
ARCreateField
AR_DPROP_BACKGROUND_MODE (unsigned long):
A value indicating whether the background of a field is opaque or transparent (applicable for trim fields only). Specify 0 for opaque (AR_DVAL_BKG_MODE_OPAQUE) or 1 for transparent (AR_DVAL_BKG_MODE_TRANSPARENT). The default value is 0 (opaque).
AR_DPROP_DATA_BBOX (ARCoordList):
A set of coordinates (X,Y) that specify the screen boundaries (bounding box) for the fields data area (applicable for data fields only). For example, this property locates the entry box for a character field and the buttons for a radio button selection field. The first coordinate pair identifies the upper-left corner for the data area. The second coordinate pair identifies the lower-right corner. The coordinates specified are relative to the fields location as specified in its AR_DPROP_BBOX property, not to the window or page containing it.
AR_DPROP_DISPLAY_PARENT (unsigned long):
A value indicating the parent field that the field will display in. Specify the field ID of the parent. A page holder field is the parent of the page fields displayed in it, and a page field is the parent of the fields displayed in it. A value of 0 indicates that the fields parent is the schema view and not another field. The default value is 0.
AR_DPROP_COLUMN_WIDTH (integer):
The width of a column in a table field.

AR_DPROP_COLUMN_ORDER (integer):
The order of a column in a table field. The column with the lowest value will be the left-most displayed.
AR_DPROP_SORT_SEQ (integer):
The sort order of a column in a table field. The system will sort based on the column with the lowest value first. To keep from sorting based on a column, specify 0 (the default).
AR_DPROP_SORT_DIR (integer):
A value indicating the sort direction of a column in a table field. Specify 0 for ascending (AR_DVAL_SORT_DIR_ASCENDING) and 1 for descending (AR_DVAL_SORT_DIR_DESCENDING).
AR_DPROP_DRILL_DOWN (unsigned long):
A bitmask indicating whether drill-down is enabled for a table field. Specify bit 0 to disable and 1 to enable. When drill-down is enabled and a user double-clicks a row in the table field, a Modify window opens for the entry represented by that row.
Functions
6-31
AR_DPROP_AUTO_REFRESH (unsigned long):
A value indicating whether automatic refresh is enabled (applicable for table fields only). Specify 0 to disable (AR_DVAL_AUTO_REFRESH_NONE) and 1 to enable (AR_DVAL_AUTO_REFRESH_TABLE_MAX). When automatic refresh is enabled, the contents of the table field will be updated when the entry is displayed in a Modify window. When automatic refresh is disabled, the table appears empty until the user clicks within its borders to refresh it.
See Also ARCreateVUI, ARDeleteField, ARGetField, ARGetListField, ARSetField, FreeARFieldLimitStruct, FreeARPermissionList, FreeARStatusList, FreeARValueStruct
6-32
ARCreateFilter
ARCreateFilter
Description ARCreateFilter creates a new filter with the indicated name on the specified server. The filter takes effect immediately and remains in effect until changed or deleted.
Privileges
Synopsis
int ARCreateFilter( ARControlStruct ARNameType unsigned int ARNameType unsigned int unsigned int ARQualifierStruct ARFilterActionList ARFilterActionList char ARNameType char ARStatusList Input Arguments control *control, name, order, schema, opSet, enable, *query, *actionList, *elseList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the filter to create. The names of all filters on a given server must be unique. A value between 0 and 1000 (inclusive) that determines the filter execution order. When multiple filters are associated with a schema, the value associated with each filter determines the order in which they are processed (from lowest to highest). The name of the schema the filter is linked to. The filter must be associated with a single schema that currently exists on the server.
name order
schema
Functions
6-33
opSet
A bitmask indicating the schema operations that trigger the filter.

Bit 0: Bit 1: Bit 2: Bit 3: Bit 4:
Execute the filter on get operations (AR_OPERATION_GET). Execute the filter on set operations (AR_OPERATION_SET). Execute the filter on create operations (AR_OPERATION_CREATE). Execute the filter on delete operations (AR_OPERATION_DELETE). Execute the filter on merge operations (AR_OPERATION_MERGE).
enable
A flag to enable or disable this filter. A value of 0 disables the filter, causing its condition checks and associated actions to not be performed. A value of 1 enables the filter, causing its conditions to be checked for each schema operation specified by the opSet parameter. A qualification that determines whether the filter is executed. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to execute the filter unconditionally. The set of actions performed if the condition defined by the query parameter is satisfied. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). The set of actions performed if the condition defined by the query parameter is not satisfied. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter (or zero actions) if you do not want to define any else actions. The help text associated with the filter. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object. The owner for the filter. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the filter. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
query
actionList
elseList
helpText
owner changeDiary
ARDeleteFilter, ARGetFilter, ARGetListFilter, ARSetFilter, FreeARFilterActionList, FreeARQualifierStruct, FreeARStatusList
See Also
6-34
ARCreateSchema
ARCreateSchema
Description ARCreateSchema creates a new schema with the indicated name on the specified server. The nine required core fields are automatically associated with the new schema.
Privileges
Synopsis
int ARCreateSchema( ARControlStruct ARNameType ARCompoundSchema ARPermissionList ARInternalIdList AREntryListFieldList ARSortList ARIndexList char ARNameType char ARStatusList Input Arguments control *control, name, *schema, *groupList, *admingrpList, *getListFields, *sortList, *indexList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema to create. The names of all schemas on a given server must be unique. The type of schema to create. The information contained in this definition depends on the schema type you specify.
name schema
Functions
6-35
1:
2:
4:
Indicates a base schema (AR_SCHEMA_REGULAR). All other structure information is ignored if you specify this type. Indicates a join schema (AR_SCHEMA_JOIN). If you specify this type you must identify the underlying member schemas and how to join them. Indicates a display-only schema (AR_SCHEMA_DIALOG). The getListFields, sortList, and indexList parameters are ignored if you specify this type.
groupList
A list of zero or more groups who can access this schema. Specifying an empty group list defines a schema accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. The permission value you assign for each group determines whether users in that group see the schema in the schema list.
1: 2:
Users see the schema in the schema list (AR_PERMISSIONS_VISIBLE). Users do not see the schema in the schema list (AR_PERMISSIONS_HIDDEN).
admingrpList
A list of zero or more groups who can administer this schema (and the associated filters, escalations, and active links). Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specifying an empty administrator group list defines a schema that can be administered by users with administrator capability only. Specifying group ID 0 (Public) provides subadministrator capability to all members of the Subadministrator group. A list of zero or more fields that identifies the default query list data for retrieving schema entries. The list can include any data fields except diary fields and long character fields. The combined length of all specified fields, including separator characters, can be as many as 128 bytes (limited by AR_MAX_SDESC_SIZE). The query list displays the Short-Description core field if you specify NULL for this parameter (or zero fields). Specifying a getListFields argument when calling the ARGetListEntry function overrides the default query list data. A list of zero or more fields that identifies the default sort order for retrieving schema entries. Specifying a sortList argument when calling the ARGetListEntry function overrides the default sort order. The set of zero or more indexes to create for the schema. You can specify from 1 to 16 fields for each index (limited by AR_MAX_INDEX_FIELDS). Diary fields and character fields larger than 255 bytes cannot be indexed. The help text associated with the schema. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object.
getListFields
sortList
indexList
helpText
6-36
ARCreateSchema
owner changeDiary
The owner for the schema. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the schema. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
ARCreateField, ARDeleteSchema, ARGetSchema, ARGetListEntry, ARGetListSchema, ARSetField, ARSetSchema, FreeARCompoundSchema, FreeAREntryListFieldList, FreeARIndexList, FreeARInternalIdList, FreeARPermissionList, FreeARSortList, FreeARStatusList
See Also
Functions
6-37
ARCreateSupportFile
Description ARCreateSupportFile creates a file that clients can retrieve by using the AR System. Such files are commonly used for reports (to store them separately from the active link that calls them, preventing large downloads of unneeded information), but this function can store any file on the server. Each support file is associated with a server object.
Privileges
Synopsis
int ARCreateSupportFile( ARControlStruct unsigned int ARNameType ARInternalId ARInternalId FILE ARStatusList Input Arguments control *control, fileType, name, fieldId, fileId, *filePtr, *status)
The control record for the operation. It contains information about the user requesting the operation and where that operation is to be performed. The user and server fields are required. The numerical value for the type of file, and the type of object the file is related to. Specify 1 (AR_SUPPORT_FILE_EXTERNAL_REPORT) for an external report file associated with an active link. The name of the object the file is associated with, usually a schema. The ID of the field or VUI, if the object is a schema. If the object is not a schema, set this parameter to 0. The unique identifier of a file within its object. A pointer to the support file to be created in the system. If using Windows, you must open the file in binary mode.
fileType
name fieldId fileId filePtr
6-38
ARCreateSupportFile
Return Values status See Also
A list of zero or more notes, warnings, or errors generated from the function call. (see Error Checking on page 4-9 for a description of all possible values)
ARCreateActiveLink, ARDeleteActiveLink, ARDeleteSupportFile, ARGetActiveLink, ARGetListSupportFile, ARGetSupportFile, ARSetActiveLink, ARSetSupportFile
Functions
6-39
ARCreateVUI
Description ARCreateVUI creates a new schema view (VUI) with the indicated name on the specified server.
Privileges
Synopsis
int ARCreateVUI( ARControlStruct ARNameType ARInternalId ARNameType ARPropList char ARNameType char ARStatusList Input Arguments control *control, schema, *vuiId, vuiName, *dPropList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema the VUI is linked to. The VUI must be associated with a single schema that currently exists on the server. The internal ID of the VUI to create. The IDs of all VUIs and fields associated with a given schema must be unique. Specify 0 for this parameter if you want the system to generate and return the ID. Otherwise, specify a value between 536870912 and 2147483647 (limited by AR_MAX_RESERVED_FIELD_ID in arstruct.h). The name of the VUI to create. The names of all VUIs and fields associated with a given schema must be unique. A list of zero or more display properties to associate with the VUI (see Display Properties below). Specify NULL for this parameter if you do not want to define any display properties.
schema vuiId
vuiName dPropList
6-40
ARCreateVUI
helpText
The help text associated with the VUI. This text can be of any length. Specify NULL for this parameter if you do not want to associate help text with this object. The owner for the VUI. The owner defaults to the user performing the operation if you specify NULL for this parameter. The initial change diary associated with the VUI. This text can be of any length. The user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to associate change diary text with this object.
owner changeDiary
Return Values vuiId status
The internal ID of the new VUI. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
Display Properties AR_DPROP_VUI_DEFAULT (unsigned long):
A flag identifying the default view (VUI) for the schema. A value of 1 identifies the default VUI (with all other VUIs having a value of 0). The system uses the first VUI returned by the ARGetListVUI function if you do not specify a default view.
AR_DPROP_PANE_LAYOUT (integer):
A value indicating how the panes of the VUI are arranged. This property also specifies whether the layout is locked to prevent the user from changing it.
-1: -2: -3: -4: -5: -6: -7: -8: 1: 2: 3: 4:
Results pane left of details, prompt pane on top, locked. Details pane left of results, prompt pane on top, locked. Results pane above details, prompt pane on top, locked. Details pane above results, prompt pane on top, locked. Results pane left of details, prompt pane on bottom, locked. Details pane left of results, prompt pane on bottom, locked. Results pane above details, prompt pane on bottom, locked. Details pane above results, prompt pane on bottom, locked. Results pane left of details, prompt pane on top, unlocked. Details pane left of results, prompt pane on top, unlocked. Results pane above details, prompt pane on top, unlocked. Details pane above results, prompt pane on top, unlocked.
Functions
6-41
5: 6: 7: 8:
Results pane left of details, prompt pane on bottom, unlocked. Details pane left of results, prompt pane on bottom, unlocked. Results pane above details, prompt pane on bottom, unlocked. Details pane above results, prompt pane on bottom, unlocked.
AR_DPROP_DETAIL_PANE_COLOR (character string):
The background color of the details pane. Specify the color as #BBGGRR, a string concatenating the two-digit hexadecimal values for blue, green, and red.
AR_DPROP_DETAIL_PANE_IMAGE (ARByteList):
The background image for the details pane. Specify a byte list type of 1 (AR_BYTE_LIST_WIN30_BITMAP) for images in Windows 3.0 bitmap (.bmp) and DIB (.dib) format. Specify 2 (AR_BYTE_LIST_JPEG) for JPEG (.jpg or .jpeg) format (see AR_DPROP_PUSH_BUTTON_IMAGE).
AR_DPROP_IMAGE_ALIGN (unsigned long):
A value indicating the vertical alignment of the background image for the details pane.
1: 2: 3: 4: 5:
Top-aligned (AR_DVAL_ALIGN_TOP). Centered (AR_DVAL_ALIGN_MIDDLE) (default setting). Expand to fill (AR_DVAL_ALIGN_FILL). Bottom-aligned (AR_DVAL_ALIGN_BOTTOM). Tile to fill (AR_DVAL_ALIGN_TILE).
AR_DPROP_IMAGE_JUSTIFY (unsigned long):
A value indicating the horizontal justification of the background image for the details pane.
1: 2: 3: 4: 5:
Left-aligned (AR_DVAL_JUSTIFY_LEFT). Centered (AR_DVAL_JUSTIFY_CENTER). Expand to fill (AR_DVAL_JUSTIFY_FILL). Right-aligned (AR_DVAL_JUSTIFY_RIGHT). Tile to fill (AR_DVAL_JUSTIFY_TILE).
AR_DPROP_TITLE_BAR_ICON_IMAGE (ARByteList):
The icon image for the title bar. Specify a byte list type of 1 (AR_BYTE_LIST_WIN30_BITMAP) for images in Windows 3.0 bitmap (.bmp) and DIB (.dib) format. Specify 2 (AR_BYTE_LIST_JPEG) for JPEG (.jpg or .jpeg) format.
6-42
ARCreateVUI
AR_DPROP_DETAIL_PANE_WIDTH (integer):
The width of the details pane, in schema coordinates. Negative values are reserved for future use.
AR_DPROP_DETAIL_PANE_HEIGHT (integer):
The height of the details pane, in schema coordinates.

AR_DPROP_DETAIL_BANNER_VISIBILITY (unsigned long):
A value indicating whether the details pane is visible. Specify 0 for invisible, 1 for visible.
AR_DPROP_RESULT_BANNER_VISIBILITY (unsigned long):
A value indicating whether the results pane is visible. Specify 0 for invisible, 1 for visible.
AR_DPROP_ALIAS_SINGULAR (character string):
The singular form of the name for the logical items represented by entries in the schema this view is associated with (such as help desk calls). Remedy User displays this name instead of the default request when referring to schema entries.
AR_DPROP_ALIAS_PLURAL (character string):
The plural form of the name for the logical items represented by entries in the schema this view is associated with (see AR_DPROP_ALIAS_SINGULAR).
AR_DPROP_ALIAS_SHORT_SINGULAR (character string):
A short, singular form of the name for the logical items represented by entries in the schema this view is associated with (see AR_DPROP_ALIAS_SINGULAR).
AR_DPROP_ALIAS_SHORT_PLURAL (character string):
A short, plural form of the name for the logical items represented by entries in the schema this view is associated with (see AR_DPROP_ALIAS_SINGULAR).
AR_DPROP_ALIAS_ABBREV_SINGULAR (character string):
A very short, singular form of the name for the logical items represented by entries in the schema this view is associated with (see AR_DPROP_ALIAS_SINGULAR).
AR_DPROP_ALIAS_ABBREV_PLURAL (character string):
A very short, plural form of the name for the logical items represented by entries in the schema this view is associated with (see AR_DPROP_ALIAS_SINGULAR).
Functions
6-43
AR_DPROP_NAMED_SEARCHES (character string):
A list of administrator-defined searches. It is encoded in the same format as qualifications in .arf files. This is a Remedy Private property that is not supported for customer use.
AR_DPROP_MENU_ACCESS (character string):
A list of client interface items an administrator can control. It is encoded in the same format as qualifications in .arf files. This is a Remedy Private property that is not supported for customer use.
AR_DPROP_QUERY_LIST_COLOR (character string):
The name of the field whose value for a given entry controls the display color of that entry in a query results list, and a list of field values and their corresponding colors. This is a Remedy Private property that is not supported for customer use.
See Also ARCreateField, ARDeleteVUI, ARGetVUI, ARGetListVUI, ARSetVUI, FreeARPropList, FreeARStatusList
6-44
ARDecodeDiary
ARDecodeDiary
Description ARDecodeDiary parses any diary field (including the changeDiary associated with every AR System object) into user, time stamp, and text components. The function takes the formatted string returned for all diary fields and decodes it into an array of diary entries.
Privileges Synopsis
This operation can be performed by all users.

int ARDecodeDiary( ARControlStruct char ARDiaryList ARStatusList Input Arguments control *control, *diaryString, *diaryList, *status)
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, sessionId, and server fields are required. A formatted diary string returned by ARGetEntry or any of the ARGet<object> API functions.
diaryString
Return Values diaryList status
An array of decoded diary entries. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARDecodeStatusHistory, ARGetActiveLink, ARGetCharMenu, ARGetEntry, ARGetField, ARGetFilter, ARGetSchema, ARGetVUI, FreeARDiaryList, FreeARStatusList
See Also
Functions
6-45
ARDecodeStatusHistory
Description ARDecodeStatusHistory parses the Status History core field into user and time stamp components. The function takes the formatted string returned for this field and decodes it into an array of status history entries.
Privileges Synopsis

int ARDecodeStatusHistory( ARControlStruct char ARStatusHistoryList ARStatusList Input Arguments control *control, *statHistString, *statHistList, *status)
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, sessionId, and server fields are required. A formatted status history string returned by ARGetEntry.
statHistString
Return Values statHistList An array of decoded status history entries. status
ARDecodeDiary, ARGetEntry, FreeARStatusList, FreeARStatusHistoryList
See Also
6-46
ARDeleteActiveLink
ARDeleteActiveLink
Description ARDeleteActiveLink deletes the active link with the indicated name from the specified server and deletes any container references to the active link. The active link is deleted from the server immediately and is not returned to users who request information about active links. Because active links operate on clients, individual clients can continue using the active link until they reconnect to the schema (thus reloading the schema from the server).
Privileges
Synopsis
int ARDeleteActiveLink( ARControlStruct ARNameType ARStatusList Input Arguments control *control, name, *status)
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, sessionId, and server fields are required. The name of the active link to delete.
name Return Values status
ARCreateActiveLink, ARDeleteSchema, ARGetActiveLink, ARGetListActiveLink, ARSetActiveLink, FreeARStatusList
See Also
Functions
6-47
ARDeleteCharMenu
Description ARDeleteCharMenu deletes the character menu with the indicated name from the specified server. The character menu is deleted from the server immediately and is not returned to users who request information about character menus. Because character menus operate on clients, individual clients can continue using the character menu until they reconnect to the schema (thus reloading the schema from the server).
Privileges
Synopsis
int ARDeleteCharMenu( ARControlStruct ARNameType ARStatusList Input Arguments control *control, name, *status)
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, sessionId, and server fields are required. The name of the character menu to delete.
ARCreateCharMenu, ARExpandCharMenu, ARGetCharMenu, ARGetListCharMenu, ARSetCharMenu, FreeARStatusList
See Also
6-48
ARDeleteContainer
ARDeleteContainer
Description ARDeleteContainer deletes the container with the indicated name from the specified server and deletes any references to the container from other containers. Objects referenced by the container are not deleted.
Privileges
Synopsis
int ARDeleteContainer( ARControlStruct ARNameType ARStatusList Input Arguments control *control, name, *status)
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, sessionId, and server fields are required. The name of the container to delete.
ARCreateContainer, ARGetContainer, ARGetListContainer, ARSetContainer, FreeARStatusList
See Also
Functions
6-49
ARDeleteEntry
Description ARDeleteEntry deletes the schema entry with the indicated ID from the specified server. You can delete entries from base schemas only. To remove entries from join schemas, delete them from the underlying base schemas.
Privileges
Synopsis
int ARDeleteEntry( ARControlStruct ARNameType AREntryIdList unsigned int ARStatusList Input Arguments control *control, schema, *entryId, option, *status)
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, sessionId, and server fields are required. The name of the base schema containing the entry to delete. The ID of the entry to delete. Specify 0 for this parameter (reserved for future use).
schema entryId option Return Values status
ARCreateEntry, ARDeleteSchema, ARGetEntry, ARGetListEntry, ARSetEntry, FreeAREntryIdList, FreeARStatusList
See Also
6-50
ARDeleteEscalation
ARDeleteEscalation
Description ARDeleteEscalation deletes the escalation with the indicated name from the specified server and deletes any container references to the escalation. The escalation is deleted from the server immediately and is not returned to users who request information about escalations.
Privileges
Synopsis
int ARDeleteEscalation( ARControlStruct ARNameType ARStatusList Input Arguments control *control, name, *status)
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, sessionId, and server fields are required. The name of the escalation to delete.
ARCreateEscalation, ARDeleteSchema, ARGetEscalation, ARGetListEscalation, ARSetEscalation, FreeARStatusList
See Also
Functions
6-51
ARDeleteField
Description ARDeleteField deletes the schema field with the indicated ID from the specified server. Depending on the value you specify for the deleteOption parameter, the field is deleted from the server immediately and is not returned to users who request information about fields. When a parent field is deleted, its child fields may also be deleted. For example, deleting a page holder field will delete all pages within it. All fields within those pages are removed from the current view but not deleted. Deleting a table field will delete all columns within it.
Privileges
Synopsis
int ARDeleteField( ARControlStruct ARNameType ARInternalId unsigned int ARStatusList Input Arguments control *control, schema, fieldId, deleteOption, *status)
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, sessionId, and server fields are required. The name of the schema containing the field to delete. The internal ID of the field to delete. A value indicating the action to take if the specified field contains data (applicable for base schemas only) or is associated with a join schema.
0: 1:
schema fieldId
deleteOption
2:
Do not delete the field (AR_FIELD_CLEAN_DELETE). Delete if the field contains data but not if it is associated with a join schema (AR_FIELD_DATA_DELETE). Delete the field, all join schema fields that map to it, and all join schemas dependent on it for join qualification (AR_FIELD_FORCE_DELETE).
6-52
ARDeleteField
ARCreateField, ARDeleteMultipleFields, ARDeleteSchema, ARGetField, ARGetListField, ARSetField, FreeARStatusList
See Also
Functions
6-53
ARDeleteFilter
Description ARDeleteFilter deletes the filter with the indicated name from the specified server and deletes any container references to the filter. The filter is deleted from the server immediately and is not returned to users who request information about filters.
Privileges
Synopsis
int ARDeleteFilter( ARControlStruct ARNameType ARStatusList Input Arguments control *control, name, *status)
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, sessionId, and server fields are required. The name of the filter to delete.
ARCreateFilter, ARDeleteSchema, ARGetFilter, ARGetListFilter, ARSetFilter, FreeARStatusList
See Also
6-54
ARDeleteMultipleFields
ARDeleteMultipleFields
Description ARDeleteMultipleFields deletes the schema fields with the indicated IDs from the specified server. Depending on the value you specify for the deleteOption parameter, the fields are deleted from the server immediately and are not returned to users who request information about fields. This function performs the same action as ARDeleteField but is easier and more efficient than deleting multiple fields one by one.
Privileges
Synopsis
int ARDeleteMultipleFields( ARControlStruct ARNameType ARInternalIdList unsigned int ARStatusList Input Arguments control *control, schema, *fieldList, deleteOption, *status)
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, sessionId, and server fields are required. The name of the schema containing the fields to delete. The internal IDs of the fields to delete. A value indicating the action to take if one of the specified fields contains data (applicable for base schemas only) or are associated with a join schema.
0: 1:
schema fieldList
deleteOption
2:
Do not delete the field (AR_FIELD_CLEAN_DELETE). Delete if the field contains data but not if it is associated with a join schema (AR_FIELD_DATA_DELETE). Delete the field, all join schema fields that map to it, and all join schemas dependent on it for join qualification (AR_FIELD_FORCE_DELETE).
Functions
6-55
ARCreateField, ARDeleteField, ARDeleteSchema, ARGetField, ARGetListField, ARSetField, FreeARInternalIdList, FreeARStatusList
See Also
6-56
ARDeleteSchema
ARDeleteSchema
Description ARDeleteSchema deletes the schema with the indicated name from the specified server and deletes any container references to the schema. Depending on the value you specify for the deleteOption parameter, the schema is deleted from the server immediately and is not returned to users who request information about schemas. In addition, the system deletes all entries, fields, views (VUIs), active links, escalations, and filters associated with the schema and all containers owned by the schema.
Privileges
Synopsis
int ARDeleteSchema( ARControlStruct ARNameType unsigned int ARStatusList Input Arguments control *control, name, deleteOption, *status)
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, sessionId, and server fields are required. The name of the schema to delete. A value indicating the action to take if the specified schema contains entries (applicable for base schemas only) or is a member of a join schema.
0: 1:
name
deleteOption
2:
Do not delete the schema (AR_SCHEMA_CLEAN_DELETE). Delete if the schema contains entries but not if it is a member of a join schema (AR_SCHEMA_DATA_DELETE). Delete the schema and all join schemas dependent on it (AR_SCHEMA_FORCE_DELETE).
Functions
6-57
ARCreateSchema, ARGetSchema, ARGetListSchema, ARSetSchema, FreeARStatusList
See Also
6-58
ARDeleteSupportFile
ARDeleteSupportFile
Description Privileges ARDeleteSupportFile deletes a support file in the AR System.
Synopsis
int ARDeleteSupportFile( ARControlStruct unsigned int ARNameType ARInternalId ARInternalId ARStatusList Input Arguments control *control, fileType, name, fieldId, fileId, *status)
The control record for the operation. It contains information about the user requesting the operation and where that operation is to be performed. The user and server fields are required. The numerical value for the type of file, and the type of object the file is related to. Specify 1 (AR_SUPPORT_FILE_EXTERNAL_REPORT) for an external report file associated with an active link. The name of the object the file is associated with, usually a schema. The ID of the field or VUI, if the object is a schema. If the object is not a schema, set this parameter to 0. The unique identifier of a file within its object.
fileType
name fieldId fileId Return Values status See Also
ARCreateActiveLink, ARCreateSupportFile, ARDeleteActiveLink, ARGetActiveLink, ARGetListSupportFile, ARGetSupportFile, ARSetActiveLink, ARSetSupportFile, FreeARStatusList
Functions
6-59
ARDeleteVUI
Description ARDeleteVUI deletes the schema view (VUI) with the indicated ID from the specified server.
Privileges
Synopsis
int ARDeleteVUI( ARControlStruct ARNameType ARInternalId ARStatusList Input Arguments control *control, schema, vuiId, *status)
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, sessionId, and server fields are required. The name of the schema containing the VUI to delete. The internal ID of the VUI to delete.
schema vuiId Return Values status
ARCreateVUI, ARDeleteSchema, ARGetVUI, ARGetListVUI, ARSetVUI, FreeARStatusList
See Also
6-60
ARExecuteProcess
ARExecuteProcess
Description ARExecuteProcess performs the indicated command on the specified server. Depending on the values you specify for the returnStatus and returnString parameters, you can execute the command as an independent process or wait for the process to complete and return the result to the client. The system executes the command based on the access privileges of the user who launched the AR System server.
Privileges
#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARExecuteProcess( ARControlStruct char int char ARStatusList *control, *command, *returnStatus, **returnString, *status)
Synopsis
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, sessionId, and server fields are required. The command to execute (must be a valid command on the specified server).
command Return Values

returnStatus
An integer identifying the status of the operation. A value of 0 generally indicates success. Any other value generally indicates a failure. Specify NULL for this parameter and the returnString parameter if you want the system to launch an independent process and not wait for it to complete. Otherwise, specify a value for this parameter if you want the system to wait for the process to complete before returning. If the process does not finish within the time-out interval, adjust the filter process time-out interval to prevent server blocking (configurable from 1 to 20 seconds). A string containing the process output. Depending on the outcome of the operation, this string contains either result data or an error message. Specify
returnString
Functions
6-61
NULL for this parameter and the returnStatus parameter if you want the system to launch an independent process and not wait for it to complete. Otherwise, specify a value for this parameter if you want the system to wait for the process to complete before returning. If the process does not finish within the time-out interval, adjust the filter process time-out interval to prevent server blocking (configurable from 1 to 20 seconds). status
ARGetListSQL, FreeARStatusList
See Also
6-62
ARExpandCharMenu
ARExpandCharMenu
Description ARExpandCharMenu expands the query and file references for the specified menu definition and returns a character menu with list-type items only.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All query items, therefore, are limited to fields the user can access.
Synopsis
int ARExpandCharMenu( ARControlStruct ARCharMenuStruct ARCharMenuStruct ARStatusList Input Arguments control *control, *menuDefn, *menu, *status)
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, sessionId, and server fields are required. The menu definition to expand.
menuDefn Return Values menu status
The expanded character menu. The menu definition contains list-type items only. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateCharMenu, ARDeleteCharMenu, ARGetCharMenu, ARGetListCharMenu, ARSetCharMenu, FreeARCharMenuStruct, FreeARStatusList
See Also
Functions
6-63
ARExport
Description ARExport exports the indicated structure definitions from the specified server. Use this function to copy structure definitions from one AR System server to another (see ARImport on page 6-141).
Note:
Schema exports do not work the same way with ARExport as they do in Remedy Administrator. Other than views, you cannot automatically export related items along with a schema. You must explicitly specify the workflow items you want to export. Also, ARExport cannot export a schema without embedding the server name in the export file (something you can do with the Server-Independent option in Remedy Administrator).
Privileges
For filters, escalations, character menus, and distributed mappings, this operation can be performed by users with AR System administrator privileges only. For schemas, containers, and active links, this operation can be performed by users with access permission for the specified structure. Access to groupList information for these structures is limited to users with AR System administrator privileges only.
Synopsis
int ARExport( ARControlStruct ARStructItemList ARNameType char ARStatusList Input Arguments control *control, *structItems, displayTag, **exportBuf, *status)
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, sessionId, and server fields are required.
6-64
ARExport
structItems
A list of zero or more structure items to export (identified by type and name).
1: 2: 3: 4: 5: 6: 8: 9: 10: 11:
12:
Schema (includes all associated views) (AR_STRUCT_ITEM_SCHEMA). Partial schema (fields only) (AR_STRUCT_ITEM_SCHEMA_DEFN). Partial schema (specified view only) (AR_STRUCT_ITEM_SCHEMA_VIEW). Partial schema (email template only) (AR_STRUCT_ITEM_SCHEMA_MAIL). Filter (AR_STRUCT_ITEM_FILTER). Active link (AR_STRUCT_ITEM_ACTIVE_LINK). Character menu (AR_STRUCT_ITEM_CHAR_MENU). Escalation (AR_STRUCT_ITEM_ESCALATION). Distributed mapping (AR_STRUCT_ITEM_DIST_MAP). Partial schema (specified view only, without button images) (AR_STRUCT_ITEM_SCHEMA_VIEW_MIN). Container (AR_STRUCT_ITEM_CONTAINER).
Note:
You must specify AR_STRUCT_ITEM_SCHEMA to export a schema that you intend to import to another server. The three partial schema types do not contain complete schema definitions and are used for caching purposes only.
displayTag
The label of the schema view (VUI) to export. You must specify this parameter to export a particular view (AR_STRUCT_ITEM_SCHEMA_VIEW). If the specified view does not exist (or you specify NULL for this parameter), the system exports the default view. The system exports the first view in the list if the schema does not have a default view.
Return Values exportBuf
A buffer that contains the definition text for the items specified for the structItems parameter. The system returns error messages for items not exported due to error. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARImport, FreeARStatusList, FreeARStructItemList
status
See Also
Functions
6-65
ARGetActiveLink
Description ARGetActiveLink retrieves information about the active link with the indicated name on the specified server.
Privileges
This operation can be performed by users with access permission for the active link. Access to groupList information is limited to users with AR System administrator privileges only.
Synopsis
int ARGetActiveLink( ARControlStruct ARNameType unsigned int ARNameType ARInternalIdList unsigned int ARInternalId ARInternalId unsigned int ARQualifierStruct ARActiveLinkActionList ARActiveLinkActionList char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, name, *order, schema, *groupList, *executeMask, *controlField, *focusField, *enable, *query, *actionList, *elseList, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the active link to retrieve.
name
6-66
ARGetActiveLink
Return Values order
A value between 0 and 1000 (inclusive) that determines the active link execution order. When multiple active links are associated with a schema, the value associated with each active link determines the order in which they are processed (from lowest to highest). Specify NULL for this parameter if you do not want to retrieve the order. The name of the schema the active link is linked to. Specify NULL for this parameter if you do not want to retrieve the schema. A list of zero or more groups who can access this active link. Access to this information is limited to users with AR System administrator privileges only. Specify NULL for this parameter if you do not want to retrieve the group list. A bitmask indicating the schema operations that trigger the active link. See ARCreateActiveLink on page 6-6 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve the execute mask. associated with executing the active link. The system returns zero if the executeMask does not include the AR_EXECUTE_ON_BUTTON condition. Specify NULL for this parameter if you do not want to retrieve the control field.
schema groupList
executeMask
controlField The ID of the field that represents the button, toolbar button, or menu item
focusField
The ID of the field associated with executing the active link by pressing Return or selecting a character menu item. The system returns zero if the executeMask does not include the AR_EXECUTE_ON_RETURN or AR_EXECUTE_ON_MENU_CHOICE conditions. Specify NULL for this parameter if you do not want to retrieve the focus field. A flag identifying whether the active link is disabled (0) or enabled (1). Specify NULL for this parameter if you do not want to retrieve this flag. A qualification that determines whether the active link is executed. The system returns zero (AR_COND_OP_NONE) if the active link has no qualification. Specify NULL for this parameter if you do not want to retrieve the query. The set of actions performed if the condition defined by the query parameter is satisfied. This list can contain from 1 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the action list. The set of actions performed if the condition defined by the query parameter is not satisfied. This list can contain from 0 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the else list.
enable query
actionList
elseList
Functions
6-67
helpText
The help text associated with the active link. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). A time stamp identifying the last change to the active link. Specify NULL for this parameter if you do not want to retrieve the time stamp. The owning user for the active link. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the active link. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the active link. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateActiveLink, ARDecodeDiary, ARDeleteActiveLink, ARGetListActiveLink, ARSetActiveLink, FreeARActiveLinkActionList, FreeARInternalIdList, FreeARQualifierStruct, FreeARStatusList
timestamp owner lastChanged changeDiary
status
See Also
6-68
ARGetCharMenu
ARGetCharMenu
Description ARGetCharMenu retrieves information about the character menu with the indicated name on the specified server.
Privileges Synopsis

int ARGetCharMenu( ARControlStruct ARNameType unsigned int ARCharMenuStruct char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, name, *refreshCode, *menuDefn, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the character menu to retrieve.
name Return Values refreshCode
A value indicating when the menu is refreshed. See ARCreateCharMenu on page 6-10 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve the refresh code. The definition of the character menu. Specify NULL for this parameter if you do not want to retrieve the menu definition. The help text associated with the character menu. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists).
menuDefn helpText
Functions
6-69
A time stamp identifying the last change to the character menu. Specify NULL for this parameter if you do not want to retrieve the time stamp. The owning user for the character menu. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the character menu. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the character menu. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateCharMenu, ARDecodeDiary, ARDeleteCharMenu, ARExpandCharMenu, ARGetListCharMenu, ARSetCharMenu, FreeARCharMenuStruct, FreeARStatusList
status
See Also
6-70
ARGetContainer
ARGetContainer
Description ARGetContainer retrieves the contents of the container with the indicated name on the specified server. It can return references of a single, specified type or of all types. The system returns information for accessible references and does nothing for references for which the user does not have access.
Privileges
This operation can be performed by users with access permission for the container. Access to groupList and admingrpList information is limited to users with AR System administrator privileges only.
Synopsis
int ARGetContainer( ARControlStruct ARNameType ARReferenceTypeList ARPermissionList ARInternalIdList ARContainerOwnerObj char char unsigned int ARReferenceList char ARNameType ARTimeStamp ARNameType char ARStatusList Input Arguments control *control, name, *refTypes, *groupList, *admingrpList, *ownerObj, **label, **description, *type, *references, **helpText, owner, *timestamp, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the container to retrieve. A list of the types of references (for example, schemas and filters) to retrieve. You can specify individual types of references to retrieve or specify that all (ARREF_ALL) or none (ARREF_NONE) of the references be retrieved.
name refTypes
Functions
6-71
Return Values groupList
A list of zero or more groups who can access this container. Access to this information is limited to users with AR System administrator privileges only. Specify NULL for this parameter if you do not want to retrieve the group list. A list of zero or more groups who can administer this container (and the referenced objects). If ownerObj does not return NULL, this list is the Subadministrator group list of the owning schema. Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specify NULL for this parameter if you do not want to retrieve the administrator group list. The schema that owns this container. Specify NULL for this parameter if you do not want to retrieve the owning schema. If this parameter returns NULL, the container exists globally. The label for this container. Specify NULL for this parameter if you do not want to retrieve the label. The description for this container. Specify NULL for this parameter if you do not want to retrieve the description. The type for this container. Specify NULL for this parameter if you do not want to retrieve the type. Pointers to the objects (for example, schemas or filters) referenced by this container. Specify NULL for this parameter if you do not want to retrieve the references. The help text associated with the container. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). The owning user for the container. Specify NULL for this parameter if you do not want to retrieve the owner. A time stamp identifying the last change to the container. Specify NULL for this parameter if you do not want to retrieve the time stamp. The user who made the last change to the container. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the container. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists).
admingrpList
ownerObj
label description type references
helpText
owner timestamp lastChanged changeDiary
6-72
ARGetContainer
status
ARCreateContainer, ARDecodeDiary, ARDeleteContainer, ARGetListContainer, ARGetSchema, ARSetContainer, FreeARContainerInfoList, FreeARInternalIdList, FreeARPermissionList, FreeARReferenceList, FreeARStatusList
See Also
Functions
6-73
ARGetEntry
Description ARGetEntry retrieves the schema entry with the indicated ID on the specified server. You can retrieve data for specific fields, all (accessible) fields, or no fields (which is useful if you want to verify whether a schema has any entries). This function only returns the name, size, and compressed size of attachment fields. Use ARGetEntryBLOB to retrieve the contents of the attachment.
Privileges
The system returns data based on the access privileges of the user you specify for the control parameter. User permissions are verified for each specified field. The system returns values for accessible fields and warning messages for fields the user cannot access.
Synopsis
int ARGetEntry( ARControlStruct ARNameType AREntryIdList ARInternalIdList ARFieldValueList ARStatusList Input Arguments control *control, schema, *entryId, *idList, *fieldList, *status)
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, sessionId, and server fields are required. The name of the schema containing the entry to retrieve. The ID of the entry to retrieve. Note: The system identifies entries in join schemas by concatenating the entry IDs from the member schemas. As a result, an entry ID can consist of one or more values of type AREntryIdType and, therefore, is represented by using the AREntryIdList structure.
schema entryId
6-74
ARGetEntry
idList
A list of zero or more internal IDs specifying the fields to retrieve. Specify NULL for this parameter (or zero fields) to retrieve all (accessible) fields. Specify NULL for both this parameter and the fieldList parameter if you do not want to retrieve any fields. To minimize network traffic, specify only the fields you need if you do not require the data for all fields. If an attachment field is specified in the list, only its name, size, and compressed size will be returned. Use ARGetEntryBLOB to retrieve the contents of the attachment.
Return Values fieldList
A list of zero or more field/value pairs that identifies the data for the specified entry. The fields are returned in the order specified by idList. If the user does not have permission for a specified field or the field does not exist, the system returns zero/NULL for the field/value pair. Specify NULL for this parameter if you do not want to retrieve any field data. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateEntry, ARDecodeDiary, ARDecodeStatusHistory, ARDeleteEntry, ARGetEntryBLOB, ARGetListEntry, ARSetEntry, FreeAREntryIdList, FreeARInternalIdList, FreeARFieldValueList, FreeARStatusList
status
See Also
Functions
6-75
ARGetEntryBLOB
Description ARGetEntryBLOB retrieves the attachment, or binary large object (BLOB), stored for the attachment field with the indicated ID on the specified server. The BLOB can be placed in a buffer or a file.
Privileges
The system returns data based on the access privileges of the user you specify for the control parameter. User permissions are verified for the specified field. If the user cannot access the field, the system returns an error message.
Synopsis
int ARGetEntryBLOB( ARControlStruct ARNameType AREntryIdList ARInternalId ARLocStruct ARStatusList Input Arguments control *control, schema, *entryId, id, *loc, *status)
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, sessionId, and server fields are required. The name of the schema containing the entry to retrieve. The ID of the entry to retrieve. Note: The system identifies entries in join schemas by concatenating the entry IDs from the member schemas. As a result, an entry ID can consist of one or more values of type AREntryIdType and, therefore, is represented by using the AREntryIdList structure.
schema entryId
id loc
The ID specifying the field to retrieve. A pointer to an ARLocStruct structure specifying how you want the contents of the BLOB returned: in a file (AR_LOC_FD) or a data buffer (AR_LOC_BUF). The structure also contains the name of the file or buffer to be used.
6-76
ARGetEntryBLOB
ARGetEntry, ARCreateEntry, ARDecodeDiary, ARDecodeStatusHistory, ARDeleteEntry, ARGetListEntry, ARSetEntry, FreeAREntryIdList, FreeARInternalIdList, FreeARFieldValueList, FreeARStatusList
See Also
Functions
6-77
ARGetEntryStatistics
Description ARGetEntryStatistics computes the indicated statistic for the schema entries that match the conditions specified by the qualifier parameter.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All statistics, therefore, are limited to entries the user can access (users must have permission for the entryId field to access and retrieve entries).
Synopsis
int ARGetEntryStatistics( ARControlStruct ARNameType ARQualifierStruct ARFieldValueOrArithStruct unsigned int ARInternalIdList ARStatisticsResultList ARStatusList Input Arguments control *control, schema, *qualifier, *target, statistic, *groupByList, *results, *status)
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, sessionId, and server fields are required. The name of the schema to compute entry statistics for. A query that determines the set of entries to use. The qualification can include one or more fields and any combination of conditional, relational, and arithmetic (numeric data types only) operations. The system generates an error if the user does not have read permission for a field or a field does not exist. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to match all schema entries. The arithmetic operation that defines the statistic to compute. The statistic can include one or more fields and any combination of arithmetic operations. The system generates an error if the user does not have read permission for a
schema qualifier
target
6-78
ARGetEntryStatistics
field or a field does not exist. If you specify AR_STAT_OP_COUNT for the statistic parameter, assign a tag value of 0 to omit this parameter.
statistic
A value indicating the statistic type.

1: 2: 3: 4: 5:
The total number of matching entries (AR_STAT_OP_COUNT). The sum of values for each group (AR_STAT_OP_SUM). The average value for each group (AR_STAT_OP_AVERAGE). The minimum value for each group (AR_STAT_OP_MINIMUM). The maximum value for each group (AR_STAT_OP_MAXIMUM).
groupByList
A list of zero or more fields to group the results by. The system computes a result for each group of entries having the same value in the specified field. Specifying more than one field creates groups within groups, each of which returns a separate statistic. Specify NULL for this parameter (or zero fields) to compute a single result for all matching entries.
Return Values results
A list of zero or more results. If you specify one or more fields for the groupByList parameter, each item in the list represents a group. Each result structure contains the field values that define the group and the statistic for that group. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateEntry, ARDeleteEntry, ARGetEntry, ARGetListEntry, ARLoadARQualifierStruct, ARMergeEntry, ARSetEntry, FreeARFieldValueOrArithStruct, FreeARInternalIdList, FreeARQualifierStruct, FreeARStatisticsResultList, FreeARStatusList
status
See Also
Functions
6-79
ARGetEscalation
Description ARGetEscalation retrieves information about the escalation with the indicated name on the specified server.
Privileges
Synopsis
int ARGetEscalation( ARControlStruct ARNameType AREscalationTmStruct ARNameType unsigned int ARQualifierStruct ARFilterActionList ARFilterActionList char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, name, *escalationTm, schema, *enable, *query, *actionList, *elseList, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the escalation to retrieve.
name Return Values

escalationTm
The time specification for evaluating the escalation condition. This parameter can take one of two forms: a time interval that defines how frequently the server checks the escalation condition (in seconds) or a bitmask that defines a particular day (by month or week) and time (hour and minute) for the server to check the condition. Specify NULL for this parameter if you do not want to retrieve the escalation time.
6-80
ARGetEscalation
schema enable query
The name of the schema the escalation is linked to. Specify NULL for this parameter if you do not want to retrieve the schema. A flag identifying whether the escalation is disabled (0) or enabled (1). Specify NULL for this parameter if you do not want to retrieve this flag. A query operation performed when the escalation is executed that determines the set of entries to which the escalation actions (defined by the actionList parameter) are applied. The system returns 0 (AR_COND_OP_NONE) if the escalation has no qualification. Specify NULL for this parameter if you do not want to retrieve the query. The set of actions performed for each entry that matches the criteria defined by the query parameter. This list can contain from 1 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the action list. The set of actions performed if no entries match the criteria defined by the query parameter. This list can contain from zero to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the else list. The help text associated with the escalation. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). A time stamp identifying the last change to the escalation. Specify NULL for this parameter if you do not want to retrieve the time stamp. The owning user for the escalation. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the escalation. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the escalation. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateEscalation, ARDecodeDiary, ARDeleteEscalation, ARGetListEscalation, ARSetEscalation, FreeARFilterActionList, FreeARQualifierStruct, FreeARStatusList
actionList
elseList
helpText
status
See Also
Functions
6-81
ARGetField
Description ARGetField retrieves information about the schema field with the indicated ID on the specified server.
Privileges
This operation can be performed by users with access permission for the fields parent schema. Access to permissions information is limited to users with AR System administrator privileges only.
Synopsis
int ARGetField( ARControlStruct ARNameType ARInternalId ARNameType ARFieldMappingStruct unsigned int unsigned int unsigned int ARValueStruct ARPermissionList ARFieldLimitStruct ARDisplayInstanceList char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, schema, fieldId, fieldName, *fieldMap, *dataType, *option, *createMode, *defaultVal, *permissions, *limit, *dInstanceList, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema containing the field to retrieve. The internal ID of the field to retrieve.
schema fieldId
6-82
ARGetField
Return Values fieldName fieldMap
The name of the field. Specify NULL for this parameter if you do not want to retrieve the field name. The underlying schema that contains the field (applicable for join schemas only). Specify NULL for this parameter if you do not want to retrieve the field mapping. The data type of the field. See ARCreateField on page 6-19 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve the data type. A flag indicating whether users must enter a value in the field. See ARCreateField on page 6-19 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve this flag. A flag indicating the permission status for the field when users submit entries. See ARCreateField on page 6-19 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve this flag. The value to apply if a user submits an entry with no field value (applicable for data fields only). The system returns 0 (AR_DEFAULT_VALUE_NONE) if the field has no default. Specify NULL for this parameter if you do not want to retrieve the default value. A list of zero or more groups who can access this field. Access to this information is limited to users with AR System administrator privileges only. Specify NULL for this parameter if you do not want to retrieve the permissions. The value limits for the field and other properties specific to the fields type. See the ARFieldLimitStruct definition in ar.h to find the contained structure that applies to the type of field you are creating. Specify NULL (or AR_FIELD_LIMIT_NONE) for trim and control fields or if you do not want to retrieve the limits and properties. A list of zero or more display properties associated with the field. See ARCreateField on page 6-19 for a description of the possible values. The system returns 0 (AR_DPROP_NONE) if the field has no display properties. Specify NULL for this parameter if you do not want to retrieve this list. The help text associated with the field. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). A time stamp identifying the last change to the field. Specify NULL for this parameter if you do not want to retrieve the time stamp.
dataType
option
createMode
defaultVal
permissions
limit
dInstanceList
helpText
timestamp
Functions
6-83
owner lastChanged changeDiary
The owning user for the field. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the field. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the field. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateField, ARDecodeDiary, ARDeleteField, ARGetSchema, ARGetListField, ARSetField, FreeARDisplayInstanceList, FreeARFieldLimitStruct, FreeARPermissionList, FreeARStatusList, FreeARValueStruct
status
See Also
6-84
ARGetFilter
ARGetFilter
Description ARGetFilter retrieves information about the specified filter on the specified
server.
Privileges
Synopsis
int ARGetFilter( ARControlStruct ARNameType unsigned int ARNameType unsigned int unsigned int ARQualifierStruct ARFilterActionList ARFilterActionList char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, name, *order, schema, *opSet, *enable, *query, *actionList, *elseList, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the filter to retrieve.
name Return Values order
A value between 0 and 1000 (inclusive) that determines the filter execution order. When multiple filters are associated with a schema, the value associated with each filter determines the order in which they are processed (from lowest to highest). Specify NULL for this parameter if you do not want to retrieve the order.
Functions
6-85
schema opSet
The name of the schema the filter is linked to. Specify NULL for this parameter if you do not want to retrieve the schema. A bitmask indicating the schema operations that trigger the filter. See ARCreateFilter on page 6-33 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve the operation set. A flag identifying whether the filter is disabled (0) or enabled (1). Specify NULL for this parameter if you do not want to retrieve this flag. A qualification that determines whether the filter is executed. The system returns 0 (AR_COND_OP_NONE) if the filter has no qualification. Specify NULL for this parameter if you do not want to retrieve the query. The set of actions performed if the condition defined by the query parameter is satisfied. This list can contain from 1 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the action list. The set of actions performed if the condition defined by the query parameter is not satisfied. This list can contain from 0 to 25 actions (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to retrieve the else list. The help text associated with the filter. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). A time stamp identifying the last change to the filter. Specify NULL for this parameter if you do not want to retrieve the time stamp. The owning user for the filter. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the filter. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the filter. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
enable query
actionList
elseList
helpText
status
6-86
ARGetFilter
See Also
ARCreateFilter, ARDecodeDiary, ARDeleteFilter, ARGetListFilter, ARSetFilter, FreeARFilterActionList, FreeARQualifierStruct, FreeARStatusList
Functions
6-87
ARGetFullTextInfo
Description ARGetFullTextInfo retrieves the requested Full Text Search (FTS) information for the specified server.
Privileges Synopsis

#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARGetFullTextInfo( ARControlStruct ARFullTextInfoRequestList ARFullTextInfoList ARStatusList *control, *requestList, *fullTextInfo, *status)
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, sessionId, and server fields are required. A list of one or more FTS options to return (see FTS Options below).
requestList Return Values

fullTextInfo
The information retrieved from the server (see FTS Options below). The system returns NULL (data type value of AR_DATA_TYPE_NULL) for FTS options not retrieved due to error. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
status
FTS Options AR_FULLTEXTINFO_CASE_SENSITIVE_SRCH:
A value indicating whether full text searches are case-sensitive. Valid values for this option are 0 (case-sensitive) and 1 (case-insensitive). The default value is 1 (case-insensitive).
AR_FULLTEXTINFO_COLLECTION_DIR:
The collection directory for the FTS engine. This directory contains all defined FTS indexes. This directory is not used if no fields are indexed for FTS.
6-88
ARGetFullTextInfo
AR_FULLTEXTINFO_FTS_MATCH_OP:
A value indicating the type of match operation used.

0:
1:
2: 3:
4:
Append leading and trailing wild cards to every word. This option produces the highest number of matches but slows performance the most (AR_FULLTEXT_FTS_MATCH_FORCE_L_T_WILD). Truncate all leading wild cards and append trailing wild cards to every word. This option produces a reasonable number of matches while still being efficient (AR_FULLTEXT_FTS_MATCH_FORCE_T_WILD). Truncate all leading wild cards (do not truncate or append trailing wild cards) (AR_FULLTEXT_FTS_MATCH_IGNORE_L_WILD). Truncate all wild cards. This option is the most efficient match operation type but produces the lowest number of matches (AR_FULLTEXT_FTS_MATCH_REMOVE_WILD). Leave all wild cards as specified by the user. This option requires that users understand both how to use wild cards and their impact on performance (AR_FULLTEXT_FTS_MATCH_UNCHANGED).
AR_FULLTEXTINFO_STATE:
A value indicating whether FTS is enabled. Valid values for this option are 0 (off) and 1 (on). The default value is 1 (FTS on).
AR_FULLTEXTINFO_STOPWORD:
A structure that contains all defined words to ignore for the FTS collection.
See Also ARGetServerInfo, ARGetServerStatistics, ARSetFullTextInfo, ARSetServerInfo, FreeARFullTextInfoList, FreeARFullTextInfoRequestList, FreeARStatusList
Functions
6-89
ARGetListActiveLink
Description ARGetListActiveLink retrieves a list of active links on the specified server. You can retrieve all (accessible) active links or limit the list to active links associated with a particular schema or modified after a specified time.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All lists, therefore, are limited to active links the user can access.
Synopsis
int ARGetListActiveLink( ARControlStruct ARNameType ARTimestamp ARNameList ARStatusList Input Arguments control *control, schema, changedSince, *nameList, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve active links for. Specify NULL for this parameter if you want to retrieve active links for all schemas. specified time. Specify 0 for this parameter if you want to retrieve active links with any modification time stamp.
schema
changedSince A time stamp that limits the active links retrieved to those modified after the
Return Values nameList
A list of zero or more (accessible) active links that match the criteria defined by the schema and changedSince parameters. The system returns a list with zero items if no active links match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
status
6-90
ARGetListActiveLink
See Also
ARCreateActiveLink, ARDeleteActiveLink, ARDeleteSchema, ARGetActiveLink, ARSetActiveLink, FreeARNameList, FreeARStatusList
Functions
6-91
ARGetListCharMenu
Description ARGetListCharMenu retrieves a list of character menus on the specified server. You can retrieve all character menus or limit the list to character menus modified after a specified time.
Privileges Synopsis

int ARGetListCharMenu( ARControlStruct ARTimestamp ARNameList ARStatusList Input Arguments control *control, changedSince, *nameList, *status)
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, sessionId, and server fields are required. the specified time. Specify 0 for this parameter if you want to retrieve character menus with any modification time stamp.
changedSince A time stamp that limits the character menus retrieved to those modified after
A list of zero or more character menus that match the criteria defined by the changedSince parameter. The system returns a list with zero items if no character menus match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateCharMenu, ARDeleteCharMenu, ARExpandCharMenu, ARGetCharMenu, ARSetCharMenu, FreeARNameList, FreeARStatusList
status
See Also
6-92
ARGetListContainer
ARGetListContainer
Description ARGetListContainer retrieves a list of containers on the specified server. You can retrieve all (accessible) containers or limit the list to containers of a particular type, containers owned by a specified schema, or containers modified after a specified time.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All lists, therefore, are limited to containers the user can access.
Synopsis
int ARGetListContainer( ARControlStruct ARTimestamp ARContainerTypeList unsigned int ARContainerOwnerObj ARContainerInfoList ARStatusList Input Arguments control *control, changedSince, containerTypes, attributes, *ownerObj, *conList, *status)
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, sessionId, and server fields are required. specified time. Specify 0 for this parameter if you want to retrieve containers with any modification time stamp.
changedSince A time stamp that limits the containers retrieved to those modified after the
containerTypes
A list of values indicating the container types to retrieve.

0: 1: 2:
Retrieve all container types (ARCON_ALL). Retrieve all guide containers (ARCON_GUIDE). Retrieve all application containers (ARCON_APP).
attributes
Specify AR_HIDDEN_INCREMENT for this parameter to retrieve both visible and hidden containers. Specify NULL for this parameter to retrieve only visible containers.
Functions
6-93
ownerObj
A structure that limits the containers retrieved based on the object that owns them.
0: 1: 2:
Retrieve all globally-owned containers (ARCONOWNER_NONE). Retrieve all containers (ARCONOWNER_ALL). Retrieve all containers owned by the specified schema (ARCONOWNER_SCHEMA).
Return Values conList
A list of zero or more (accessible) containers that match the criteria defined by the containerTypes, ownerObj, and changedSince parameters. The system returns a list with zero items if no containers match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateContainer, ARDeleteContainer, ARGetContainer, ARGetListSchema, ARSetContainer, FreeARNameList, FreeARStatusList
status
See Also
6-94
ARGetListEntry
ARGetListEntry
Description ARGetListEntry retrieves a list of schema entries on the specified server. Data from each entry is returned as a string containing the concatenated values of selected fields. You can limit the list to entries that match particular conditions by specifying the qualifier parameter. ARGetListEntryWithFields also returns a qualified list of entries, but as field/value pairs.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All lists, therefore, are limited to entries the user can access (users must have permission for the entryId field to access and retrieve entries).
Synopsis
int ARGetListEntry( ARControlStruct ARNameType ARQualifierStruct AREntryListFieldList ARSortList unsigned int AREntryListList unsigned int ARStatusList Input Arguments control *control, schema, *qualifier, *getListFields, *sortList, maxRetrieve, *entryList, *numMatches, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve entries for. A query that determines the set of entries to retrieve. The qualification can include one or more fields and any combination of conditional, relational, and arithmetic (numeric data types only) operations. The system generates an error if the user does not have read permission for a field or a field does not exist. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to match all schema entries.
schema qualifier
Functions
6-95
getListFields
A list of zero or more fields that identifies the data to display in the query list. The list can include any data fields except diary fields and long character fields. The system checks the permissions for each specified field and returns only those fields for which you have read access. The combined length of all specified fields, including separator characters, can be as many as 128 bytes (limited by AR_MAX_SDESC_SIZE). Specify NULL for this parameter (or zero fields) to return the default query list data for the schema (see ARCreateSchema on page 6-35). The system returns the Short-Description core field if the schema has no default query list data. A list of zero or more fields that identifies the entry sort order. The system generates an error if you do not have read access on all specified fields. Specify NULL for this parameter (or zero fields) to use the default sort order for the schema (see ARCreateSchema on page 6-35). The system sorts the entries in ascending order by entryId if the schema has no default sort order. The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the qualification does not sufficiently narrow the list. Specify 0 (AR_NO_MAX_LIST_RETRIEVE) to assign no maximum.
sortList
maxRetrieve
Return Values entryList
A list of zero or more (accessible) entries that match the criteria defined by the qualifier parameter. The system returns a list with zero items if no entries match the specified criteria. The total number of (accessible) entries that match the qualification criteria. This value does not represent the number of entries returned unless the number of matching entries is less than or equal to the maxRetrieve value. Specify NULL for this parameter if you do not want to retrieve this count. Note: Performing this count requires additional search time if the number of matching entries is more than the maxRetrieve value. In this case, the cost of completing the search diminishes the performance benefits of retrieving fewer entries.
numMatches
status
ARGetListEntryWithFields, ARCreateEntry, ARDeleteEntry, ARGetEntry, ARGetEntryStatistics, ARLoadARQualifierStruct, ARMergeEntry, ARSetEntry, FreeAREntryListFieldList, FreeAREntryListList, FreeARQualifierStruct, FreeARSortList, FreeARStatusList
See Also
6-96
ARGetListEntryWithFields
Description ARGetListEntryWithFields retrieves a list of schema entries on the specified server. Data from each entry is returned as field/value pairs for all fields. You can limit the list to entries that match particular conditions by specifying the qualifier parameter. ARGetListEntry also returns a qualified list of entries, but as a string for each entry containing the concatenated values of selected fields.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All lists, therefore, are limited to entries the user can access (users must have permission for the entryId field to access and retrieve entries).
Synopsis
int ARGetListEntryWithFields( ARControlStruct ARNameType ARQualifierStruct AREntryListFieldList ARSortList unsigned int AREntryListFieldValueList unsigned int ARStatusList Input Arguments control *control, schema, *qualifier, *getListFields, *sortList, maxRetrieve, *entryList, *numMatches, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve entries for. A query that determines the set of entries to retrieve. The qualification can include one or more fields and any combination of conditional, relational, and arithmetic (numeric data types only) operations. The system generates an error if the user does not have read permission for a field or a field does not exist. Specify NULL or assign an operation value of 0 (AR_COND_OP_NONE) to match all schema entries.
schema qualifier
Functions
6-97
getListFields
A list of zero or more fields to be retrieved with each entry. The system checks the permissions for each specified field and returns only those fields for which you have read access. A list of zero or more fields that identifies the entry sort order. The system generates an error if you do not have read access on all specified fields. Specify NULL for this parameter (or zero fields) to use the default sort order for the schema (see ARCreateSchema on page 6-35). The system sorts the entries in ascending order by entryId if the schema has no default sort order. The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the qualification does not sufficiently narrow the list. Specify 0 (AR_NO_MAX_LIST_RETRIEVE) to assign no maximum.
sortList
maxRetrieve
Return Values entryList
A list of zero or more (accessible) entries that match the criteria defined by the qualifier parameter. The system returns a list with zero items if no entries match the specified criteria. The total number of (accessible) entries that match the qualification criteria. This value does not represent the number of entries returned unless the number of matching entries is less than or equal to the maxRetrieve value. Specify NULL for this parameter if you do not want to retrieve this count. Note: Performing this count requires additional search time if the number of matching entries is more than the maxRetrieve value. In this case, the cost of completing the search diminishes the performance benefits of retrieving fewer entries.
numMatches
status
ARGetListEntry, ARCreateEntry, ARDeleteEntry, ARGetEntry, ARGetEntryStatistics, ARLoadARQualifierStruct, ARMergeEntry, ARSetEntry, FreeAREntryListFieldList, FreeAREntryListList, FreeARQualifierStruct, FreeARSortList, FreeARStatusList
See Also
6-98
ARGetListEscalation
ARGetListEscalation
Description ARGetListEscalation retrieves a list of escalations on the specified server. You can retrieve all escalations or limit the list to escalations associated with a particular schema or that are set to be executed before a specified time.
Privileges
Synopsis
int ARGetListEscalation( ARControlStruct ARNameType ARTimestamp ARNameList ARStatusList Input Arguments control *control, schema, changedSince, *nameList, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve escalations for. Specify NULL for this parameter if you want to retrieve escalations for all schemas. before the specified time. Specify 0 for this parameter if you want to retrieve escalations with any time specification.
schema
changedSince A time stamp that limits the escalations retrieved to those set to be executed
A list of zero or more escalations that match the criteria defined by the schema and changedSince parameters. The system returns a list with zero items if no escalations match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateEscalation, ARDeleteEscalation, ARDeleteSchema, ARGetEscalation, ARSetEscalation, FreeARNameList, FreeARStatusList
status
See Also
Functions
6-99
ARGetListField
Description ARGetListField retrieves a list of fields for a particular schema on the specified server. You can retrieve all fields or limit the list to fields of a particular type or fields modified after a specified time.
Privileges
This operation can be performed by users with access permission for the specified schema.
Synopsis
int ARGetListField( ARControlStruct ARNameType unsigned long ARTimestamp ARInternalIdList ARStatusList Input Arguments control *control, schema, fieldType, changedSince, *idList, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve fields for. A bitmask indicating the field types to retrieve.
Bit 0: Bit 1: Bit 2: Bit 3: Bit 4: Bit 5: Bit 6:
schema fieldType
Retrieve data fields (AR_FIELD_TYPE_DATA). Retrieve trim fields (AR_FIELD_TYPE_TRIM). Retrieve control fields (AR_FIELD_TYPE_CONTROL). Retrieve page fields (AR_FIELD_TYPE_PAGE). Retrieve page holder fields (AR_FIELD_TYPE_PAGE_HOLDER). Retrieve table fields (AR_FIELD_TYPE_TABLE). Retrieve column fields (AR_FIELD_TYPE_COLUMN).
changedSince A time stamp that limits the fields retrieved to those modified after the
specified time. Specify 0 for this parameter if you want to retrieve fields with any modification time stamp.
6-100
ARGetListField
Return Values idList
A list of zero or more fields that match the criteria defined by the fieldType and changedSince parameters. The system returns a list with zero items if no fields match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateField, ARDeleteField, ARGetField, ARSetField, FreeARInternalIdList, FreeARStatusList
status
See Also
Functions 6-101
ARGetListFilter
Description ARGetListFilter retrieves a list of filters on the specified server. You can retrieve all filters or limit the list to filters associated with a particular schema or modified after a specified time.
Privileges
Synopsis
int ARGetListFilter( ARControlStruct ARNameType ARTimestamp ARNameList ARStatusList Input Arguments control *control, schema, changedSince, *nameList, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve filters for. Specify NULL for this parameter if you want to retrieve filters for all schemas. specified time. Specify 0 for this parameter if you want to retrieve filters with any modification time stamp.
schema
changedSince A time stamp that limits the filters retrieved to those modified after the
A list of zero or more filters that match the criteria defined by the schema and changedSince parameters. The system returns a list with zero items if no filters match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateFilter, ARDeleteFilter, ARDeleteSchema, ARGetFilter, ARSetFilter, FreeARNameList, FreeARStatusList
status
See Also
6-102
ARGetListGroup
ARGetListGroup
Description ARGetListGroup retrieves a list of access control groups on the specified server. You can retrieve all groups or limit the list to groups associated with a particular user.
Privileges
Group information for the current user can be retrieved by all users. Access to group information for other users is limited to users with AR System administrator privileges only.
Synopsis
int ARGetListGroup( ARControlStruct ARNameType ARGroupInfoList ARStatusList Input Arguments control *control, *userName, *groupList, *status)
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, sessionId, and server fields are required. The name of the user to retrieve group information for. Specify NULL for this parameter if you want to retrieve all groups on the server.
userName
Return Values groupList
A list of zero or more groups that match the criteria defined by the userName parameter. The list contains each group ID and group name. The system returns a list with zero items if no groups match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARGetListUser, FreeARGroupInfoList, FreeARStatusList
status
See Also
Functions 6-103
ARGetListSchema
Description ARGetListSchema retrieves a list of schemas on the specified server. You can retrieve all (accessible) schemas or limit the list to schemas of a particular type or schemas modified after a specified time.
Privileges
The system returns information based on the access privileges of the user you specify for the control parameter. All lists, therefore, are limited to schemas the user can access.
Synopsis
int ARGetListSchema( ARControlStruct ARTimestamp unsigned int ARNameType ARNameList ARStatusList Input Arguments control *control, changedSince, schemaType, name, *nameList, *status)
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, sessionId, and server fields are required. specified time. Specify 0 for this parameter if you want to retrieve schemas with any modification time stamp.
changedSince A time stamp that limits the schemas retrieved to those modified after the
6-104
ARGetListSchema
schemaType
A value indicating the schema types to retrieve (some types are mutually exclusive).
0: 1: 2: 4:
5:
6: 7:
Retrieve all schema types (AR_LIST_SCHEMA_ALL). Retrieve all base schemas (AR_LIST_SCHEMA_REGULAR). Retrieve all join schemas (AR_LIST_SCHEMA_JOIN). Retrieve all join schemas that depend on the schema specified by the name parameter (AR_LIST_SCHEMA_UPLINK). Retrieve all base or join schemas that the schema specified by the name parameter depends on (AR_LIST_SCHEMA_DOWNLINK). Retrieve all display-only schemas (AR_LIST_SCHEMA_DIALOG) Retrieve all schemas with data fields (AR_LIST_SCHEMA_ALL_WITH_DATA)
To retrieve both visible and hidden schemas, add 1024 (AR_HIDDEN_INCREMENT) to the schema type. For example, specify AR_LIST_SCHEMA_ALL | AR_HIDDEN_INCREMENT for this parameter.
name
If the schemaType is AR_LIST_SCHEMA_UPLINK, this parameter specifies the schema upon which the retrieved schemas depend. If the schemaType is AR_LIST_SCHEMA_DOWNLINK, this parameter specifies the schema that depends on the retrieved schemas. This parameter is ignored if you do not specify AR_LIST_SCHEMA_UPLINK or AR_LIST_SCHEMA_DOWNLINK as the schemaType.
A list of zero or more (accessible) schemas that match the criteria defined by the schemaType and changedSince parameters. The system returns a list with zero items if no schemas match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateSchema, ARDeleteSchema, ARGetSchema, ARSetSchema, FreeARNameList, FreeARStatusList
status
See Also
Functions 6-105
ARGetListServer
Description ARGetListServer retrieves the list of available AR System servers defined in the ar directory file (UNIX only). Remedy User, Remedy Administrator, Remedy Notifier, and Remedy Import connect to these servers automatically if no servers are specified at startup. If the ar file is under NIS control, the system uses the file specified by the NIS map instead of the local ar file. For information about the ar file, see the Action Request System Administrators Guide, Volume 2.
Note:
In the Windows NT API, server information is retrieved from the registry instead of the ar file. API programs that run on the server (for example, through a filter or escalation) can use this function to retrieve the name of that local server only. Programs that run on a Windows client, however, cannot. In this case, the function always returns a list of zero servers.
Privileges Synopsis

#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARGetListServer( ARControlStruct ARServerNameList ARStatusList *control, *serverList, *status)
Return Values serverList
A list of zero or more registered AR System servers. The system returns a list with zero items if no AR System servers are registered.
6-106
ARGetListServer
status
ar directory file, FreeARServerNameList, FreeARStatusList
See Also
Functions 6-107
ARGetListSQL
Description ARGetListSQL retrieves a list of rows from the underlying SQL database on the specified server. The server executes the SQL command you specify and returns the matching rows. A list with zero items and a warning message are returned if no SQL database resides on the server. The system returns information based on the access privileges of the user who launched the AR System server.
Privileges
Synopsis
int ARGetListSQL( ARControlStruct char unsigned int ARValueListList unsigned int ARStatusList Input Arguments control *control, *sqlCommand, maxRetrieve, *valueListList, *numMatches, *status)
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, sessionId, and server fields are required. The SQL command to execute (following the syntax rules for the underlying database). The owner of the AR System server process must have permission to perform the specified SQL operation. The maximum number of rows to retrieve. Use this parameter to limit the amount of data returned if the SQL query does not sufficiently narrow the list. Specify 0 (AR_NO_MAX_LIST_RETRIEVE) to assign no maximum.
sqlCommand
maxRetrieve
Return Values
valueListList
A list of zero or more (accessible) rows that match the criteria defined by the sqlCommand parameter. Each item in the list represents one matching row,
6-108
ARGetListSQL
each of which contains a list of the selected column values. The system returns a list with zero items if no rows match the specified criteria.
numMatches
The total number of (accessible) rows that match the SQL selection criteria. This value does not represent the number of rows returned unless the number of matching rows is less than or equal to the maxRetrieve value. Specify NULL for this parameter if you do not want to retrieve this count. Note: Performing this count requires additional search time if the number of matching rows is more than the maxRetrieve value. In this case, the cost of completing the search diminishes the performance benefits of retrieving fewer rows.
status
ARExecuteProcess, ARGetListEntry, FreeARStatusList, FreeARValueListList
See Also
Functions 6-109
ARGetListSupportFile
Description ARGetListSupportFile retrieves a list of support file IDs for a specified type
of object.
Privileges
This operation can be performed by any user who has access to the specified object.
Synopsis
int ARGetListSupportFile( ARControlStruct unsigned int ARNameType ARInternalId ARInternalId ARTimeStamp ARInternalIdList ARStatusList Input Arguments control *control, fileType name, fieldId, fileId, changedSince, *fileIdList, *status)
The control record for the operation. It contains information about the user requesting the operation and where that operation is to be performed. The user and server fields are required. The numerical value for the type of file, and the type of object the file is related to. Specify 1 (AR_SUPPORT_FILE_EXTERNAL_REPORT) for an external report file associated with an active link. The name of the object the file is associated with, usually a schema. The ID of the field or VUI, if the object is a schema. If the object is not a schema, set this parameter to 0. The unique identifier of a file within its object. time. Specify 0 for this parameter if you want to retrieve all IDs.
fileType
name fieldId fileId
changedSince A time stamp that limits the IDs retrieved to those modified after the specified fileIdList
A list of support file IDs linked to an object.
6-110
ARGetListSupportFile
ARCreateActiveLink, ARCreateSupportFile, ARDeleteActiveLink, ARDeleteSupportFile, ARGetActiveLink, ARGetSupportFile, ARSetActiveLink, ARSetSupportFile
See Also
Functions 6-111
ARGetListUser
Description ARGetListUser retrieves a list of users on the specified AR System server. You can retrieve information about the current user, all registered users, or all users currently accessing the server.
Privileges
Information about the current user can be retrieved by all users. Access to information about other users is limited to users with AR System administrator privileges only.
Synopsis
int ARGetListUser( ARControlStruct unsigned int ARUserInfoList ARStatusList Input Arguments control *control, userListType, *userList, *status)
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, sessionId, and server fields are required. A value indicating the user type to retrieve.
0: 1: 2:
userListType
Retrieve the current user (AR_USER_LIST_MYSELF). Retrieve all registered users (AR_USER_LIST_REGISTERED). Retrieve all users currently accessing the server (AR_USER_LIST_CURRENT).
Return Values userList
A list of zero or more users that match the criteria defined by the userListType parameter. The list contains the user name and license type. If you retrieve the current user, the list also contains a time stamp identifying the last server access. The system returns a list with zero items if no users match the specified criteria.
6-112
ARGetListUser
status
ARGetListGroup, FreeARUserInfoList, FreeARStatusList
See Also
Functions 6-113
ARGetListVUI
Description ARGetListVUI retrieves a list of schema views (VUI) for a particular schema on the specified server. You can retrieve all views or limit the list to views modified after a specified time.
Privileges
This operation can be performed by users with access permission for the specified schema.
Synopsis
int ARGetListVUI( ARControlStruct ARNameType ARTimestamp ARInternalIdList ARStatusList Input Arguments control *control, schema, changedSince, *idList, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve views for. specified time. Specify 0 for this parameter if you want to retrieve views with any modification time stamp.
schema
changedSince A time stamp that limits the views retrieved to those modified after the
Return Values idList
A list of zero or more view IDs that match the criteria defined by the changedSince parameter. The system returns a list with zero items if no views match the specified criteria. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateVUI, ARDeleteVUI, ARGetVUI, ARSetVUI, FreeARInternalIdList, FreeARStatusList
status
See Also
6-114
ARGetMultipleEntries
ARGetMultipleEntries
Description ARGetMultipleEntries retrieves the group of schema entries specified by the entryIdList parameter. You can retrieve data for specific fields or all
(accessible) fields. This function only returns the name, size, and compressed size of attachment fields. Use ARGetEntryBLOB to retrieve the contents of the attachment. This function performs the same action as ARGetEntry but is easier and more efficient than retrieving multiple entries one by one.
Privileges
The system returns data based on the access privileges of the user you specify for the control parameter. User permissions are verified for each specified entry and field. The system returns values for accessible fields and warning messages for fields the user cannot access.
Synopsis
int ARGetMultipleEntries( ARControlStruct ARNameType AREntryIdListList ARInternalIdList ARBooleanList ARFieldValueListList ARStatusList Input Arguments control *control, schema, entryIdList, *fieldIdList, *existList, *fieldList, *status)
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, sessionId, and server fields are required. The name of the schema containing the entries to retrieve. The list of zero or more entries to retrieve. A list of zero or more internal IDs specifying the fields to retrieve. Specify NULL for this parameter (or zero fields) to retrieve all (accessible) fields. To improve performance, specify only the fields you need if you do not require the data for all fields. If an attachment field is specified in the list, only its name, size, and compressed size will be returned. Use ARGetEntryBLOB to retrieve the contents of the attachment.
schema entryIdList fieldIdList
Functions 6-115
Return Values existList fieldList
A list of flags indicating whether the entries exist. If the value of a flag is True, the entry exists. A list of zero or more fields and associated values that identify the data for the specified entries. The fields are returned in the order specified by fieldIdList. If a specified entry does not exist, the system returns zero (or NULL) for that entry. If the user does not have permission for a specified field or the field does not exist, the system returns NULL for the associated value within each entry value list. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateEntry, ARDecodeDiary, ARDecodeStatusHistory, ARDeleteEntry, ARGetEntry, ARGetListEntry, ARSetEntry, FreeARBooleanList, FreeAREntryIdList, FreeARInternalIdList, FreeARStatusList
status
See Also
6-116
ARGetSchema
ARGetSchema
Description ARGetSchema retrieves information about the schema with the indicated name on the specified server. This information does not include the schemas field definitions (see ARGetField on page 6-82).
Privileges
This operation can be performed by users with access permission for the schema. Access to groupList and admingrpList information is limited to users with AR System administrator privileges only.
Synopsis
int ARGetSchema( ARControlStruct ARNameType ARCompoundSchema ARPermissionList ARInternalIdList AREntryListFieldList ARSortList ARIndexList char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, name, *schema, *groupList, *admingrpList, *getListFields, *sortList, *indexList, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema to retrieve.
name Return Values schema
The schema type (base schema or join schema). See ARCreateSchema on page 6-35 for a description of the possible values. Specify NULL for this parameter if you do not want to retrieve the schema type.
Functions 6-117
groupList
A list of zero or more groups who can access this schema. Access to this information is limited to users with AR System administrator privileges only. Specify NULL for this parameter if you do not want to retrieve the group list. A list of zero or more groups who can administer this schema (and the associated filters, escalations, and active links). Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specify NULL for this parameter if you do not want to retrieve the administrator group list. A list of zero or more fields that identifies the default query list data for retrieving schema entries. Specify NULL for this parameter if you do not want to retrieve the default query list fields. A list of zero or more fields that identifies the default sort order for retrieving schema entries. Specify NULL for this parameter if you do not want to retrieve the default sort fields. The set of zero or more indexes for the schema. Specify NULL for this parameter if you do not want to retrieve the index list. The help text associated with the schema. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). A time stamp identifying the last change to the schema (includes changing or adding fields or character menus). Specify NULL for this parameter if you do not want to retrieve the time stamp. The owning user for the schema. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the schema. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the schema. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateSchema, ARDecodeDiary, ARDeleteSchema, ARGetField, ARGetListField, ARGetListSchema, ARSetSchema, FreeARCompoundSchema, FreeAREntryListFieldList, FreeARIndexList, FreeARInternalIdList, FreeARPermissionList, FreeARSortList, FreeARStatusList
admingrpList
getListFields
sortList
indexList helpText
timestamp
owner lastChanged changeDiary
status
See Also
6-118
ARGetServerInfo
ARGetServerInfo
Description ARGetServerInfo retrieves the requested configuration information for the
specified server.
Privileges Synopsis

#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARGetServerInfo( ARControlStruct ARServerInfoRequestList ARServerInfoList ARStatusList *control, *requestList, *serverInfo, *status)
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, sessionId, and server fields are required. A list of one or more server options to return (see Server Options below).
requestList Return Values serverInfo
The information retrieved from the server (see Server Options below). The system returns NULL (AR_DATA_TYPE_NULL) for server options not retrieved due to error. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
status
Server Options AR_SERVER_INFO_ACTLINK_DIR:
The name of a directory where all external processes to be run by active links must reside. If the value is NULL, active links can run processes located anywhere.
AR_SERVER_INFO_ACTLINK_SHELL:
The name of a shell to use when running external processes from an active link. If the value is NULL, processes are run from /bin/sh (UNIX) or without a shell (Windows NT).
Functions 6-119
AR_SERVER_INFO_ADMIN_ONLY:
A flag indicating whether the server is in Administrator Only mode (1) or not (0). When not in Administrator Only mode, subadministrators can also perform administrator duties. The default value is 0 (Not in Administrator Only mode).
AR_SERVER_INFO_ADMIN_TCP_PORT:
The TCP port that the administrator thread will use.

AR_SERVER_INFO_ALLOW_GUESTS:
A flag indicating whether the server accepts guest users. Guest users are users not registered with the AR System. If allowed, guest users have no permissions but are allowed to perform some basic operations. Guest users can submit entries to schemas for which permission has been given to the Public group and enter data in fields that have been defined as allowing any user to submit. If not allowed, unregistered users have no access to the system. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 1 (allow guest users).
AR_SERVER_INFO_AP_DEFN_CHECK:
The length of time in seconds between checks by an application service to verify that definitions it is using from the AR System are correct. The value can be from 0 to 3600 seconds (1 hour). A value of 0 means to check definitions with each command. A larger value means a slight delay in recognizing changes to some definition, while a smaller value means the significant overhead of checking the definitions often. The default value is 300 seconds (5 minutes).
AR_SERVER_INFO_AP_LOG_FILE:
The name of the file to use if approval tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_AP_RPC_SOCKET:
The RPC program number the approval server will use when contacting the AR System. This allows you to define a specific AR System server for private use by the approval server.
AR_SERVER_INFO_API_LOG_FILE:
The name of the file to use if API tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_APPL_PENDING:
The name of the schema that contains the pending list of application commands to be processed. This schema is specific to the use of Application-Commands.
6-120
ARGetServerInfo
AR_SERVER_INFO_CACHE_LOG_FILE
The file name used for the cache log if shared cache tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_CACHE_SEG_SIZE
(UNIX only) The shared cache segment size in bytes. The default value is 5,000,000.
AR_SERVER_INFO_CASE_SENSITIVE:
A value indicating whether the underlying database is case-sensitive. Valid values for this option are 0 (case-sensitive) and 1 (case-insensitive). The default value is 1 (case-insensitive).
AR_SERVER_INFO_CLUSTERED_INDEX:
A value that indicates whether a clustered index is created on the EntryId field when a new schema is created. Valid values for this option are 1 (create a clustered index) and 0 (create a unique index). The default value is 1 (clustered), but you can override this in the AR configuration file.
AR_SERVER_INFO_DBCONF:
The complete contents of the db.conf (ardb.cfg) file.

AR_SERVER_INFO_DBHOME_DIR:
The home directory for the underlying database (applicable for SQL databases only).
AR_SERVER_INFO_DB_NAME:
The name of the underlying SQL database (not applicable for Oracle databases). The default value is ARSystem.
AR_SERVER_INFO_DB_TYPE:
The underlying database type (character string).

AR_SERVER_INFO_DB_USER:
The user name the Action Request System uses to access the underlying database.
AR_SERVER_INFO_DB_VERSION:
The underlying database version (character string).
Functions 6-121
AR_SERVER_INFO_DEBUG_MODE:
A bitmask indicating the server debug modes.

Bit 0:
Bit 1:
Bit 2: Bit 3:
Bit 4:
Bit 5:
Bit 6: Bit 15:
Enables SQL tracing (applicable for SQL databases only). The default file for SQL tracing is arsql.log (see AR_SERVER_INFO_SQL_LOG_FILE). Enables filter tracing. The default file for filter tracing is arfilter.log (see AR_SERVER_INFO_FILTER_LOG_FILE). Enables user tracing. The default file for user tracing is aruser.log (see AR_SERVER_INFO_USER_LOG_FILE). Enables escalation tracing. The default file for escalation tracing is arescl.log (see AR_SERVER_INFO_ESCALATION_LOG_FILE). Enables API tracing. The default file for API tracing is arapi.log (see AR_SERVER_INFO_API_LOG_FILE). (Windows NT only) Enables thread tracing. The default file for thread tracing is arthread.log (see AR_SERVER_INFO_THREAD_LOG_FILE). For shared cache (See AR_SERVER_INFO_CACHE_LOG_FILE). Enables distributed server tracing (applicable for Distributed Server Option only). The default file for distributed server tracing is ardist.log (see AR_SERVER_INFO_DS_LOG_FILE).
AR_SERVER_INFO_DELAYED_CACHE:
A flag indicating whether to disable recacheing of the shared cache after a time-out (1) or not (0). The default value is 0 (delayed recache not disabled).
AR_SERVER_INFO_DS_LOG_FILE:
The name of the file to use if distributed server tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_DS_MAPPING:
The name of the schema that contains distributed mapping definitions (applicable for Distributed Server Option only).
AR_SERVER_INFO_DS_PENDING:
The name of the schema that contains the pending operation list (applicable for Distributed Server Option only).
AR_SERVER_INFO_DS_RPC_SOCKET:
The specific server socket to use for the distributed server. Valid values for this option are 390600 and 390680 through 390694. Any other value causes the distributed server to use the default server.
6-122
ARGetServerInfo
AR_SERVER_INFO_DS_SVR_LICENSE:
The distributed server license type (character string).

AR_SERVER_INFO_DSO_DEST_PORT:
The TCP port that the distributed server option uses to communicate with the Action Request System server.
AR_SERVER_INFO_EMAIL_FROM:
The sender name to use for filter-generated email notifications where no subject is specified. Only "trusted" email users can use this name (refer to documentation about the /etc/sendmail.cf file for more information about trusted users).
AR_SERVER_INFO_EMAIL_LINE_LEN:
The maximum line length of e-mail messages.

AR_SERVER_INFO_EMAIL_TIMEOUT:
(UNIX only) The length of time in seconds before the system closes the pipe to sendmail to unblock the AR System server. Valid values for this option are from 1 to 300. The default value is 10.
AR_SERVER_INFO_EMBEDDED_SQL:
A value indicating whether the underlying SQL database is embedded (bundled with the Action Request System). Valid values for this option are 0 (not embedded) and 1 (embedded).
AR_SERVER_INFO_ESCALATION_LOG_FILE:
The name of the file to use if escalation tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_ESCL_DAEMON:
A flag indicating whether a private escalation daemon is running (requires a Multi-Processing Server license). Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 0 (private escalation daemon not running).
AR_SERVER_INFO_ESCL_TCP_PORT:
The TCP port that the escalation thread will use.

AR_SERVER_INFO_FAST_TCP_PORT:
The number of the port that the first of the fast servers will use. Each subsequent fast server will use the port with the next sequential number after the server before it.
AR_SERVER_INFO_FILT_MAX_TOTAL:
The maximum number of filters that the server will execute for a given operation. The default value is 10000.
Functions 6-123
AR_SERVER_INFO_FILT_MAX_STACK:
The maximum number of levels of recursion allowed for a given operation. The data modification performed by an AR_FILTER_ACTION_FIELDP filter action could trigger a second set, or level, of filters, one of which could trigger filters a third level down and so on. This option limits the number of times such recursion can happen, preventing the server crash that would occur if the recursion continued indefinitely. The default value is 25.
AR_SERVER_INFO_FILTER_LOG_FILE:
The name of the file to use if filter tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_FLASH_DAEMON:
A flag indicating whether Flashboards is installed (1) or not (0). The default value is 1 if the server has one or more Flashboards licenses, and 0 if the server has no licenses.
AR_SERVER_INFO_FLASH_TCP_PORT
The TCP port that the Flashboards thread will use.

AR_SERVER_INFO_FLOAT_LICENSE:
The number of floating write licenses defined.

AR_SERVER_INFO_FLOAT_TIMEOUT:
The number of hours the server waits before disconnecting inactive users. If a user is holding a floating write license token, the system also frees the token at this time.
AR_SERVER_INFO_FTEXT_FIXED:
The number of fixed Full Text licenses defined.

AR_SERVER_INFO_FTEXT_FLOAT:
The number of floating Full Text licenses defined.

AR_SERVER_INFO_FTEXT_TIMEOUT:
The number of hours the server waits before disconnecting inactive users with Full Text licenses. If a user is holding a floating Full Text license token, the system also frees the token at this time.
AR_SERVER_INFO_FULL_HOSTNAME:
The full DNS host name of the server (long machine name).
AR_SERVER_INFO_G_CACHE_CHANGE:
The time of the last change to the group cache.

AR_SERVER_INFO_HARDWARE:
The server hardware type (character string).
6-124
ARGetServerInfo
AR_SERVER_INFO_HOSTNAME:
The host name of the server (short machine name).

AR_SERVER_INFO_LIST_TCP_PORT:
The number of the port that the first of the list servers will use. Each subsequent list server will use the port with the next sequential number after the server before it.
AR_SERVER_INFO_INFORMIX_DBN:
Informix database server name. This option has a value only if you are using an Informix database.
AR_SERVER_INFO_INFORMIX_TBC:
The Informix configuration file. This option has a value only if you are using an Informix database. The default value is onconfig.
AR_SERVER_INFO_INGRES_VNODE
Vnode setting for remote access to an Ingres database. This option has a value only if you are using an Ingres database.
AR_SERVER_INFO_MAX_ENTRIES:
The maximum number of entries returned by a single query. Because users can also specify the maximum number of entries returned (in query preferences), the actual maximum is the lower of these two values. The default value is no (server-defined) maximum.
AR_SERVER_INFO_MAX_F_DAEMONS:
The maximum number of fast servers allowed (requires a MultiProcessing Server license). Fast servers perform short, nonblocking database operations. They do not perform database searches. Valid values for this option are 0 through 15. The default value is 0 (no fast servers).
AR_SERVER_INFO_MAX_L_DAEMONS:
The maximum number of list servers allowed (requires a Multi-Processing Server license). List servers perform blocking database operations, including database searches. These operations can result in short or long server blocks. Valid values for this option are 0 through 35. The default value is 0 (no list servers).
AR_SERVER_INFO_MAX_SCHEMAS:
The maximum number of schemas allowed. The default value is 0 (no limit).
AR_SERVER_INFO_NFY_TCP_PORT:
The TCP port that the Notifier server will use.
Functions 6-125
AR_SERVER_INFO_ORACLE_SID:
The System ID of the Oracle database you are accessing. This option has a value only if you are using an Oracle database.
AR_SERVER_INFO_ORACLE_TWO_T:
The two-task environment setting for remote access to an Oracle database. This option has a value only if you are using an Oracle database.
AR_SERVER_INFO_PS_RPC_SOCKET:
The RPC program number and port pairs the Private Servers will use. A value of 0 for the port means no port was specified.
AR_SERVER_INFO_REGISTER_PORTMAPPER:
A flag indicating whether to register with the portmapper (1) or not (0). The default value is 1.
AR_SERVER_INFO_REM_SERV_ID:
The AR System server ID associated with the license (character string).

AR_SERVER_INFO_RESERV1_A:
The number of fixed Flashboards licenses defined.

AR_SERVER_INFO_SAVE_LOGIN:
A value indicating whether users must log in to client tools.

0: 1: 2:
Controlled by user (default setting). Force no login (controlled by the administrator). Force login (controlled by the administrator).
AR_SERVER_INFO_SERVER_DIR:
The data directory for the AR System. This directory contains support files for the underlying SQL database (but no actual database files). For flat file databases, this directory contains both database definition and data files.
AR_SERVER_INFO_SERVER_IDENT:
The unique identifier for the server (character string).

AR_SERVER_INFO_SERVER_LANG:
The local language setting of the server.

AR_SERVER_INFO_SERVER_LICENSE:
The server license type (character string).

AR_SERVER_INFO_SERVER_NAME:
An alias server name that is always interpreted as the current server. The name is not fully qualified. For example, the server alpha.remedy.com would have the value alpha. See also Server-Name in ar.conf.
6-126
ARGetServerInfo
AR_SERVER_INFO_SET_PROC_TIME:
The number of seconds the server waits before ending a set fields process that has not completed. Valid values for this option are 1 through 20. The default value is five seconds.
AR_SERVER_INFO_SHARED_CACHE:
(UNIX only) A flag indicating whether the server will use a shared cache for structure definitions. Valid values for this option are 1 (Use shared cache) and 0 (do not use shared cache).
AR_SERVER_INFO_SHARED_MEM:
(UNIX only) A flag indicating whether the shared memory is disabled or enabled. Valid values for this option are 1 (shared memory enabled) and 0 (shared memory disabled).
AR_SERVER_INFO_SQL_LOG_FILE:
The name of the file to use if SQL tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_SUBMITTER_MODE:
A value indicating whether the Submitter field can be changed and whether the submitter of an entry must have a license to modify it. In locked mode, the Submitter field cannot be changed after submit, and the submitter can modify the entry with or without a write license (if the Submitter group has Change permission). In changeable mode, the Submitter field can be changed after submit, but the submitter must have a write license to modify the entry (if the Submitter group has Change permission). Valid values for this option are 1 (locked) and 2 (changeable). The default value is 2 (changeable).
AR_SERVER_INFO_SUPPRESS_WARN:
A series of zero or more message numbers (separated by spaces) that identify the informational or warning messages that the system suppresses.
AR_SERVER_INFO_SYBASE_CHARSET:
The character set being used to access a Sybase database. This option has a value only if you are using a Sybase database.
AR_SERVER_INFO_SYBASE_SERV:
The Sybase logical server name. This option has a value only if you are using a Sybase database. The default value is SYBASE.
AR_SERVER_INFO_TCD_TCP_PORT:
The TCP port that the TCD thread will use.
Functions 6-127
AR_SERVER_INFO_THREAD_LOG_FILE:
The name of the file to use if thread tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE) (Windows NT only).
AR_SERVER_INFO_U_CACHE_CHANGE:
The time of the last change to the user cache.

AR_SERVER_INFO_USER_CACHE_UTILS: A flag indicating whether the ARCACHE and ARRELOAD utilities are disabled.
Valid values for this option are 1 (disabled) and 0 (enabled).

AR_SERVER_INFO_UNQUAL_QUERIES:
A flag indicating whether the server allows unqualified queries. Unqualified queries are ARGetListEntry calls in which the qualifier parameter is either NULL or has an operation value of 0 (AR_COND_OP_NONE). These queries can cause performance problems, especially for large schemas, because they return all entries for a given schema. If not allowed, you can return all schema entries by specifying a dummy qualification such as 1 = 1. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 1 (allow unqualified queries).
AR_SERVER_INFO_USER_LICENSE:
The number of fixed write licenses defined.

AR_SERVER_INFO_USER_LOG_FILE:
The name of the file to use if user tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_USE_ETC_PASSWD: A flag indicating whether the /etc/passwd file is used to validate users
not registered with the AR System (UNIX only). If so, users in /etc/passwd are considered valid users of the AR System and are assigned to a group identified by the UNIX group ID. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 1 (use password file).
AR_SERVER_INFO_VERSION:
The AR System server version (character string).

AR_SERVER_INFO_XREF_PASSWORDS: A flag indicating whether the /etc/passwd file is cross-referenced if an
AR System user has no password (UNIX only). This option enables you to manage group membership and other support information by using the AR System but still manage passwords using the /etc/passwd file. Valid
6-128
ARGetServerInfo
values for this option are 1 (TRUE) and 0 (FALSE). The default value is 0 (blank passwords not cross-referenced).
See Also ar.conf file, ARGetFullTextInfo, ARGetServerStatistics, ARSetFullTextInfo, ARSetServerInfo, FreeARServerInfoList, FreeARServerInfoRequestList, FreeARStatusList
Functions 6-129
ARGetServerStatistics
Description ARGetServerStatistics retrieves the requested statistics for the specified server. The counts returned generally represent the number of occurrences since starting the server. If a statistic reaches the maximum value for a long integer, the system resets the counter and begins incrementing again.
Privileges Synopsis

#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARGetServerStatistics( ARControlStruct ARServerInfoRequestList ARServerInfoList ARStatusList *control, *requestList, *serverInfo, *status)
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, sessionId, and server fields are required. A list of one or more statistics to return (see Statistic Options below).
requestList Return Values serverInfo
The statistics retrieved from the server (see Statistic Options below). The system returns NULL (AR_DATA_TYPE_NULL) for statistics not retrieved due to error. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
status
Statistic Options AR_SERVER_STAT_API_REQUESTS (integer):
The total number of API requests received.

AR_SERVER_STAT_API_TIME (integer):
The total processor time spent performing API function calls.
6-130
AR_SERVER_STAT_BAD_PASSWORD (integer):
The total number of times an incorrect password was specified during login.
AR_SERVER_STAT_CACHE_TIME (integer):
The total processor time spent loading the internal cache to improve performance.
AR_SERVER_STAT_CPU (integer):
The total CPU time used by the server.

AR_SERVER_STAT_CREATE_E_COUNT (integer): The total number of calls made to the ARCreateEntry function. AR_SERVER_STAT_CREATE_E_TIME (integer):
The total processor time spent performing the ARCreateEntry function.

AR_SERVER_STAT_CURRENT_USERS (integer):
The total number of users currently accessing the system.

AR_SERVER_STAT_DELETE_E_COUNT (integer): The total number of calls made to the ARDeleteEntry function. AR_SERVER_STAT_DELETE_E_TIME (integer):
The total processor time spent performing the ARDeleteEntry function.

AR_SERVER_STAT_ENTRY_TIME (integer):
The total processor time spent performing API function calls that manipulate entries.
AR_SERVER_STAT_ESCL_DISABLE (integer):
The total number of escalations that were evaluated but skipped because they were marked disabled.
AR_SERVER_STAT_ESCL_FAILED (integer):
The total number of escalations that were skipped (qualification criteria not met).
AR_SERVER_STAT_ESCL_FIELDP (integer):
The total number of push fields escalation actions performed.

AR_SERVER_STAT_ESCL_FIELDS (integer):
The total number of set fields escalation actions performed.

AR_SERVER_STAT_ESCL_LOG (integer):
The total number of log escalation actions performed.

AR_SERVER_STAT_ESCL_NOTIFY (integer):
The total number of notify escalation actions performed.
Functions 6-131
AR_SERVER_STAT_ESCL_PASSED (integer):
The total number of escalations that were executed (qualification criteria met).
AR_SERVER_STAT_ESCL_PROCESS (integer):
The total number of run process escalation actions performed.

AR_SERVER_STAT_ESCL_SQL (integer):
The total number of direct SQL escalation actions performed.

AR_SERVER_STAT_ESCL_TIME (integer):
The total processor time spent checking and processing escalations.

AR_SERVER_STAT_E_STATS_COUNT (integer): The total number of calls made to the ARGetEntryStatistics function. AR_SERVER_STAT_E_STATS_TIME (integer):
The total processor time spent performing the ARGetEntryStatistics function.

AR_SERVER_STAT_FILTER_DISABLE (integer):
The total number of filters that were evaluated but skipped because they were marked disabled.
AR_SERVER_STAT_FILTER_FAILED (integer):
The total number of filters that were skipped (qualification criteria not met).
AR_SERVER_STAT_FILTER_FIELDP (integer):
The total number of push fields filter actions performed.

AR_SERVER_STAT_FILTER_FIELDS (integer):
The total number of set fields filter actions performed.

AR_SERVER_STAT_FILTER_LOG (integer):
The total number of log filter actions performed.

AR_SERVER_STAT_FILTER_MESSAGE (integer):
The total number of message filter actions performed.

AR_SERVER_STAT_FILTER_NOTIFY (integer):
The total number of notify filter actions performed.

AR_SERVER_STAT_FILTER_PASSED (integer):
The total number of filters that were executed (qualification criteria met).
AR_SERVER_STAT_FILTER_PROCESS (integer):
The total number of run process filter actions performed.
6-132
AR_SERVER_STAT_FILTER_SQL (integer):
The total number of direct SQL filter actions performed.

AR_SERVER_STAT_FILTER_TIME (integer):
The total processor time spent checking and processing filters.

AR_SERVER_STAT_FTS_SRCH_COUNT (integer):
The total number of Full Text Search operations performed.

AR_SERVER_STAT_FTS_SRCH_TIME (integer):
The total processor time spent performing Full Text Search operations.
AR_SERVER_STAT_FULL_FIXED (integer):
The total number of connected users with fixed Full Text licenses.
AR_SERVER_STAT_FULL_FLOATING (integer):
The total number of connected users with floating Full Text licenses.
AR_SERVER_STAT_FULL_NONE (integer):
The total number of connected users with no Full Text license.

AR_SERVER_STAT_GETLIST_E_COUNT (integer): The total number of calls made to the ARGetListEntry function. AR_SERVER_STAT_GETLIST_E_TIME (integer):
The total processor time spent performing the ARGetListEntry function.

AR_SERVER_STAT_GET_E_COUNT (integer):
The total number of calls made to the ARGetEntry function.

AR_SERVER_STAT_GET_E_TIME (integer):
The total processor time spent performing the ARGetEntry function.

AR_SERVER_STAT_IDLE_TIME (integer):
The total idle time when the server is not processing any requests.
AR_SERVER_STAT_MERGE_E_COUNT (integer): The total number of calls made to the ARMergeEntry function. AR_SERVER_STAT_MERGE_E_TIME (integer):
The total processor time spent performing the ARMergeEntry function.

AR_SERVER_STAT_NET_RESP_TIME (integer):
The total time spent on the network responding to the client.

AR_SERVER_STAT_NO_FULL_TOKEN (integer):
The total number of times a user tried to connect and no floating Full Text token was available.
Functions 6-133
AR_SERVER_STAT_NO_WRITE_TOKEN (integer):
The total number of times a user tried to connect and no floating write token was available.
AR_SERVER_STAT_NUMBER_BLOCKED (integer):
The total number of blocked processes. This statistic, in conjunction with the AR_SERVER_STAT_TIMES_BLOCKED statistic, enables you to determine the approximate number of processes being blocked per instance. For example, if AR_SERVER_STAT_TIMES_BLOCKED is three and AR_SERVER_STAT_NUMBER_BLOCKED is six, the six blocked processes could be distributed in three possible ways: 1) 2) 3) Two blocked processes in each of the three instances (2+2+2 = 6). Three blocked processes in one instance, two blocked processes in one instance, and one blocked process in one instance (3+2+1 = 6). Four blocked processes in one instance and one blocked process in both of the other two instances (4+1+1 = 6).
In this example, the blocked processes could not be distributed as five in one instance, one in one instance, and none in one instance because, by definition, the number of instances represents those times when at least one process is blocked.
AR_SERVER_STAT_OTHER_TIME (integer):
The total processor time spent performing API function calls that do not manipulate entries or restructure the database.
AR_SERVER_STAT_RESTRUCT_TIME (integer):
The total processor time spent performing API function calls that restructure the database.
AR_SERVER_STAT_SET_E_COUNT (integer):
The total number of calls made to the ARSetEntry function.

AR_SERVER_STAT_SET_E_TIME (integer):
The total processor time spent performing the ARSetEntry function.

AR_SERVER_STAT_SINCE_START (integer):
The number of seconds since the server was started (i.e. the total real time that the server process has been running).
AR_SERVER_STAT_SQL_DB_COUNT (integer):
The total number of SQL commands sent to the database.

AR_SERVER_STAT_SQL_DB_TIME (integer):
The total processor time spent performing SQL commands.
6-134
AR_SERVER_STAT_START_TIME (time stamp):
The UNIX time at which this server was started.

AR_SERVER_STAT_TIMES_BLOCKED (integer):
The total number of instances in which at least one process was blocked by the current process. This statistic, in conjunction with the AR_SERVER_STAT_NUMBER_BLOCKED statistic, enables you to determine the approximate number of processes being blocked per instance.
AR_SERVER_STAT_WRITE_FIXED (integer):
The total number of connected users with fixed write licenses.

AR_SERVER_STAT_WRITE_FLOATING (integer):
The total number of connected users with floating write licenses.

AR_SERVER_STAT_WRITE_READ (integer):
The total number of connected users with no write license.

See Also ARGetFullTextInfo, ARGetServerInfo, FreeARServerInfoList, FreeARServerInfoRequestList, FreeARStatusList
Functions 6-135
ARGetSupportFile
Description Privileges ARGetSupportFile retrieves a file supporting external reports.
This operation can be performed by any user who has access to the specified object.
Synopsis
#include #include #include #include
"ar.h" "arerrno.h" "arextern.h" "arstruct.h"
int ARGetSupportFile( ARControlStruct unsigned int ARNameType ARInternalId ARInternalId FILE ARTimeStamp ARStatusList Input Arguments control *control, fileType name, fieldId, fileId, *filePtr, *timeStamp, *status)
The control record for the operation. It contains information about the user requesting the operation and where that operation is to be performed. The user, sessionId, and server fields are required. The numerical value for the type of file, and the type of object the file is associated with. Specify 1 (AR_SUPPORT_FILE_EXTERNAL_REPORT) for an external report file associated with an active link. The name of the object the file is associated with, usually a schema. The ID of the field or VUI, if the object is a schema. If the object is not a schema, set this parameter to 0. The unique identifier of a file within its object. A pointer to a file into which the support file contents will be retrieved. Specify
NULL for this parameter if you do not want to retrieve the file contents. If you
fileType
name fieldId fileId filePtr
are using Windows, you must open the file in binary mode.
timestamp
A time stamp identifying the last change to the field. Specify NULL for this parameter if you do not want to retrieve the time stamp.
6-136
ARGetSupportFile
Return Values status See Also
A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values.)
ARCreateActiveLink, ARCreateSupportFile, ARDeleteActiveLink, ARDeleteSupportFile, ARGetActiveLink, ARGetListSupportFile, ARSetActiveLink, ARSetSupportFile
Functions 6-137
ARGetTextForErrorMessage
Description ARGetTextForErrorMessage retrieves the message text for the specified error from the local catalog (in the local language). The length of the text is limited by AR_MAX_MESSAGE_SIZE (255 bytes).
Privileges Synopsis

#include "ar.h" #include "arerrno.h" #include "arextern.h" char * ARGetTextForErrorMessage ( int msgId)
Input Arguments msgId
The error number whose message text you want to retrieve. This number is provided in the messageNum member of ARStatusStruct.
Return Values return
The function return value is a pointer to the retrieved message text. You must free this memory after calling this function.
6-138
ARGetVUI
ARGetVUI
Description ARGetVUI retrieves information about the schema view (VUI) with the indicated ID on the specified server.
Privileges
This operation can be performed by users with access permission for the schema with which the VUI is associated.
Synopsis
int ARGetVUI( ARControlStruct ARNameType ARInternalId ARNameType ARPropList char ARTimestamp ARNameType ARNameType char ARStatusList Input Arguments control *control, schema, vuiId, vuiName, *dPropList, **helpText, *timestamp, owner, lastChanged, **changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema containing the VUI to retrieve. The internal ID of the VUI to retrieve.
schema vuiId Return Values vuiName dPropList
The name of the VUI. Specify NULL for this parameter if you do not want to retrieve the VUI name. A list of zero or more display properties associated with the VUI. See ARCreateVUI on page 6-40 for a description of the possible values. The system returns 0 (AR_DPROP_NONE) if the VUI has no display properties. Specify NULL for this parameter if you do not want to retrieve this list.
Functions 6-139
helpText
The help text associated with the VUI. Specify NULL for this parameter if you do not want to retrieve the help text (which is useful if you are calling this function to verify whether an instance of this object exists). A time stamp identifying the last change to the VUI. Specify NULL for this parameter if you do not want to retrieve the time stamp. The owning user for the VUI. Specify NULL for this parameter if you do not want to retrieve the owner. The user who made the last change to the VUI. Specify NULL for this parameter if you do not want to retrieve this information. The change diary associated with the VUI. Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. Specify NULL for this parameter if you do not want to retrieve the change diary (which is useful if you are calling this function to verify whether an instance of this object exists). A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateVUI, ARDecodeDiary, ARDeleteVUI, ARGetListVUI, ARSetVUI, FreeARPropList, FreeARStatusList
status
See Also
6-140
ARImport
ARImport
Description ARImport imports the indicated structure definitions to the specified server. Use this function to copy structure definitions from one AR System server to another (see ARExport on page 6-64).
Privileges
Synopsis
int ARImport( ARControlStruct ARStructItemList char ARStatusList Input Arguments control *control, *structItems, *importBuf, *status)
Functions 6-141
structItems
A list of zero or more structure items to import (identified by type and name). Specify NULL for this parameter if you want to import all structures in the import buffer.
1: 5: 6: 8: 9: 10: 12:
Schema (includes all associated views) (AR_STRUCT_ITEM_SCHEMA). Filter (AR_STRUCT_ITEM_FILTER). Active link (AR_STRUCT_ITEM_ACTIVE_LINK). Character menu (AR_STRUCT_ITEM_CHAR_MENU). Escalation (AR_STRUCT_ITEM_ESCALATION). Distributed mapping (AR_STRUCT_ITEM_DIST_MAP). Container (AR_STRUCT_ITEM_CONTAINER).
Note:
You must specify AR_STRUCT_ITEM_SCHEMA to import a schema. The three partial schema types defined in ar.h (AR_STRUCT_ITEM_SCHEMA_DEFN, AR_STRUCT_ITEM_SCHEMA_VIEW, and AR_STRUCT_ITEM_SCHEMA_MAIL) do not contain complete schema definitions and are used for caching purposes only.
importBuf
A buffer that contains the definition text for the items specified for the structItems parameter. This buffer can contain other structure definitions, but the system imports the specified items only.
ARExport, FreeARStatusList, FreeARStructItemList
See Also
6-142
ARInitialization
ARInitialization
Description ARInitialization performs server- and network-specific initialization operations for each Action Request System session. All API programs that interact with the AR System must call this function before calling any other AR System API functions. Your program can call this function again to create additional sessions.
Privileges Synopsis

int ARInitialization( ARControlStruct ARStatusList Input Arguments control *control, *status)
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. The sessionId field, which you must supply in the control record for most other functions, will be returned by this function.
ARTermination, FreeARStatusList
See Also
Functions 6-143
ARLoadARQualifierStruct
Description ARLoadARQualifierStruct loads the specified qualification string (if valid for the schema) into an ARQualifierStruct structure. This function simplifies the process of specifying qualifications in the required format. #include #include #include #include "ar.h" "arerrno.h" "arextern.h" "arstruct.h"
Synopsis
int ARLoadARQualifierStruct( ARControlStruct ARNameType ARNameType char ARQualifierStruct ARStatusList Input Arguments control *control, schema, displayTag, *qualString, *qualifier, *status)
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, sessionId, and server fields are required. The name of the schema to which the qualification applies. The name of the schema view (VUI) to use for resolving field names. If the specified view does not exist or does not contain a field specified in the qualification string (or you specify NULL for this parameter), the system uses the field name in the default view. A character string containing the qualification to load (following the syntax rules for entering qualifications in the Remedy User query bar).
schema displayTag
qualString
Return Values qualifier
An ARQualifierStruct structure that contains the specified qualification. Use FreeARQualifierStruct to recursively free the allocated memory associated with this structure as soon as you no longer need it. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARGetEntryStatistics, ARGetListEntry, FreeARQualifierStruct, FreeARStatusList
status
See Also
6-144
ARMergeEntry
ARMergeEntry
Description ARMergeEntry merges an existing entry into the indicated schema on the specified server. You can merge entries into base schemas only. To add entries to join schemas, merge them into one of the underlying base schemas.
Privileges
The system merges data based on the access privileges of the user you specify for the control parameter and the createMode setting for each field (see ARCreateField on page 6-19). User permissions are verified for each specified field. The system generates an error if the user does not have write permission for a field or a field does not exist.
Synopsis
int ARMergeEntry( ARControlStruct ARNameType ARFieldValueList unsigned int AREntryIdType ARStatusList Input Arguments control *control, schema, *fieldList, mergeType, entryId, *status)
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, sessionId, and server fields are required. The name of the schema to merge the entry into. A list of one or more field/value pairs (specified in any order) that identifies the data for the new entry. You must specify values for all required fields that do not have defined defaults. Values must be of the data type defined for the field or have a data type of 0 (AR_DATA_TYPE_NULL). NULL values can be specified for optional fields only, and assigning NULL overrides any defined
schema fieldList
Functions 6-145
field default. An error is generated if a field does not exist or the user specified by the control parameter does not have write permission for a field. Note: You must specify a formatted diary string (such as that returned by ARGetEntry) for any diary fields you want to merge. In addition, unlike creating a new entry, you can specify values for the Entry ID, Create Date, Last Modified By, Modified Date, and Status History fields when merging an existing entry.
mergeType
A value indicating the action to take if fieldList includes the Entry ID field and the ID specified already exists in the target schema. This parameter is ignored if you do not specify the Entry ID field or the ID specified does not conflict with existing entry IDs.
1: 2: 3:
4:
Generate an error (AR_MERGE_ENTRY_DUP_ERROR). Create a new entry with a new ID (AR_MERGE_ENTRY_DUP_NEW_ID). Delete the existing entry and create a new one in its place (AR_MERGE_ENTRY_DUP_OVERWRITE). Update the fields specified in fieldList in the existing entry (AR_MERGE_ENTRY_DUP_MERGE).
To omit some field validation steps, add the appropriate increments to the merge type.
1024:
2048:
Allow NULL in required fields (not applicable for the Submitter, Status, or Short-Description core fields) (AR_MERGE_NO_REQUIRED_INCREMENT). Skip field pattern checking (including $MENU$) (AR_MERGE_NO_PATTERNS_INCREMENT).
Return Values entryId
The ID of the merged entry. If you do not specify the Entry ID field in fieldList, the system generates and returns a new ID. If you do specify the Entry ID field and the ID specified is unique in the target schema, the system returns that ID. If the ID specified is not unique and you specify AR_MERGE_ENTRY_DUP_NEW_ID for the mergeType parameter, the system generates and returns a new ID. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ARCreateEntry, FreeARFieldValueList, FreeARStatusList
status
See Also
6-146
ARSetActiveLink
ARSetActiveLink
Description ARSetActiveLink updates the active link with the indicated name on the specified server. The changes are added to the server immediately and returned to users who request information about active links. Because active links operate on clients, individual clients do not receive the updated definition until they reconnect to the schema (thus reloading the schema from the server).
Privileges
Synopsis
int ARSetActiveLink( ARControlStruct ARNameType ARNameType unsigned int ARNameType ARInternalIdList unsigned int ARInternalId ARInternalId unsigned int ARQualifierStruct ARActiveLinkActionList ARActiveLinkActionList char ARNameType char ARStatusList Input Arguments control *control, name, newName, *order, schema, *groupList, *executeMask, *controlField, *focusField, *enable, *query, *actionList, *elseList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the active link to update.
name
Functions 6-147
newName
The new name for the active link. The names of all active links on a given server must be unique. Specify NULL for this parameter if you do not want to change the name of the active link. A value between 0 and 1000 (inclusive) that determines the active link execution order. When multiple active links are associated with a schema, the value associated with each active link determines the order in which they are processed (from lowest to highest). Specify NULL for this parameter if you do not want to change the order. The name of the schema the active link is linked to. The active link must be associated with a single schema that currently exists on the server. Specify NULL for this parameter if you do not want to change the schema. A list of zero or more groups who can access this active link. Users can execute an active link if they belong to a group that has access to it. Specifying an empty group list defines an active link accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. The group list you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the group list. A bitmask indicating the schema operations that trigger the active link.
Bit 0:
order
schema
groupList
executeMask
Bit 1: Bit 2:
Bit 3:
Bit 4: Bit 7:
Bit 9:
Execute the active link when a user selects a button, toolbar button, or menu item specified by the controlField parameter (AR_EXECUTE_ON_BUTTON). Execute the active link when a user presses Return in the field specified by the focusField parameter (AR_EXECUTE_ON_RETURN). Execute the active link when a user submits an entry (before data is sent to the AR System server) (AR_EXECUTE_ON_SUBMIT). Execute the active link when a user modifies an individual entry (before data is sent to the AR System server) (AR_EXECUTE_ON_MODIFY). Execute the active link when a user displays an entry (after data is retrieved from the AR System server) (AR_EXECUTE_ON_DISPLAY). Execute the active link when a user selects an item from a character menu associated with the field specified by the focusField parameter or selects a row in the table field specified by the focusField parameter (AR_EXECUTE_ON_MENU_CHOICE). Execute the active link when a user sets default values (either manually or with preference settings) (AR_EXECUTE_ON_SET_DEFAULT).
6-148
ARSetActiveLink
Bit 10:
Bit 11:
Bit 12: Bit 14:
Bit 15:
Execute the active link when a user retrieves one or more entries (before the query is sent to the AR System server) (AR_EXECUTE_ON_QUERY). Execute the active link when a user modifies an individual entry (after data is committed to the database) (AR_EXECUTE_ON_AFTER_MODIFY). Execute the active link when a user submits an entry (after data is committed to the database) (AR_EXECUTE_ON_AFTER_SUBMIT). Execute the active link when a user opens any schema window (AR_EXECUTE_ON_WINDOW_OPEN). Execute the active link when a user closes any schema window (AR_EXECUTE_ON_WINDOW_CLOSE).
Specify NULL for this parameter if you do not want to change the execute mask.
controlField The ID of the field that represents the button, toolbar button, or menu item associated with executing the active link. The AR_EXECUTE_ON_BUTTON condition (see the executeMask parameter) is ignored unless you specify this
parameter. This parameter is ignored if you do not specify AR_EXECUTE_ON_BUTTON. Specify NULL for this parameter if you do not want to change the control field.
focusField
The ID of the field associated with executing the active link by pressing Return or selecting a character menu item. The AR_EXECUTE_ON_RETURN or AR_EXECUTE_ON_MENU_CHOICE conditions (see the executeMask parameter) are ignored unless you specify this parameter (you must create another active link to specify a different field for each condition). This parameter is ignored if you do not specify either condition. Specify NULL for this parameter if you do not want to change the focus field. A flag to enable or disable this active link. A value of 0 disables the active link, causing it to be invisible to the user and unavailable for use. A value of 1 enables the active link, causing it to be visible and available for use. Specify NULL for this parameter if you do not want to change this flag. A qualification that determines whether the active link is executed. Assign an operation value of 0 (AR_COND_OP_NONE) to execute the active link unconditionally. Specify NULL for this parameter if you do not want to change the query. The set of actions performed if the condition defined by the query parameter is satisfied. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to change the action list.
enable
query
actionList
Functions 6-149
elseList
The set of actions performed if the condition defined by the query parameter is not satisfied. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify a list with zero items to define no else actions. Specify NULL for this parameter if you do not want to change the else list. The help text associated with the active link. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text. The owning user for the active link. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the active link. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
helpText owner changeDiary
ARCreateActiveLink, ARDeleteActiveLink, ARGetActiveLink, ARGetListActiveLink, FreeARActiveLinkActionList, FreeARInternalIdList, FreeARQualifierStruct, FreeARStatusList
See Also
6-150
ARSetCharMenu
ARSetCharMenu
Description ARSetCharMenu updates the character menu with the indicated name on the specified server. The changes are added to the server immediately and returned to users who request information about character menus. Because character menus operate on clients, individual clients do not receive the updated definition until they reconnect to the schema (thus reloading the schema from the server).
Privileges
This operation can be performed by users with AR System administrator privileges only. Note: The refreshCode parameter has no effect on when the updated menu definition is retrieved. Rather, it controls how often the menu contents are retrieved by using the cached menu definition.
Synopsis
#include #include #include #include
"ar.h" "arerrno.h" "arextern.h" "arstruct.h"
int ARSetCharMenu( ARControlStruct ARNameType ARNameType unsigned int ARCharMenuStruct char ARNameType char ARStatusList Input Arguments control *control, name, newName, *refreshCode, *menuDefn, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the character menu to update.
name
Functions 6-151
newName
The new name for the character menu. The names of all character menus on a given server must be unique. Specify NULL for this parameter if you do not want to change the name of the character menu. A value indicating when the menu is refreshed. This parameter enables you to balance menu consistency with performance.
1: 2: 3:
refreshCode
Refresh only when the schema is opened (AR_MENU_REFRESH_CONNECT). Refresh every time the menu is opened (AR_MENU_REFRESH_OPEN). Refresh the first time the menu is opened and every 15 minutes thereafter (AR_MENU_REFRESH_INTERVAL).
Specify NULL for this parameter if you do not want to change the refresh code.
menuDefn helpText
The definition of the character menu. Specify NULL for this parameter if you do not want to change the menu definition. The help text associated with the character menu. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text. The owning user for the character menu. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the character menu. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
owner changeDiary
ARCreateCharMenu, ARDeleteCharMenu, ARExpandCharMenu, ARGetCharMenu, ARGetListCharMenu, FreeARCharMenuStruct, FreeARStatusList
See Also
6-152
ARSetContainer
ARSetContainer
Description ARSetContainer updates the definition for the container with the indicated name on the specified server.
Privileges
Synopsis
int ARSetContainer( ARControlStruct ARNameType ARNameType ARPermissionList ARInternalIdList ARContainerOwnerObj char char unsigned int ARReferenceList ARBoolean char ARNameType char ARStatusList Input Arguments control *control, name, newName, *groupList, *admingrpList, *ownerObj, *label, *description, *type, *references, removeFlag, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the container to update. The new name for the container. The names of all containers on a given server must be unique. The system automatically updates all workflow references to the container if you rename it. Specify NULL for this parameter if you do not want to change the name of the container. A list of zero or more groups who can access this container. Specifying an empty group list defines a container accessible by users with administrator
name newName
groupList
Functions 6-153
capability only. Specifying group ID 0 (Public) provides access to all users. The permission value you assign for each group determines whether users in that group see the container in the container list.
1: 2:
Users see the container in the container list (AR_PERMISSIONS_VISIBLE). Users do not see the container in the container list (AR_PERMISSIONS_HIDDEN).
The group list you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the group list.
admingrpList
A list of zero or more groups who can administer this container (and the referenced objects). If ownerObj is not NULL, this parameter is ignored and the Subadministrator group list of the owning schema is used instead. Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specifying an empty administrator group list defines a container that can be administered by users with administrator capability only. Specifying group ID 0 (Public) provides subadministrator capability to all members of the Subadministrator group. The group list you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the administrator group list. The schema that owns this container. Specify ARCONOWNER_NONE for this parameter if you want the container to exist globally. Specify NULL for this parameter if you do not want to change the containers owning object. The label for this container. It can be as many as 255 characters long. Specify NULL for this parameter if you do not want to change the label. The description for this container. It can be as many as 2000 characters long. Specify NULL for this parameter if you do not want to change the description. The type for this container, either ARCON_GUIDE or ARCON_APP. Specify NULL for this parameter if you do not want to change the type. Pointers to the objects (for example, schemas or filters) referenced by this container. Specify NULL for this parameter if you do not want to change the references. A flag specifying how invalid object references are removed. If FALSE, references to nonexistent AR System objects will be removed with no error generated. If TRUE, an error will be generated. Specify NULL for this parameter if you do not want to change the flag. The help text associated with the container. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text.
ownerObj
label description type references
removeFlag
helpText
6-154
ARSetContainer
owner changeDiary
The owning user for the container. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the container. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
ARCreateContainer, ARDeleteContainer, ARGetContainer, ARGetListContainer, ARSetSchema, FreeARContainerInfoList, FreeARInternalIdList, FreeARPermissionList, FreeARReferenceList, FreeARStatusList
See Also
Functions 6-155
ARSetEntry
Description ARSetEntry updates the schema entry with the indicated ID on the specified
server.
Privileges
The system updates data based on the access privileges of the user you specify for the control parameter. User permissions are verified for each specified field. The system generates an error if the user does not have write permission for a field or a field does not exist.
Synopsis
int ARSetEntry( ARControlStruct ARNameType AREntryIdList ARFieldValueList ARTimestamp unsigned int ARStatusList Input Arguments control *control, schema, *entryId, *fieldList, getTime, option, *status)
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, sessionId, and server fields are required. The name of the schema containing the entry to update. The ID of the entry to update. A list of one or more field/value pairs (specified in any order) that identifies the new data for the entry. Values must be of the data type defined for the field or have a data type of 0 (AR_DATA_TYPE_NULL). NULL values can be specified for optional fields only. An error is generated if a field does not exist or the user specified by the control parameter does not have write permission for a field. A time stamp identifying when the entry was last retrieved. The system compares this value with the value in the Modified Date core field to determine whether the entry has been changed since the last retrieval. The system updates the entry if the value you specify is greater than Modified Date. If not, the system returns an error. You can either retrieve the
schema entryId fieldList
getTime
6-156
ARSetEntry
entry again and determine whether to apply your changes or specify 0 for this parameter to bypass the time stamp comparison.
option
A value indicating whether users can update fields specified in the join qualification (applicable for join schemas only).
0:
1:
Users can update fields used in the join criteria (thereby causing the entry to no longer appear in the join schema) (AR_JOIN_SETOPTION_NONE). Users cannot update fields used in the join criteria (AR_JOIN_SETOPTION_REF).
ARCreateEntry, ARDeleteEntry, ARGetEntry, ARGetListEntry, ARMergeEntry, FreeAREntryIdList, FreeARFieldValueList, FreeARStatusList
See Also
Functions 6-157
ARSetEscalation
Description ARSetEscalation updates the escalation with the indicated name on the specified server. The changes are added to the server immediately and returned to users who request information about escalations.
Privileges
Synopsis
int ARSetEscalation( ARControlStruct ARNameType ARNameType AREscalationTmStruct ARNameType unsigned int ARQualifierStruct ARFilterActionList ARFilterActionList char ARNameType char ARStatusList Input Arguments control *control, name, newName, *escalationTm, schema, *enable, *query, *actionList, *elseList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the escalation to update. The new name for the escalation. The names of all escalations on a given server must be unique. Specify NULL for this parameter if you do not want to change the name of the escalation. The time specification for evaluating the escalation condition. This parameter can take one of two forms: a time interval that defines how frequently the server checks the escalation condition (in seconds) or a bitmask that defines a particular day (by month or week) and time (hour and minute) for the server
name newName
escalationTm
6-158
ARSetEscalation
to check the condition. Specify NULL for this parameter if you do not want to change the escalation time.
schema
The name of the schema the escalation is linked to. The escalation must be associated with a single schema that currently exists on the server. Specify NULL for this parameter if you do not want to change the schema. A flag to enable or disable this escalation. A value of 0 disables the escalation, causing its condition checks and associated actions not to be performed. A value of 1 enables the escalation, causing its conditions to be checked at the specified time interval. Specify NULL for this parameter if you do not want to change this flag. A query operation performed when the escalation is executed that determines the set of entries to which the escalation actions (defined by the actionList parameter) are applied. Assign an operation value of 0 (AR_COND_OP_NONE) to match all schema entries. Specify NULL for this parameter if you do not want to change the query. The set of actions performed for each entry that matches the criteria defined by the query parameter. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to change the action list. The set of actions performed if no entries match the criteria defined by the query parameter. These actions are not performed for all nonmatching entries. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify a list with zero items to define no else actions. Specify NULL for this parameter if you do not want to change the else list. The help text associated with the escalation. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text. The owning user for the escalation. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the escalation. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
enable
query
actionList
elseList
Functions 6-159
ARCreateEscalation, ARDeleteEscalation, ARGetEscalation, ARGetListEscalation, FreeARFilterActionList, FreeARQualifierStruct, FreeARStatusList
See Also
6-160
ARSetField
ARSetField
Description ARSetField updates the definition for the schema field with the indicated ID on the specified server.
Privileges
Synopsis
int ARSetField( ARControlStruct ARNameType ARInternalId ARNameType unsigned int unsigned int ARValueStruct ARPermissionList ARFieldLimitStruct ARDisplayInstanceList char ARNameType char ARStatusList Input Arguments control *control, schema, fieldId, fieldName, *option, *createMode, *defaultVal, *permissions, *limit, *dInstanceList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema containing the field to update. The internal ID of the field to update. The new name for the field. The names of all fields and VUIs associated with a given schema must be unique. Specify NULL for this parameter if you do not want to change the name of the field.
schema fieldId fieldName
Functions 6-161
option
A flag indicating whether users must enter a value in the field.

1: 2: 3: 4:
Required (data fields only) (AR_FIELD_OPTION_REQUIRED). Optional (data fields only) (AR_FIELD_OPTION_OPTIONAL). System (core data fields only) (AR_FIELD_OPTION_SYSTEM). Display-only (nondata fields only) (AR_FIELD_OPTION_DISPLAY).
Specify NULL for this parameter if you do not want to change this flag.
createMode
A flag indicating the permission status for the field when users submit entries. This parameter is ignored for display-only fields.
1:
2:
Any user (including guest users) can enter data in the field when submitting (AR_FIELD_OPEN_AT_CREATE). Only users who have been granted permission can enter data in the field when submitting (AR_FIELD_PROTECTED_AT_CREATE).
Specify NULL for this parameter if you do not want to change this flag.
defaultVal
The value to apply if a user submits an entry with no field value (applicable for data fields only). The default value can be as many as 255 bytes in length (limited by AR_MAX_DEFAULT_SIZE) and must be of the same data type as the field. Specify 0 (AR_DEFAULT_VALUE_NONE) for trim and control fields or to assign no default. Specify NULL for this parameter if you do not want to change the default value. A list of zero or more groups who can access this field. Specifying an empty permission list defines a field accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. The permission value you assign for each group determines whether users in that group can modify the field.
1: 2:
permissions
Users can view but not modify the field (AR_PERMISSIONS_VIEW). Users can view and modify the field (AR_PERMISSIONS_CHANGE).
The permission list you specify replaces all existing group privileges. Specify NULL for this parameter if you do not want to change the permissions.
limit
The value limits for the field and other properties specific to the fields type. See the ARFieldLimitStruct definition in ar.h to find the contained structure that applies to the type of field you are modifying. The limits and properties you assign must be of the same data type as the field. Specify 0 (AR_FIELD_LIMIT_NONE) for trim and control fields or if you do not want to assign any limits or field type-specific properties. Specify NULL for this parameter if you do not want to change the field limits and properties.
6-162
ARSetField
dInstanceList
A list of zero or more display properties to associate with the field. See ARCreateField on page 6-19 for a description of the possible values. You can define both properties common to all schema views (VUIs) and display properties specific to particular views. The system includes the field in each view you specify, regardless of whether you define any display properties for those views. If you do not specify a property for a particular view, the system uses the default value (if defined). Specify a list with zero items if you want to remove all display properties for the field. Specify NULL for this parameter if you do not want to change this list. The help text associated with the field. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text. The owning user for the field. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the field. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
ARCreateField, ARDeleteField, ARGetField, ARGetListField, FreeARDisplayInstanceList, FreeARFieldLimitStruct, FreeARPermissionList, FreeARStatusList, FreeARValueStruct
See Also
Functions 6-163
ARSetFilter
Description ARSetFilter updates the filter with the indicated name on the specified server. The changes are added to the server immediately and returned to users who request information about filters.
Privileges
Synopsis
int ARSetFilter( ARControlStruct ARNameType ARNameType unsigned int ARNameType unsigned int unsigned int ARQualifierStruct ARFilterActionList ARFilterActionList char ARNameType char ARStatusList Input Arguments control *control, name, newName, *order, schema, *opSet, *enable, *query, *actionList, *elseList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the filter to update. The new name for the filter. The names of all filters on a given server must be unique. Specify NULL for this parameter if you do not want to change the name of the filter. A value between 0 and 1000 (inclusive) that determines the filter execution order. When multiple filters are associated with a schema, the value associated with each filter determines the order in which they are processed
name newName
order
6-164
ARSetFilter
(from lowest to highest). Specify NULL for this parameter if you do not want to change the order.
schema
The name of the schema the filter is linked to. The filter must be associated with a single schema that currently exists on the server. Specify NULL for this parameter if you do not want to change the schema. A bitmask indicating the schema operations that trigger the filter.
Bit 0: Bit 1: Bit 2: Bit 3: Bit 4:
opSet
Execute the filter on get operations (AR_OPERATION_GET). Execute the filter on set operations (AR_OPERATION_SET). Execute the filter on create operations (AR_OPERATION_CREATE). Execute the filter on delete operations (AR_OPERATION_DELETE). Execute the filter on merge operations (AR_OPERATION_MERGE).
Specify NULL for this parameter if you do not want to change the operation set.
enable
A flag to enable or disable this filter. A value of 0 disables the filter, causing its condition checks and associated actions not to be performed. A value of 1 enables the filter, causing its conditions to be checked for each schema operation specified by the opSet parameter. Specify NULL for this parameter if you do not want to change this flag. A qualification that determines whether the filter is executed. Assign an operation value of 0 (AR_COND_OP_NONE) to execute the filter unconditionally. Specify NULL for this parameter if you do not want to change the query. The set of actions performed if the condition defined by the query parameter is satisfied. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to change the action list. The set of actions performed if the condition defined by the query parameter is not satisfied. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify a list with zero items to define no else actions. Specify NULL for this parameter if you do not want to change the else list. The help text associated with the filter. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text. The owning user for the filter. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the filter. 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 user making the change and a
query
actionList
elseList
Functions 6-165
time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
ARCreateFilter, ARDeleteFilter, ARGetFilter, ARGetListFilter, FreeARFilterActionList, FreeARQualifierStruct, FreeARStatusList
See Also
6-166
ARSetFullTextInfo
ARSetFullTextInfo
Description ARSetFullTextInfo updates the indicated Full Text Search (FTS) information for the specified server.
Privileges
#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARSetFullTextInfo( ARControlStruct ARFullTextInfoList ARStatusList *control, *fullTextInfo, *status)
Synopsis
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, sessionId, and server fields are required. system returns error messages for FTS options not updated due to error.
fullTextInfo The information to update on the server (see FTS Options below). The
FTS Options AR_FULLTEXTINFO_CASE_SENSITIVE_SRCH:
A value indicating whether full text searches are case-sensitive. Valid values for this option are 0 (case-sensitive) and 1 (case-insensitive). The default value is 1 (case-insensitive).
AR_FULLTEXTINFO_COLLECTION_DIR:
The collection directory for the FTS engine. This directory contains all defined FTS indexes. This directory is not used if no fields are indexed for FTS.
Functions 6-167
AR_FULLTEXTINFO_FTS_MATCH_OP:
A value indicating the type of match operation used.

0:
1:
2: 3:
4:
Append leading and trailing wild cards to every word. This option produces the highest number of matches but causes the largest performance impact (AR_FULLTEXT_FTS_MATCH_FORCE_L_T_WILD). Truncate all leading wild cards and append trailing wild cards to every word. This option produces a reasonable number of matches while still being efficient (AR_FULLTEXT_FTS_MATCH_FORCE_T_WILD). Truncate all leading wild cards (do not truncate or append trailing wild cards) (AR_FULLTEXT_FTS_MATCH_IGNORE_L_WILD). Truncate all wild cards. This option is the most efficient match operation type but produces the lowest number of matches (AR_FULLTEXT_FTS_MATCH_REMOVE_WILD). Leave all wild cards as specified by the user. This option requires that users understand both how to use wild cards and their impact on performance (AR_FULLTEXT_FTS_MATCH_UNCHANGED).
AR_FULLTEXTINFO_REINDEX:
A value indicating whether the system rebuilds FTS indexes. Valid values for this option are 0 (no) and 1 (yes). The default value is 0 (do not rebuild).
AR_FULLTEXTINFO_STATE:
A value indicating whether FTS is enabled. Valid values for this option are 0 (off) and 1 (on). The default value is 1 (FTS on).
AR_FULLTEXTINFO_STOPWORD:
A structure that contains all defined words to ignore for the FTS collection.
See Also ARGetFullTextInfo, ARGetServerInfo, ARSetServerInfo, FreeARFullTextInfoList, FreeARStatusList
6-168
ARSetSchema
ARSetSchema
Description ARSetSchema updates the definition for the schema with the indicated name on the specified server.
Privileges
Synopsis
int ARSetSchema( ARControlStruct ARNameType ARNameType ARCompoundSchema ARPermissionList ARInternalIdList AREntryListFieldList ARSortList ARIndexList char ARNameType char ARStatusList Input Arguments control *control, name, newName, *schema, *groupList, *admingrpList, *getListFields, *sortList, *indexList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema to update. The new name for the schema. The names of all schemas on a given server must be unique. The system automatically updates all workflow references to the schema if you rename it. Specify NULL for this parameter if you do not want to change the name of the schema. The schema type (base schema or join schema). See ARCreateSchema on page 6-35 for a description of the possible values. You cannot change a join schema to a base schema or vice versa. You can, however, modify the join
name newName
schema
Functions 6-169
criteria for a join schema. Specify NULL for this parameter if you do not want to change the schema information.
groupList
A list of zero or more groups who can access this schema. Specifying an empty group list defines a schema accessible by users with administrator capability only. Specifying group ID 0 (Public) provides access to all users. The permission value you assign for each group determines whether users in that group see the schema in the schema list.
1: 2:
Users see the schema in the schema list (AR_PERMISSIONS_VISIBLE). Users do not see the schema in the schema list (AR_PERMISSIONS_HIDDEN).
The group list you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the group list.
admingrpList
A list of zero or more groups who can administer this schema (and the associated filters, escalations, and active links). Users must belong to both a specified group and the Subadministrator group to obtain these privileges. Specifying an empty administrator group list defines a schema that can be administered by users with administrator capability only. Specifying group ID 0 (Public) provides subadministrator capability to all members of the Subadministrator group. The group list you specify replaces all existing group permissions. Specify NULL for this parameter if you do not want to change the administrator group list. A list of zero or more fields that identifies the default query list data for retrieving schema entries. The combined length of all specified fields, including separator characters, can be as many as 128 bytes (limited by AR_MAX_SDESC_SIZE). Specify zero fields to assign the Short-Description core field as the default query list data. Specifying a getListFields argument when calling the ARGetListEntry function overrides the default query list data. Specify NULL for this parameter if you do not want to change the default query list fields. A list of zero or more fields that identifies the default sort order for retrieving schema entries. Specifying a sortList argument when calling the ARGetListEntry function overrides the default sort order. Specify NULL for this parameter if you do not want to change the default sort fields. The set of zero or more indexes to create for the schema. You can specify from 1 to 16 fields for each index (limited by AR_MAX_INDEX_FIELDS). Diary fields and character fields larger than 255 bytes cannot be indexed. Specify NULL for this parameter if you do not want to change the index list. The help text associated with the schema. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text.
getListFields
sortList
indexList
helpText
6-170
ARSetSchema
owner changeDiary
The owning user for the schema. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the schema. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
ARCreateField, ARCreateSchema, ARDeleteSchema, ARGetListEntry, ARGetListSchema, ARGetSchema, ARSetField, FreeARCompoundSchema, FreeAREntryListFieldList, FreeARIndexList, FreeARInternalIdList, FreeARPermissionList, FreeARSortList, FreeARStatusList
See Also
Functions 6-171
ARSetServerInfo
Description ARSetServerInfo updates the indicated configuration information for the
specified server.
Privileges
#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARSetServerInfo( ARControlStruct ARServerInfoList ARStatusList *control, *serverInfo, *status)
Synopsis
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, sessionId, and server fields are required. The information to update on the server (see Server Options below). The system returns error messages for server options not updated due to error.
serverInfo
Server Options AR_SERVER_INFO_ACTLINK_DIR:
The name of a directory where all external processes to be run by active links must reside. Specify NULL to allow active links to run processes located anywhere. The default value is NULL.
AR_SERVER_INFO_ACTLINK_SHELL:
The name of a shell to use when running external processes from an active link. Specify NULL to run processes from /bin/sh (UNIX) or without a shell (Windows NT). The default value is NULL.
6-172
ARSetServerInfo
AR_SERVER_INFO_ADMIN_ONLY
A flag specifying whether the server is in Administrator Only mode (1) or not (0). When not in Administrator Only mode, subadministrators can also perform administrator duties. The default value is 0 (Not in Administrator Only mode).
AR_SERVER_INFO_ADMIN_TCP_PORT
The TCP port that the administrator thread will use.

AR_SERVER_INFO_ALLOW_GUESTS:
A flag specifying whether the server accepts guest users. Guest users are users not registered with the AR System. If allowed, guest users have no permissions but are allowed to perform some basic operations. Guest users can submit entries to schemas for which permission has been given to the Public group and fields have been defined as allowing any user to submit. If not allowed, unregistered users have no access to the system. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 1 (allow guest users).
AR_SERVER_INFO_AP_DEFN_CHECK:
The length of time in seconds between checks by an application service to verify that definitions it is using from the AR System are correct. The value can be from 0 to 3600 seconds (1 hour). A value of 0 means to check definitions with each command. A larger value means a slight delay in recognizing changes to some definition, while a smaller value means the significant overhead of checking the definitions often. The default value is 300 seconds (5 minutes).
AR_SERVER_INFO_AP_LOG_FILE:
The name of the file to use if approval tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_AP_RPC_SOCKET:
The RPC program number the approval server will use when contacting the AR System. This allows you to define a specific AR System server for private use by the approval server.
AR_SERVER_INFO_API_LOG_FILE:
The name of the file to use if API tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_CACHE_LOG_FILE
The file name used for the cache log if shared cache tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
Functions 6-173
AR_SERVER_INFO_CLUSTERED_INDEX:
A value specifying whether a clustered index is created on the Entry ID field when a new schema is created. Specify 1 for this option to create a clustered index and 0 to create a unique index. The default value is 1 (clustered), but you can override this in the AR configuration file.
AR_SERVER_INFO_DB_PASSWORD:
The database password associated with the ARSystem database or tablespace (applicable for Sybase and Oracle databases only). The password is stored in encrypted form.
AR_SERVER_INFO_DBCONF:
The complete contents of the db.conf (ardb.cfg) file.

AR_SERVER_INFO_DEBUG_MODE:
A bitmask specifying the server debug modes.

Bit 0:
Bit 1:
Bit 2: Bit 3:
Bit 4:
Bit 5:
Bit 15:
Enables SQL tracing (applicable for SQL databases only). The default file for SQL tracing is arsql.log (see AR_SERVER_INFO_SQL_LOG_FILE). Enables filter tracing. The default file for filter tracing is arfilter.log (see AR_SERVER_INFO_FILTER_LOG_FILE). Enables user tracing. The default file for user tracing is aruser.log (see AR_SERVER_INFO_USER_LOG_FILE). Enables escalation tracing. The default file for escalation tracing is arescl.log (see AR_SERVER_INFO_ESCALATION_LOG_FILE). Enables API tracing. The default file for API tracing is arapi.log (see AR_SERVER_INFO_API_LOG_FILE). Enables thread tracing (Windows NT only). The default file for thread tracing is arthread.log (see AR_SERVER_INFO_THREAD_LOG_FILE). Enables distributed server tracing (applicable for Distributed Server Option only). The default file for distributed server tracing is ardist.log (see AR_SERVER_INFO_DS_LOG_FILE).
AR_SERVER_INFO_DELAYED_CACHE:
A flag specifying whether to disable recacheing of the shared cache after a time-out (1) or not (0). The default value is 0 (delayed recache not disabled).
AR_SERVER_INFO_DS_LOG_FILE:
The name of the file to use if distributed server tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
6-174
ARSetServerInfo
AR_SERVER_INFO_DSO_DEST_PORT
The TCP port that the distributed server option uses to communicate with the Action Request System server.
AR_SERVER_INFO_DS_RPC_SOCKET:
The specific server socket to use for the distributed server. Valid values for this option are 390600 and 390680 through 390694. Any other value causes the distributed server to use the default server.
AR_SERVER_INFO_EMAIL_FROM:
The sender name to use for filter-generated email notifications where no subject is specified. Only trusted email users can use this name (refer to your UNIX Sendmail documentation for more information about trusted users).
AR_SERVER_INFO_EMAIL_LINE_LEN:
The maximum line length of e-mail messages.

AR_SERVER_INFO_EMAIL_TIMEOUT:
(UNIX only) The length of time in seconds before the system closes the pipe to sendmail to unblock the AR System server. Valid values for this option are from 1 to 300. The default value is 10.
AR_SERVER_INFO_ESCALATION_LOG_FILE:
The name of the file to use if escalation tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_ESCL_DAEMON:
A flag specifying whether a private escalation daemon is running (requires a Multi-Processing Server license). Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 0 (private escalation daemon not running).
AR_SERVER_INFO_ESCL_TCP_PORT
The TCP port that the escalation thread will use.

AR_SERVER_INFO_FAST_TCP_PORT
The number of the port that the first of the fast servers will use. Each subsequent fast server will use the port with the next sequential number after the server before it.
AR_SERVER_INFO_FILT_MAX_TOTAL
The maximum number of filters that the server will execute for a given operation. The default value is 10000.
Functions 6-175
AR_SERVER_INFO_FILT_MAX_STACK
The maximum number of levels of recursion allowed for a given operation. The data modification performed by an AR_FILTER_ACTION_FIELDP filter action could trigger a second set, or level, of filters, one of which could trigger filters a third level down and so on. This option limits the number of times such recursion can happen, preventing the server crash that would occur if the recursion continued indefinitely. The default value is 25.
AR_SERVER_INFO_FILTER_LOG_FILE:
The name of the file to use if filter tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_FLASH_DAEMON
A flag indicating whether Flashboards is installed (1) or not (0). The default value is 1 if the server has one or more Flashboards licenses, and 0 if the server has no licenses.
AR_SERVER_INFO_FLASH_TCP_PORT

AR_SERVER_INFO_FLOAT_TIMEOUT:
The number of hours the server waits before disconnecting inactive users. If a user is holding a floating write license token, the system also frees the token at this time.
AR_SERVER_INFO_FTEXT_TIMEOUT:
The number of hours the server waits before disconnecting inactive users with Full Text licenses. If a user is holding a floating Full Text license token, the system also frees the token at this time.
AR_SERVER_INFO_LIST_TCP_PORT
The number of the port that the first of the list servers will use. Each subsequent list server will use the port with the next sequential number after the server before it.
AR_SERVER_INFO_MAX_ENTRIES:
The maximum number of entries returned by a single query. Because users can also specify the maximum number of entries returned (Query Preferences), the actual maximum is the lower of these two values. The default value is no (server-defined) maximum.
6-176
ARSetServerInfo
AR_SERVER_INFO_MAX_F_DAEMONS:
The maximum number of fast servers allowed (requires a MultiProcessing Server license). Fast servers perform short, nonblocking database operations. They do not perform database searches. Valid values for this option are 0 through 15. The default value is 0 (no fast servers).
AR_SERVER_INFO_MAX_L_DAEMONS:
The maximum number of list servers allowed (requires a Multi-Processing Server license). List servers perform blocking database operations, including database searches. These operations can result in short or long server blocks. Valid values for this option are 0 through 35. The default value is 0 (no list servers).
AR_SERVER_INFO_NFY_TCP_PORT
The TCP port that the Notifier server will use.

AR_SERVER_INFO_PS_RPC_SOCKET:
The RPC program number and port pairs the Private Servers will use. A value of 0 for the port means no port was specified.
AR_SERVER_INFO_REGISTER_PORTMAPPER:
A flag specifying whether to register with the portmapper (1) or not (0). The default value is 1.
AR_SERVER_INFO_SAVE_LOGIN:
A value specifying whether users must log in to client tools.

0: 1: 2:
Controlled by the user (default setting). Do not force login (controlled by the administrator). Force login (controlled by the administrator).
AR_SERVER_INFO_SERVER_NAME:
An alias server name that is always interpreted as the current server. The name is not fully qualified. For example, to specify the server alpha.remedy.com, use the value alpha. See also Server-Name in ar.conf.
AR_SERVER_INFO_SET_PROC_TIME:
The number of seconds the server waits before ending a set fields process that has not completed. Valid values for this option are 1 through 20. The default value is five seconds.
AR_SERVER_INFO_SQL_LOG_FILE:
The name of the file to use if SQL tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
Functions 6-177
AR_SERVER_INFO_SUBMITTER_MODE:
A value specifying whether the Submitter field can be changed and whether the submitter of an entry must have a license to modify it. In locked mode, the Submitter field cannot be changed after submit, and the submitter can modify the entry with or without a write license (if the Submitter group has change permission). In changeable mode, the Submitter field can be changed after submit, but the submitter must have a write license to modify the entry (if the Submitter group has change permission). Valid values for this option are 1 (locked) and 2 (changeable). The default value is 2 (changeable).
AR_SERVER_INFO_SUPPRESS_WARN:
A series of zero or more message numbers (separated by spaces) that identify the informational or warning messages that the system should suppress.
AR_SERVER_INFO_TCD_TCP_PORT
The TCP port that the TCD thread will use.

AR_SERVER_INFO_TCP_PORT

AR_SERVER_INFO_THREAD_LOG_FILE:
The name of the file to use if thread tracing is turned on (Windows NT only) (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_UNQUAL_QUERIES:
A flag specifying whether the server allows unqualified queries. Unqualified queries are ARGetListEntry calls in which the qualifier parameter is either NULL or has an operation value of 0 (AR_COND_OP_NONE). These queries can cause performance problems, especially for large schemas, because they return all entries for a given schema. If not allowed, you can return all schema entries by specifying a dummy qualification such as 1 = 1. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is1 (allow unqualified queries).
AR_SERVER_INFO_USE_ETC_PASSWD: A flag specifying whether the /etc/passwd file is used to validate users
not registered with the AR System (UNIX only). If so, users in /etc/passwd are considered valid users of the AR System and are assigned to a group identified by the UNIX group ID. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 1 (use password file).
6-178
ARSetServerInfo
AR_SERVER_INFO_USER_CACHE_UTILS: A flag specifying whether the ARCACHE and ARRELOAD utilities are disabled.
Specify 1 for this option to disable the utilities and 0 to enable them. The default value is 1 (ARCACHE and ARRELOAD disabled).
AR_SERVER_INFO_USER_LOG_FILE:
The name of the file to use if user tracing is turned on (see AR_SERVER_INFO_DEBUG_MODE).
AR_SERVER_INFO_XREF_PASSWORDS: A flag specifying whether the /etc/passwd file is cross-referenced if an AR
System user has no password (UNIX only). This option enables you to manage group membership and other support information by using the AR System but still manage passwords by using the /etc/passwd file. Valid values for this option are 1 (TRUE) and 0 (FALSE). The default value is 0 (blank passwords not cross-referenced).
See Also ar.conf file, ARGetFullTextInfo, ARGetServerInfo, ARSetFullTextInfo, FreeARServerInfoList, FreeARStatusList
Functions 6-179
ARSetServerPort
Description ARSetServerPort specifies the port that your program will use to communicate with the AR System server, and whether to use a private server.
Privileges Synopsis

#include "ar.h" #include "arerrno.h" #include "arextern.h" int ARSetServerPort( ARControlStruct ARNameType int int ARStatusList *control, name, port, progNum, *status)
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, sessionId, and server fields are required. The name of the server to update. The port number that your program will use to communicate with the AR System server. If you do not specify this parameter, your program will use the port number supplied by the TCD (when progNum specifies the admin server) or by the portmapper (when progNum specifies a private server or the TCD cannot supply a port number). When progNum does not specify a private server, this parameter specifies the TCD port. This parameter is overridden by the ARTCPPORT environment variable. The RPC program number of the server. Specify 390600 to use the admin server, a number from 390680 to 390694 to use a private server, or 0 (the default) to use the server number supplied by the TCD. If you specify 0 or 390600 for this parameter, the value specified for the port parameter is used as the TCD port and your program will use the port number supplied by the TCD. This parameter is overridden by the ARRPC environment variable.
name port
progNum
6-180
ARSetSupportFile
ARSetSupportFile
Description Privileges ARSetSupportFile sets a support file in the AR System.
Synopsis
int ARSetSupportFile ( ARControlStruct unsigned int ARNameType ARInternalId FILE ARStatusList Input Arguments control *control, fileType, name, fileId, *filePtr, *status)
The control record for the operation. It contains information about the user requesting the operation and where that operation is to be performed. The user and server fields are required. The numerical value for the type of file, and the type of object the file is related to. Specify 1 (AR_SUPPORT_FILE_EXTERNAL_REPORT) for an external report file associated with an active link. The name of the object the file is associated with, usually a schema. The unique identifier of a file within its object. A pointer to the support file to be set in the system. If you are using Windows, you must open the file in binary mode.
fileType
name fileId filePtr
ARCreateActiveLink, ARCreateSupportFile, ARDeleteActiveLink, ARDeleteSupportFile, ARGetActiveLink, ARGetListSupportFile, ARGetSupportFile, ARSetActiveLink
See Also
Functions 6-181
ARSetVUI
Description ARSetVUI updates the schema view (VUI) with the indicated ID on the specified server.
Privileges
Synopsis
int ARSetVUI( ARControlStruct ARNameType ARInternalId ARNameType ARPropList char ARNameType char ARStatusList Input Arguments control *control, schema, vuiId, vuiName, *dPropList, *helpText, owner, *changeDiary, *status)
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, sessionId, and server fields are required. The name of the schema containing the VUI to update. The internal ID of the VUI to update. The new name for the VUI. The names of all VUIs and fields associated with a given schema must be unique. Specify NULL for this parameter if you do not want to change the name of the VUI. A list of zero or more display properties to associate with the VUI. See ARCreateVUI on page 6-40 for a description of the possible values. Specify 0 (AR_DPROP_NONE) to assign no display properties. Specify NULL for this parameter if you do not want to change this list. The help text associated with the VUI. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text.
schema vuiId vuiName
dPropList
helpText
6-182
ARSetVUI
owner changeDiary
The owning user for the VUI. Specify NULL for this parameter if you do not want to change the owner. The additional change diary text to associate with the VUI. 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 user making the change and a time stamp are added when the change diary is saved. Specify NULL for this parameter if you do not want to add to the change diary.
ARCreateVUI, ARDeleteVUI, ARGetVUI, ARGetListVUI, FreeARPropList, FreeARStatusList
See Also
Functions 6-183
ARTermination
Description ARTermination performs environment-specific cleanup routines and disconnects from the specified Action Request System session. All API programs that interact with the AR System should call this function upon completing work in a given session. Calling this function is especially important in environments that use floating licenses. If you do not disconnect from the server, your license token is unavailable for other users for the defined time-out interval.
Privileges Synopsis

int ARTermination( ARControlStruct ARStatusList Input Arguments control *control, *status)
ARInitialization, FreeARStatusList
See Also
6-184
ARVerifyUser
ARVerifyUser
Description ARVerifyUser checks the cache on the specified server to determine whether the user you specify for the control parameter is registered in the AR System.
Privileges Synopsis

int ARVerifyUser( ARControlStruct ARBoolean ARBoolean ARBoolean ARStatusList Input Arguments control *control, *adminFlag, *subAdminFlag, *customFlag, *status)
Return Values adminFlag
A flag indicating whether the specified user is a member of the Administrator group. The system returns 0 (FALSE) if the user is invalid or unknown. Specify NULL for this parameter if you do not want to retrieve this flag. A flag indicating whether the specified user is a member of the Subadministrator group. The system returns 0 (FALSE) if the user is invalid or unknown. Specify NULL for this parameter if you do not want to retrieve this flag. A flag indicating whether the specified user is a member of the Customize group. The system always returns 1 (TRUE) if the user is a member of the Administrator group. The system returns 0 (FALSE) if the user is invalid or unknown. Specify NULL for this parameter if you do not want to retrieve this flag. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
subAdminFlag
customFlag
status
Functions 6-185
If a user is known but the password is invalid, the system returns message 329 (AR_ERROR_PASSWORD_MISMATCH). If a user is unknown but guest users are allowed, the system returns message 59 (AR_WARN_NO_SUCH_USER). If a user is unknown and guest users are not allowed, the system returns message 612 (AR_ERROR_NO_SUCH_USER). Note: For information about the Administrator, Subadministrator, and Customize reserved groups, see the Action Request System Administrators Guide, Volume 1.
See Also
FreeARStatusList
6-186
FreeAR
FreeAR
Description
The FreeAR functions recursively free all allocated memory associated with a particular AR System data structure. All structure components must be in allocated memory to use these functions. This operation can be performed by all users.
#include "ar.h" #include "arfree.h" void FreeARActiveLinkActionList( ARActiveLinkActionList ARBoolean *value, freeStruct)
Privileges Synopsis
void FreeARActiveLinkActionStruct( ARActiveLinkActionStruct ARBoolean void FreeARArithOpAssignStruct( ARArithOpAssignStruct ARBoolean void FreeARArithOpStruct( ARArithOpStruct ARBoolean void FreeARAssignFieldStruct( ARAssignFieldStruct ARBoolean void FreeARAssignSQLStruct( ARAssignSQLStruct ARBoolean void FreeARAssignStruct( ARAssignStruct ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
Functions 6-187
void FreeARAttachStruct( ARAttachStruct ARBoolean void FreeARBooleanList( ARBooleanList ARBoolean void FreeARBooleanMatrix( ARBooleanMatrix ARBoolean void FreeARByteList( ARByteList ARBoolean void FreeARCharMenuItemStruct( ARCharMenuItemStruct ARBoolean void FreeARCharMenuList( ARCharMenuList ARBoolean void FreeARCharMenuStruct( ARCharMenuStruct ARBoolean void FreeARCompoundSchema( ARCompoundSchema ARBoolean void FreeARContainerInfoList( ARContainerInfoList ARBoolean void FreeARCoordList( ARCoordList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
6-188
FreeAR
void FreeARDDEStruct( ARDDEStruct ARBoolean void FreeARDiaryList( ARDiaryList ARBoolean void FreeARDisplayInstanceList( ARDisplayInstanceList ARBoolean void FreeARDisplayList( ARDisplayList ARBoolean void FreeAREntryIdList( AREntryIdList ARBoolean void FreeAREntryIdListList( AREntryIdListList ARBoolean void FreeAREntryListFieldList( AREntryListFieldList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
void FreeAREntryListFieldValueList( AREntryListFieldValueList ARBoolean void FreeAREntryListList( AREntryListList ARBoolean void FreeARFieldAssignList( ARFieldAssignList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct)
Functions 6-189
void FreeARFieldAssignStruct( ARFieldAssignStruct ARBoolean void FreeARFieldLimitStruct( ARFieldLimitStruct ARBoolean void FreeARFieldValueList( ARFieldValueList ARBoolean void FreeARFieldValueListList( ARFieldValueListList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
void FreeARFieldValueOrArithStruct( ARFieldValueOrArithStruct ARBoolean void FreeARFieldValueStruct( ARFieldValueStruct ARBoolean void FreeARFilterActionList( ARFilterActionList ARBoolean void FreeARFilterActionStruct( ARFilterActionStruct ARBoolean void FreeARFullTextInfoList( ARFullTextInfoList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
void FreeARFullTextInfoRequestList( ARFullTextInfoRequestList ARBoolean *value, freeStruct)
6-190
FreeAR
void FreeARFunctionAssignStruct( ARFunctionAssignStruct ARBoolean void FreeARGroupInfoList( ARGroupInfoList ARBoolean void FreeARIndexList( ARIndexList ARBoolean void FreeARInternalIdList( ARInternalIdList ARBoolean void FreeARLocStruct( ARLocStruct ARBoolean void FreeARNameList( ARNameList ARBoolean void FreeARPermissionList( ARPermissionList ARBoolean void FreeARPropList( ARPropList ARBoolean void FreeARPropStruct( ARPropStruct ARBoolean void FreeARPushFieldsList( ARPushFieldsList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
Functions 6-191
void FreeARQualifierStruct( ARQualifierStruct ARBoolean void FreeARReferenceList( ARReferenceList ARBoolean void FreeARRelOpStruct( ARRelOpStruct ARBoolean void FreeARServerInfoList( ARServerInfoList ARBoolean void FreeARServerInfoRequestList( ARServerInfoRequestList ARBoolean void FreeARServerNameList( ARServerNameList ARBoolean void FreeARSortList( ARSortList ARBoolean void FreeARSQLStruct( ARSQLStruct ARBoolean void FreeARStatisticsResultList( ARStatisticsResultList ARBoolean void FreeARStatusHistoryList( ARStatusHistoryList ARBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
6-192
FreeAR
void FreeARStatusList( ARStatusList ARBoolean void FreeARStructItemList( ARStructItemList ARBoolean void FreeARUserInfoList( ARUserInfoList ARBoolean void FreeARUserLicenseList( ARUserLicenseList ARBoolean void FreeARValueList( ARValueList ARBoolean void FreeARValueListList( ARValueListList ARBoolean void FreeARValueStruct( ARValueStruct ARBoolean Input Arguments value freeStruct *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
A pointer to the structure you want to free. The system performs no operation if the structure is a list with zero items or you specify NULL for this parameter. A flag indicating whether you need to free the top-level structure. If you allocated memory for the top-level structure, specify 1 (TRUE) to free both the structure and its contents. If you used a stack variable for the top-level structure, specify 0 (FALSE) to free only the contents of the structure.
Functions 6-193
FreeNT
Description
The FreeNT functions recursively free all allocated memory associated with a particular Remedy Notifier data structure. All structure components must be in allocated memory to use these functions. This operation can be performed by all users.
#include "nt.h" #include "ntfree.h" void FreeNTNameList( NTNameList NTBoolean void FreeNTNotification( NTNotification NTBoolean void FreeNTServerNameList( NTServerNameList NTBoolean void FreeNTStatusList( NTStatusList NTBoolean *value, freeStruct) *value, freeStruct) *value, freeStruct) *value, freeStruct)
Privileges Synopsis
Input Arguments value freeStruct
A pointer to the structure you want to free. The system performs no operation if the structure is a list with zero items or you specify NULL for this parameter. A flag indicating whether you need to free the top-level structure. If you allocated memory for the top-level structure, specify 1 (TRUE) to free both the structure and its contents. If you used a stack variable for the top-level structure, specify 0 (FALSE) to free only the contents of the structure.
6-194
NTDeregisterServer
NTDeregisterServer
Description NTDeregisterServer cancels registration for the specified user on the specified Remedy Notifier server and port. After calling NTRegisterServer, your program should continue monitoring the socket for as long as it needs to receive notifications.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTDeregisterServer( char NTNameType NTNameType NTPortAddr NTStatusList *serverHost, user, password, *clientPort, *status)
Input Arguments serverHost user password clientPort
The host name of the Remedy Notifier server machine. The name of the user canceling registration. The system deletes the user from the active list and stops delivering notifications for this user. The password of the user canceling registration. The password is used to verify that the user is registered with the Remedy Notifier server. The TCP port on the Remedy Notifier server being used by this instance of the specified user name. A user can register with the same server multiple times by specifying different port numbers.
NTRegisterServer, FreeNTStatusList
See Also
Functions 6-195
NTGetListServer
Description NTGetListServer retrieves the list of available Remedy Notifier servers defined in the ar directory file. Remedy User, Remedy Administrator, Remedy Notifier, and Remedy Import connect to these servers automatically if no servers are specified at startup. If the ar file is under NIS control, the system uses the file specified by the NIS map instead of the local ar file. For information about the ar file, see the Action Request System Administrators Guide, Volume 2.
Privileges
This operation can be performed by all users. Note: In the Windows NT API, server information is retrieved from the registry instead of the ar file. API programs that run on the server (for example, through a filter or escalation) can use this function to retrieve the list of available servers. Programs that run on the client, however, cannot. In this case, the function always returns a list of zero servers.
Synopsis
#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTGetListServer( NTServerNameList NTStatusList *serverList, *status)
Return Values serverList status
A list of zero or more registered Remedy Notifier servers. The system returns a list with zero items if no servers are registered. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
ar directory file, FreeNTServerNameList, FreeNTStatusList
See Also
6-196
NTGetListUser
NTGetListUser
Description NTGetListUser retrieves a list of all users on the specified Remedy Notifier
server.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int ARGetListUser( char NTNameList NTStatusList *serverHost, *userList, *status)
Input Arguments serverHost Return Values userList status
The host name of the Remedy Notifier server machine.
A list of zero or more user names registered on the specified server. The system returns a list with zero items if no users are registered on the server. A list of zero or more notes, warnings, or errors generated from the function call (see Error Checking on page 4-9 for a description of all possible values).
FreeNTNameList, FreeNTStatusList
See Also
Functions 6-197
NTGetTextForErrorMessage
Description NTGetTextForErrorMessage retrieves the message text for the specified error from the local catalog (in the local language). The length of the text is limited by NT_MAX_MESSAGE_SIZE (256 bytes).
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" char * NTGetTextForErrorMessage ( int msgId)
Input Arguments msgId
The error number whose message text you want to retrieve. This number is provided in the messageNum member of NTStatusStruct.
Return Values return
The function return value is a pointer to the retrieved message text. You must free this memory after calling this function.
6-198
NTInitializationServer
NTInitializationServer
Description NTInitializationServer performs server- and network-specific initialization operations for connecting to a Remedy Notifier server. In some environments, this function performs no work, but for maximum portability, all API programs that interact with a Remedy Notifier server should call this function at startup.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTInitializationServer( NTStatusList *status)
NTTerminationServer, FreeNTStatusList
See Also
Functions 6-199
NTNotificationServer
Description NTNotificationServer forwards a notification for the indicated user to the specified Remedy Notifier server. The server delivers the notification to the registered client machine for that user.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTNotificationServer( char NTNameType char int char NTStatusList *serverHost, user, *notifyText, notifyCode, *notifyCodeText, *status)
Input Arguments serverHost user
The host name of the Remedy Notifier server machine. The name of the user the notification is for. Specify * (NT_REGISTERED_BROADCAST) to send the notification to all users currently accessing the Remedy Notifier server. Broadcast notifications are not stored in the ntserver.log file for later delivery to users not currently connected. The notification text. A value identifying the notification source. The system does not generate this code automatically.
1: 2: 5:
notifyText notifyCode
Notification from the Remedy Notifier server. Notification from the AR System. Notification from Flashboards.
notifyCodeText
The text associated with the notification source (see Notification Formats below). Specify NULL for this parameter if you do not want to associate additional text with the notification.
6-200
NTNotificationServer
Notification Formats
Remedy Notifier A character string containing additional notification details. This text usually includes one or more error messages with information about the problem that triggered the notification. AR System A formatted character string identifying the schema entry that triggered the notification (fixed-size fields).
Entry-Id: Schema: Server:
The ID of the entry (padded to AR_MAX_ENTRYID_SIZE). Join schemas will have multiple Entry IDs. The name of the schema containing the entry (padded to AR_MAX_NAME_SIZE). The name of the server where the schema is located.
Flashboards
A formatted character string identifying the flashboard alert that triggered the notification (fields delimited by colons). Colons or backslashes embedded in the data must be preceded by a backslash. The name of the server where the flashboard is located. Flashboard: The name of the flashboard containing the alert. Alert: The name of the alert.
Server:
See Also
NTDeregisterServer, NTRegisterServer, FreeNTStatusList
Functions 6-201
NTRegisterServer
Description NTRegisterServer registers the indicated user on the specified Remedy Notifier server. The server delivers all notifications for this user to the registered client machine.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTRegisterServer( char NTNameType NTNameType unsigned int NTPortAddr unsigned int NTBoolean NTStatusList *serverHost, user, password, clientCommunication, clientPort, protocol, multipleClients, *status)
Input Arguments serverHost user password
The host name of the Remedy Notifier server machine. The name of the user registering to receive notifications. The system registers the current client machine as the delivery location for this user. The password of the user registering to receive notifications. The password is used to verify that the user is registered with the Remedy Notifier server. A value indicating the communication mechanism between client and server. Specify 2 (NT_CLIENT_COMMUNICATION_SOCKET) for this parameter (the only option currently supported). The specific TCP port being used by Remedy Notifier. A value indicating the communication protocol being used on the client machine. Specify 1 (NT_PROTOCOL_TCP) for this parameter (only option currently supported). A flag indicating whether the client machine can run multiple instances of Remedy Notifier. Specify 1 (TRUE) for UNIX clients. Specify 0 (FALSE) for Windows or Macintosh clients.
clientCommunication
clientPort protocol
multipleClients
6-202
NTRegisterServer
NTDeregisterServer, FreeNTStatusList
See Also
Functions 6-203
NTSetServerPort
Description NTSetServerPort specifies the port that your program will use to communicate with the Remedy Notifier server.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTSetServerPort( NTNameType int NTStatusList name, port, *status)
Input Arguments name port
The name of the server to update. The port number that your program will use to communicate with the AR System server. If you do not specify this parameter, your program will use the port number supplied by the portmapper. This parameter is overridden by the NTTCPPORT environment variable.
NTDeregisterServer, NTRegisterServer
See Also
6-204
NTTerminationServer
NTTerminationServer
Description NTTerminationServer performs environment-specific cleanup routines and disconnects from the Notification System. In some environments, this function performs no work, but for maximum portability, all API programs that interact with a Remedy Notifier server should call this function before completing.
Privileges Synopsis

#include "nt.h" #include "nterrno.h" #include "ntsextrn.h" int NTTerminationServer( NTStatusList *status)
NTInitializationServer, FreeNTStatusList
See Also
Functions 6-205
6-206
Appendix A Controlling Remedy User with OLE Automation
This appendix describes the OLE interfaces supported by Remedy User. It assumes you already have a working knowledge of Microsoft OLE Automation programming. For more information on OLE programming, see Microsofts website (www.microsoft.com).
Overview
Remedy User for Windows is a Microsoft Object Linking and Embedding (OLE) Automation server, exposing its basic functionality to OLE Automation clients located on the same machine. This functionality includes the ability to open a form, perform create, search, and modify operations, get and set field values and properties, open a guide, and run a macro. You can write client applications that control Remedy User in the foreground, using it for display and user interaction. You can also write client applications that control Remedy User in the background, bypassing its display and user interaction. However, if any workflow opens additional windows they will be visible. Your client application can launch a new instance of Remedy User or connect to an instance that is already running. It can also connect to a running AR System application (an instance of Remedy User that manages a prescribed set of forms), but cannot launch one. Unless otherwise specified for an interface, your client application can both get and set the interface objects properties. As with the API, the AR System
Controlling Remedy User with OLE Automation
A-1
permissions you have when making a OLE Automation call are those of the user logged in to the session you use. Note: Remedy Users OLE Automation capabilities are meant to be used by a client program on the same machine and is a supported feature in a Component Object Model (COM) environment, but not in a Distributed Component Object Model (DCOM) environment.
Data Types
You should include the type library file aruser.tlb in your project so that your client application can access Remedy Users OLE Automation interfaces. The file is installed in the same folder as Remedy User executable file, aruser.exe.
To include the type library in a Visual Basic project 1. Choose Projects References. 2. Click Browse, and select aruser.tlb, located in the same folder as Remedy User. 3. Click Open. The type library appears as ARUSER in the References dialog. 4. Click the checkbox next to ARUSER to enable the reference.
To include the type library in a Visual C++ project using MFC 1. Choose View ClassWizard. 2. Choose From a Type Library from the Add Class menu. 3. Select all of the available classes, and click OK. This creates the aruser.h header file and includes it in your project.
A-2
Errors
Errors
When a call to one of its OLE Automation interfaces is unsuccessful, Remedy User returns an appropriate error code. Your client application should implement error-handling routines to catch and display the error such as preceding your OLE calls with On Error statements (Visual Basic) or encapsulating the calls with Try and Catch statements (C++).
Sample Program
The following sample program demonstrates some common Remedy User OLE Automation calls, providing a user interface that lets a user search the Group form with a combination of query-by-example and a search string. The program was coded in Microsoft Visual Basic 5.0. Form1, the search form, has query-by-example fields for Group Name, Group Type, and Long Group Name, a search string field, and a results field. One button clears the search and the other performs it. Form2, the login form, has user and password fields and an OK button. The code portion of both forms is included here. Warning: This sample is supplied as is. There is no expressed or implied support for this sample from Remedy Corporation. Trouble-free operation is not guaranteed because there is no expressed or implied testing or validation that has been performed on the sample provided.
A-3
Form1
This is the startup form.
GroupName TypeCombo LongName QueryString
ResultList
DoQueryBtn ClrQueryBtn
Figure 6-1
Sample Form1
Public App As COMAppObj Public ARForm As ICOMFormWnd Public NameField As ICOMField, TypeField As ICOMField, LongNameField As ICOMField Public EntryList As ICOMQueryResultSet Public sessionId As Long Public user As String, Password As String Public LoginForm As Form Private Sub Form_Load() Dim gotDefaultSession As Boolean Dim terminateString As String Initialization Set LoginForm = Form2 sessionId = 0
A-4
Form1
terminateString = Chr(10) & Chr(13) & "Program will be terminated" See if we can connect to an already running instance of Remedy User. If not, we will try to launch a new instance. On Error GoTo LaunchTheApp Set App = GetObject(, "Remedy.User") GoTo ContinueLoading LaunchTheApp: On Error GoTo ErrorHandler Set App = New COMAppObj ContinueLoading: Test if we need to login. When Remedy User comes up, it will not have a valid session if the users option is to prompt for login. On Error GoTo ErrorHandler gotDefaultSession = App.HasDefaultSession If gotDefaultSession = False Then LoginForm.Show vbModal, Me sessionId = App.Login(user, Password, False) MsgBox ("Login succeeded!") End If On Error GoTo ErrorHandler Set ARForm = App.OpenForm(sessionId, "My_AR_Server", "Group", ARQuery, False) Set NameField = ARForm.GetField("Group Name") Set TypeField = ARForm.GetField("Group Type") Set LongNameField = ARForm.GetField("Long Group Name") Exit Sub ErrorHandler: AutomationError = "Automation Error: " & Hex(Err.Number) & " " & Err.Description MsgBox (AutomationError & terminateString) Err.Clear End terminate program End Sub Private Sub DoQueryBtn_Click() Dim entryStr As String Set the fields values first On Error GoTo SetFieldError NameField.Value = GroupName.Text TypeField.Value = TypeCombo.Text LongNameField.Value = LongName.Text Clear the result list first ResultList.Clear ResultList.Refresh
A-5
Do the query now On Error GoTo QueryError Set EntryList = ARForm.Query(QueryString.Text) If EntryList.Count = 0 Then MsgBox ("No matches found") Else: fill in the list box. For i = 1 To EntryList.Count entryStr = EntryList.Item(i).entryId & " " & EntryList.Item(i).Description ResultList.AddItem (entryStr) Next End If Exit Sub SetFieldError: MsgBox ("Set fields value Error: " & Hex(Err.Number) & " " & Err.Description) Err.Clear Exit Sub QueryError: MsgBox ("Query Error: " & Hex(Err.Number) & " " & Err.Description) Err.Clear End Sub Private Sub ClrQueryBtn_Click() GroupName.Text = "" TypeCombo.Clear TypeCombo.AddItem ("None") TypeCombo.AddItem ("View") TypeCombo.AddItem ("Change") LongName.Text = "" QueryString.Text = "" ResultList.Clear End Sub Private Sub Form_Unload(cancel As Integer) Clean up before exiting Set App = Nothing Set ARForm = Nothing Set NameField = Nothing Set TypeField = Nothing Set LongNameField = Nothing Set EntryList = Nothing cancel = 0 End Sub
A-6
Form2
Form2
This form is displayed when the user needs to log in.
UserName Password OKBtn
Figure 6-2
Private Sub OKBtn_Click() UserName.Refresh Password.Refresh Form1.user = UserName.Text Form1.Password = Password.Text Me.Hide End Sub
Sample Form2
A-7
ICOMAppObj
The ICOMAppObj object is the root object of Remedy Users OLE hierarchy. You use it to establish a session and to access form entries. You should explicitly log out of sessions you create to permit proper resource cleanup. You create an ICOMAppObj object in several different ways, depending on your programming environment and whether you are launching a new instance of Remedy User or connecting with either a running instance of Remedy User or an AR System application. To launch a new instance, call the function in your environment that creates and returns a reference to a Microsoft Component Object Model (COM) object. To connect with a running instance, call the function in your environment that gets a reference to a COM object. In both cases, pass Remedy.User as the ProgID. To connect with a running AR System application, call the function in your environment that gets a reference to a COM object. For the ProgID, pass the full path to Remedy Users .exe file with the application name and the server name appended to it.
Properties
None.
A-8
Login
Login
Description
Establishes a user session. An OLE client can omit this call to instead use the existing session. A newly launched instance of Remedy User will have an existing session only if the Preferences are not set to always prompt for login.
sessionID = Login(name, password, visiblePrompt) char char long long
Synopsis
*name; *password;
visiblePrompt; *sessionID;
Input Arguments name password
The user to log in for this session. The users password. desktop user.
visiblePrompt A code specifying whether errors will (1) or will not (0) be displayed to the
Return Values sessionID See Also
The ID of the session established.

Logout
A-9
Logout
Description
Terminates the session with the specified ID. An OLE client cannot terminate a session established by the desktop user. An OLE client also cannot terminate the default session even if it established the session.
Logout(sessionID) long
Synopsis
*sessionID;
Input Arguments sessionID See Also
The ID of the session to terminate.

Login
A-10
GetServerList
GetServerList
Description Synopsis
Returns the available server names for the specified session.

retVal = GetServerList(sessionId) long variant sessionId;
*retVal;
Input Arguments sessionId
The ID of the session for which to find available servers. Specify 0 for this parameter to use the current session.
Return Values retVal See Also
An array containing the list of available servers.

GetFormList, ICOMFormWnd::GetServerName
A-11
GetFormList
Returns the available form names for the specified session and server.
retVal = GetFormList(sessionId, serverName) long char variant sessionId;
*serverName; *retVal;
Input Arguments sessionId serverName Return Values retVal See Also
The ID of the session for which to find available forms. Specify 0 for this parameter to use the current session. The name of the server on which to find available forms.
An array containing the list of available forms.

GetServerList, ICOMFormWnd::GetFormName, OpenForm
A-12
OpenForm
OpenForm
Description
Return an ICOMFormWnd interface to search or save entries in the specified form.

retVal = OpenForm(sessionId, server, form, mode, visible) long char char long long ICOMFormWnd sessionId;
Synopsis
*server; *form;
mode; visible; *retVal;
Input Arguments sessionId server form mode visible
The ID of the session for which to open the form. Specify 0 for this parameter to use the current session. The name of the server on which to open the form. The name of the form to open. A flag identifying whether to open the form in search (1) or save (2) mode. A flag identifying whether the form should be opened invisible (0) or visible (1). If the form is visible, the desktop user must dismiss any dialogs that appear before your OLE client can regain control.
A reference to the form window that was opened.

GetFormList, ICOMFormWnd::GetFormName
A-13
LoadForm
Description
Return an ICOMFormWnd interface to display or modify an entry in the specified form.

retVal = LoadForm(sessionId, server, form, entryId, mode, visible) long char char char long long ICOMFormWnd sessionId;
Synopsis
*server; *form; *entryId;

mode; visible; *retVal;
Input Arguments sessionId server form entryId mode visible
The ID of the session for which to open the form. Specify 0 for this parameter to use the current session. The name of the server on which to open the entry. The name of the form containing the entry. The Entry ID of the entry to open. A flag identifying whether to open the form for display (3) or modify (4). A flag identifying whether the entry should be opened invisible (0) or visible (1). If the entry is visible, the desktop user must dismiss any dialogs that appear before your OLE client can regain control.
A reference to the entry window that was opened.

OpenForm, ICOMFormWnd::GetFormName
A-14
GetActiveForm
GetActiveForm
Description
Return an ICOMFormWnd interface to the currently active form on the desktop, if one exists.
retVal = GetActiveForm() ICOMFormWnd
Synopsis
*retVal;
A reference to the current entry window.

LoadForm, OpenForm
A-15
HasDefaultSession
Return a flag indicating whether a session is currently active.

retVal = HasDefaultSession() long
*retVal;
Return Values retVal
A flag indicating whether a session is (1) or is not (0) active in the ICOMAppObj object.
Login, Logout, GetServerList
See Also
A-16
OpenGuide
OpenGuide
Open the specified guide on the specified server.

OpenGuide(sessionId, guideName, serverName) long char char sessionId;
*guideName; *serverName;
Input Arguments sessionId guideName serverName See Also
The ID of the session for which to open the guide. Specify 0 for this parameter to use the current session. The name of the guide to open. The name of the server on which to open the guide.
OpenForm
A-17
RunMacro
Description
Run the specified macro, substituting the specified parameters. The macro is run in visible mode. If you run this method against an invisible instance of Remedy User, it will be made visible to the desktop user. If Remedy User is visible but minimized, its window will be brought to the foreground. The desktop user must dismiss any dialogs triggered by the macro before your OLE client can regain control.
RunMacro(sessionId, macroName, parmCount, parmList) long char long variant sessionId;
Synopsis
*macroName;
parmCount;
*parmList;
Input Arguments sessionId macroName parmCount parmList
The ID of the session for which to run the macro. Specify 0 for this parameter to use the current session. The name of the macro to run. Remedy User must have this macro in its search path. The number of parameters in parmList. A list of parameters to pass to the macro, in the form of a variable-length array of strings. Each string is in the format parameter=value.
A-18
ICOMFormWnd
ICOMFormWnd
The ICOMFormWnd interface represents a form window in one of four modes. You use it to create, search, display, or modify entries.
Properties
None.
A-19
Submit
Description
Save a new entry to the current form. Field values are taken from the currently open form window.
pEntryId = Submit() char
Synopsis
*pEntryId;
Return Values pEntryId
The Entry ID of the new entry. This parameter is only returned if the operation was successful.
Modify, Close, MakeVisible, Query
See Also
A-20
Modify
Modify
Description
Modify the current entry. Field values are taken from the currently open form window.
Modify() Submit, Close, MakeVisible, Query
Synopsis See Also
A-21
Close
Description
Close the current form. If the window is visible, this method cannot be performed. Only the desktop user can close visible windows.
Close() Submit, Modify, MakeVisible, Query
Synopsis See Also
A-22
MakeVisible
MakeVisible
Description
Make a hidden form window visible. This method has no effect on a window that is already visible. If the window is visible, the desktop user must dismiss any dialogs that appear before your OLE client can regain control.
MakeVisible() Submit, Modify, Close, Query
Synopsis See Also
A-23
GetField
Returns an ICOMField instance referencing the field with the specified name.
retVal = GetField(field) char ICOMField
*field; *retVal;
Input Arguments field Return Values retVal See Also
The name of the field you want a reference to.
A reference to the field.

GetFieldById, GiveFieldFocus, GiveFieldFocusById, ICOMField::Value
A-24
GetFieldById
GetFieldById
Returns an ICOMField instance referencing the field with the specified ID.
retVal = GetFieldById(fieldId) long ICOMField fieldId;
*retVal;
Input Arguments fieldId Return Values retVal See Also
The ID of the field you want a reference to.
A reference to the field.

GetField, GiveFieldFocus, GiveFieldFocusById, ICOMField::Value
A-25
GiveFieldFocus
Sets the input focus to the field with the specified name.
GiveFieldFocus(field) char field;
Input Arguments field See Also
The name of the field to receive the input focus.

GiveFieldFocusById, GetField, GetFieldById, ICOMField::Value
A-26
GiveFieldFocusById
GiveFieldFocusById
Sets the input focus to the field with the specified ID.
GiveFieldFocusById(fieldId) long fieldId;
Input Arguments fieldId See Also
The ID of the field to receive the input focus.

GiveFieldFocus, GetField, GetFieldById, ICOMField::Value
A-27
Query
Description
Perform the specified search against the current form with the current session.
retVal = Query(queryString) char ICOMQueryResultSet
Synopsis
*queryString; *retVal;
Input Arguments queryString
The search criteria for your search, in the same format used in the Remedy User advanced search bar. If the current session is visible, any field values entered in the window will also be used in the search criteria.
A reference to the list of entries found by your search.

Submit, Modify, Close, MakeVisible
A-28
GetServerName
GetServerName
Returns the name of the server hosting this form.

pName = GetServerName() char
*pName;
Return Values pName See Also
The name of the server.

GetFormName, ICOMAppObj::GetServerList, ICOMAppObj::GetFormList, ICOMQueryResultSet::server
A-29
GetFormName
Returns the name of this form.

pName = GetFormName() char
*pName;
Return Values pName See Also
The name of the form.

GetServerName, ICOMAppObj::GetServerList, ICOMAppObj::GetFormList, ICOMAppObj::OpenForm
A-30
ICOMField
ICOMField
The ICOMField interface represents a field in the current form. You use it to retrieve or set the fields value, change the fields visibility, specify whether the field is read-only, and enable or disable the field.
Properties Value
A string representing the fields value.
A-31
MakeVisible
Make the field visible or invisible to the desktop user.

MakeVisible(visible) long visible;
Input Arguments visible See Also
A flag specifying whether the field is invisible (0) or visible (1).

MakeReadWrite, Disable, ICOMFormWnd::GetField, ICOMFormWnd::GetFieldById
A-32
MakeReadWrite
MakeReadWrite
Make the field read-write or read-only.

MakeReadWrite(readOnly) long readOnly;
Input Arguments readOnly See Also
A flag specifying whether the field is read-write (0) or read-only (1).

MakeVisible, Disable, ICOMFormWnd::GetField, ICOMFormWnd::GetFieldById
A-33
Disable
Description
Disable the field. The methods of a disabled fields interface cannot be called, and it is disabled (grayed) and unavailable to the desktop user.
Disable() MakeVisible, MakeReadWrite, ICOMFormWnd::GetField, ICOMFormWnd::GetFieldById
Synopsis See Also
A-34
ICOMQueryResult
ICOMQueryResult
The ICOMQueryResult interface represents an entry found by a search. The entry is a member of an ICOMQueryResultset list. You use it to retrieve the Entry ID and short description of the entry. This interface has no methods.
Properties entryId
A string representing the ID of the found entry. This property is read-only.
Description
A string representing the short description of the found entry. This property is read-only.
A-35
ICOMQueryResultSet
The ICOMQueryResultset interface represents a list of entries found by a search. You use it to retrieve individual entries from the list, determine how many entries were found by the search, and retrieve the name of the form and server where the search was performed.
Properties Count
A long integer representing the number of items in the list.
form
A string representing the name of the form where the search was performed.
server
A string representing the name of the server where the search was performed.
A-36
Item
Item
Retrieves a reference to an item from the list.

retVal = Item(pos) long ICOMQueryResult pos;
*retVal;
Input Arguments pos
The position in the list of the item you want a reference to. The first item is numbered 1.
A reference to the specified list item.

Count, ICOMQueryResult::entryId, ICOMQueryResult::Description
A-37
A-38
Appendix B Migrating to the AR System 4.0 API
Significant changes have occurred in the API since the 3.2 release. This appendix provides a brief summary of these changes. The AR System 4.0 server is backward-compatible, supporting all requests from applications that use the 3.0 or 3.2 API libraries. You can continue linking to one of these libraries, in which case you need not make any changes to continue running your existing programs against 4.0 servers. If you link to the new 4.0 API libraries, you must make some local changes to your programs. The main program structure and processing, however, need not change.
Changes that Impact Existing Programs

These changes will cause existing programs to break if recompiled with 4.0 libraries, unless you modify them according to the instructions presented.
ARInitialization
ARInitialization must be the first AR System API function your program
calls.
Control Record
Two changes involve the control record, the ARControlStruct structure that is passed as the first parameter to most API functions:
Migrating to the AR System 4.0 API
B-1
It has a new member, sessionId. This unsigned long is an identifier for the session control block, which is used to identify unique API sessions now that clients can be multithreaded in their use of the API. These functions have added the control record as their first parameter:
ARDecodeDiary ARDecodeStatusHistory ARGetListServer ARInitialization ARTermination
Status Structure
The ARStatusStruct data structure now has a new member, appendedText. This string contains any text that augments the message text, including messages returned by the operating system or database management system. In previous releases of the AR System, this information was appended to the messageText member.
Windows DLL Requirements

These changes affect Windows NT API programs.
Link
Version 3.2 required your API program to link with the static library arapi.lib. Version 4.0 requires it to link with the arapi40.lib import library for arapi40.dll.
Runtime
Version 3.2 required your API program to have tirpc.dll in your PATH. Version 4.0 instead requires arrpc40.dll, arutl40.dll, and arapi40.dll to be in the PATH.
B-2
UNIX Makefile Changes
UNIX Makefile Changes

Your program must both link to the pthreads library and compile with the appropriate flag to get the re-entrant version of operating system functions. This makes your program safe for multi-threading. See the sample driver makefiles for your environment for an example of how to do this. (Does not apply to HP/UX 10, which does not support a multi-threaded API.)
Deleted Functions
These memory-freeing functions have been removed:
s s s
FreeAREntryValueStruct FreeAREntryValueList FreeARMultipleEntryStruct
Changes that Do Not Impact Existing Programs

These changes will not cause existing programs to break. However, they represent new features you may want to implement in your programs.
New Functions
All of the following functions are new to the AR System.
s
A new server object called a container has been introduced to implement applications and guides. The standard object manipulation functions have been added for this object:
ARCreateContainer ARDeleteContainer ARGetContainer ARGetListContainer ARSetContainer
B-3
ARGetEntryBLOB
Retrieves the contents of an attachment. ARGetEntry will retrieve only the name, size, and compressed size for an attachment field, so you must use ARGetEntryBLOB to get the actual contents of the attachment.
s
Retrieves a list of qualified schema entries the same as ARGetListEntry does. But where ARGetListEntry returns each entry as one concatenated string, ARGetListEntryWithFields returns a list of field/value pairs.
s
ARGetTextForErrorMessage
Retrieves the message text for the current error from the local catalog (in the local language).
s
ARSetServerPort
Specifies the port that your application will use to communicate with the AR System server, and whether to use a private server.
s
New memory-freeing functions have been added. These work like the existing FreeARxxx functions.
FreeARAttachStruct FreeARAutomationStruct FreeARBooleanList FreeARBooleanMatrix FreeARBufStruct FreeARCOMMethodList FreeARCOMMethodParmList FreeARCOMMethodParmStruct FreeARCOMMethodStruct FreeARCOMValueStruct FreeARContainerInfoList FreeARDisplayList FreeAREntryListFieldValueList FreeARLocStruct FreeAROpenDlgStruct
B-4
New Properties and Options
FreeARPushFieldsList FreeARReferenceList FreeARReferenceStruct FreeARSQLStruct FreeARWaitStruct
New Properties and Options

Several new field display properties, VUI display properties, and server options have been added. For field properties see ARCreateField on page 6-19, for VUI properties see ARCreateVUI on page 6-40, and for server options see ARGetServerInfo on page 6-119.
New Field Types

#define #define #define #define AR_FIELD_TYPE_PAGE AR_FIELD_TYPE_PAGE_HOLDER AR_FIELD_TYPE_TABLE AR_FIELD_TYPE_COLUMN page field type */ page holder field type */ table field type */ column field (in a table field) type */ 128 /* attachment field type */ 8 16 32 64 /* /* /* /*
#define AR_FIELD_TYPE_ATTACH
New Data Types

#define AR_DATA_TYPE_DECIMAL #define AR_DATA_TYPE_ATTACH #define AR_DATA_TYPE_TABLE #define AR_DATA_TYPE_COLUMN #define AR_DATA_TYPE_PAGE #define AR_DATA_TYPE_PAGE_HOLDER 10 /* code for 11 /* code for field */ 33 /* code for fields */ 34 35 /* code for 36 /* code for field */ decimal field */ attachment table and column page field */ page holder
Multithreaded API Clients

The AR System API supports multithreaded clients through the use of sessions. Each session maintains its own state information, enabling simultaneous operations against AR System servers. This feature enables more sophisticated client programs to perform multiple operations simultaneously against the same or different servers. You establish a session
B-5
with a call to ARInitialization and terminate it with a call to ARTermination. The session identifier returned in the control record from an ARInitialization call must be present in the control record for all subsequent API function calls intended to operate within that session. Operations for a session are not restricted to a single thread; however, each session can only be active on one thread at any one time.
B-6
Glossary
access control A security feature in which AR System administrators limit the access users have to forms, to specific fields within a form, and to specific functions within the system. See also group, permission, user. See permission. See request. Adaptable client/server software that provides a foundation for creating applications that can automate, track, and manage a wide variety of business processes. Workflow that causes Remedy User to perform specific operations in response to specific user actions. AR System administrators can define many types of active links. For example, they can define active links that run macros, set fields to specified values, run independent system processes, send interactive messages to users, or change field characteristics. Active links run on the client machine. An individual responsible for the management of the AR System, including setting up forms, setting access rights for users, and designing the workflow process. The value that AR System administrators assign to a field while designing a form. When users set defaults, this value is automatically entered in the field. Users can override the administrator default by assigning their own default or by entering a different value. See also user default. One of several special access control groups that the AR System provides. Members of this group have full and unlimited access to the AR System, including unlimited ability to create forms, filters, escalations, active links, menu lists, guides, and applications. See also Subadministrator group.
access permission action request Action Request System (AR System) active link
administrator
administrator default
Administrator group
Glossary-1
advanced search bar
The row of buttons, Search Criteria field, and Fields menu list that appears at the bottom of the Remedy User Details pane when the user clicks the Advanced button. You can use this bar to specify complex search criteria. A group of forms (and associated workflow) that are collected by an administrator and that are related to a particular business function, for example, Employee Care or Help Desk. An application is also a server object in Remedy Administrator, accessible through the API as a container. A set of functions that provides application programmers with access to the full functionality of a product. The AR System API is documented in the Action Request System Programmers Guide (this book).
s
application
application programming interface (API) AR System client
The subset of AR System software necessary to enable users to access an AR System server on the network from a local workstation. The AR System client tools are Remedy Administrator, Remedy User, Remedy Import, and Remedy Notifier. The hardware running the AR System client software. The full set of AR System software, including the AR System server processes and fast, list, and escalation server processes. When installed on a workstation on the network, the server software provides access to the full feature set of the AR System and can be accessed by UNIX workstations or 32-bit Windows PCs on the network that are running the AR System client software. The hardware running the AR System server software.
AR System server
assignee Assignee group
The person assigned responsibility for resolving a request. One of several special access control groups that the AR System provides. Users automatically belong to this implicit group for requests for which they have been assigned responsibility (that is, their name is in the Assigned-to field). See also Assignee Group group, Submitter group.
Glossary-2
Assignee Group group
One of several special access control groups that the AR System provides. Users automatically belong to this implicit group for requests for which they are a member of the group assigned responsibility (that is, they are a member of the group whose name is in the Assignee Group field). See also Assignee group, Submitter group. A field that enables you to allocate space for text, graphics, audio, or video attachments in the database. A field on a form that a user can click to execute an active link. A bitmap can represent a button. See also menu item, toolbar button. The data type used for fields that contain alphanumeric text. A menu that the AR System administrator can create and attach to any character field. See AR System client. A Microsoft software architecture that allows applications to be built from binary software components. OLE functionality is founded on COM. The underlying data structure for guides and applications. The data type for fields that execute active links. These fields do not contain actual data. One of a set of basic fields that are common to all AR System forms. AR System administrators cannot remove these fields from a form. See user command. One of several special access control groups that the AR System provides. This group grants users the right to customize their form layout and create custom commands (in UNIX) in Remedy User.
attachment button
character data type character menu client Component Object Model (COM) container control data type core field
custom extension Customize group
Glossary-3
data field
A field that stores data in the database. Data fields include: character, date/time, diary, integer, real, decimal, selection, and attachment. The property of a field that determines what type of information the field contains. The choices are character, date/time, diary, integer, real, decimal, selection, table, column, page, page holder, trim, control, and attachment. The data type used for fields containing calendar dates and time values. A field that accepts and contains fixed-point numbers. This type of field enables you to store quantitative information in a request. An AR System administrator- or user-defined setting or value that automatically applies to a field if users do not supply a different setting or value when submitting a new request. See also administrator default, user default. The structure in which the data in the AR System is organized and manipulated. A set of fields that are displayed to users and must be responded to before they continue to fill out a form. The administrator creates a dialog box by using an active link action. The data type used for fields that enable you to capture a history of the actions taken for a request. The field stores character data. It is an append-only field, and each addition is stamped with the time, date, and name of the user who entered the item. A type of form containing display-only fields. Display-only forms are used to create control panels and dialog boxes. A Microsoft protocol that enables software components to communicate directly over a network. See also Component Object Model.
data type
date/time data type decimal data type
default
definition dialog box
diary data type
display-only form Distributed Component Object Model (DCOM)
Glossary-4
dynamic data exchange (DDE)
An interapplication communication feature used in Windows applications. For more information, see your Windows documentation. (Windows only). See also object linking and embedding. A menu that causes a search to be performed when a user selects the menu icon. The results of the search are used to build the list of items from which the user can choose. See also character menu. A row in the database that represents a request. Also another term for a request. Workflow that searches at specified times or at regular intervals for any requests matching a specified condition and performs specified operations on all matching requests. The AR System administrator can define escalations to perform actions such as notifying an individual, running a process, setting specified fields, or making an entry to a log file. Escalations run on the AR System server.
s
dynamic menu
entry escalation
export
The Remedy Administrator command that transfers definitions (for example, forms, filters, active links, and mail templates) in a file. The ability to transfer one or more data entries to a file for archive or transfer using the reporting feature in Remedy User.
See also import. field In the AR System, the main entity of a form. All of the following are AR System fields: data, table, page, active link control fields (buttons, menu items, and toolbar buttons), and trim. A menu with items that are retrieved from a file that contains a formatted character menu.
file menu
Glossary-5
filter
Workflow that tests every server transaction for certain conditions and responds to the conditions by taking specific actions. AR System administrators can define many types of filters. They can define filters that set fields to specified values, run independent system processes, send interactive messages to users, notify users when the state of requests change, or make entries in audit trail log files. Filters run on the server. A license that is permanently assigned to a user, enabling access to the licensed features of the AR System at any time. See also floating license, FTS license, write license. A license that exists on a server and is temporarily allocated to any user that requests a license and is defined in the User form as having a floating license type. If no floating license is available at the time of the user request, the user must wait until a license becomes available. See also fixed license, FTS license, write license. A collection of fields that represents a record of information in the AR System. AR System administrators can define and change the fields and workflow associated with a form. An AR System application can include many forms. API calls still refer to forms as schemas. The screen layout for a form. It appears in the Details pane of Remedy User. AR System administrators can create and name multiple form views, which can be further modified by users with Customize permission. Administrators can include different fields and hide fields in various form views. See Full Text Search. A license that enables a user to perform a Full Text Search in any large text or diary field indexed for FTS. See also fixed license, floating license. A feature that enables a user to search quickly for information in large text or diary fields. The fields must be indexed and enabled for FTS by the AR System administrator, and the user must have an FTS license.
fixed license
floating license
form
form view
FTS FTS license
Full Text Search (FTS)
Glossary-6
group
A category in the AR System used to define user access to form fields and functions. The AR System defines several special groups: Public, Administrator, Subadministrator, Customize, Submitter, Assignee, Assignee Group, and Flashboards Administrator. You can define additional groups through the Group form. See also access control, permission, user. The form in which you add new groups, delete groups, and modify group permissions. An unregistered user with a limited set of capabilities (submit requests and possibly review those requests). The administrator can specify whether unregistered users are allowed at your site. A set of ordered steps to help users achieve a specific goal. Instructions for each step can appear in the prompt bar if the administrator writes them. Internally, a guide is a collection of ordered active links, and it is an AR System server object, accessible through the API as a container. A guide is associated with a form. A field that exists but is not visible in a users view of the form.
s
Group form guest user
guide
hidden field import
The Remedy Administrator command that transfers definitions from an export file to the current server. The Remedy Import command that transfers one or more data entries from an archive file to a form.
See also export. integer data type The data type used for fields that contain numeric values between 2147483647 and 2147483647. The range for a particular field can be limited by the AR System administrator. A type of form that contains information from two or more AR System forms. Although join forms function like regular AR System forms in most respects, they do not store independent data. Join forms point to the data stored on the two AR System forms that were used to create the join form.
join form
Glossary-7
license macro
See fixed license, floating license, FTS license, read license, write license. A set of operations recorded for later execution. Macros are useful for automating frequently used or complex search operations. A template that enables you to submit a request by using electronic mail. The AR System administrator generates templates from an existing form by using the export command. A command that is accessed from a menu. An alert that an AR System event has occurred. A standard interapplication communication feature used in Windows applications only. Remedy User can act as both an OLE client (described in the Action Request System Administrators Guide, Volume 2) and an OLE server (described in Appendix A). For more information, see your Windows documentation. See also Component Object Model. One of a number of functions that enable you to define advanced searches or build qualifications. See selection data type. The data type used for fields that organize data displayed in a form. When the user clicks a tab in a Remedy User form, one page is displayed and all other pages are hidden. Each page contains other fields in the schema. See also page holder data type. The data type used for fields that contain page fields. One page holder can contain several pages, and only one page can have focus in any given page holder. See also page data type.
mail template
menu item notification Object Linking and Embedding (OLE)
operator option group page data type
page holder data type
Glossary-8
permission
The property setting that enables AR System administrators to control who can view and change individual fields of a form. Administrators also set permissions for forms and active links. Permissions are defined for each access control group. See also access control, group, user. The part of a main window that displays instructions or useful information to the user. An attribute that is defined. For example, the properties of a field include its data type, physical characteristics such as length, and whether it is required or optional. An access control group that the AR System provides. Every user is automatically a member of this group. A complete definition of search criteria that is constructed in the qualification field. The row of buttons, qualification field, and menu list in Remedy Administrator with which you can specify complex search criteria. The upper and lower limits of acceptable values. For example, if an integer fields range is 10 to 100, users can enter any integer from negative 10 to positive 100 inclusive. A license that allows a user to search the AR System forms and submit new requests but does not allow the user to modify existing requests. See also write license. The data type used for fields that contain floating-point numbers. The range and precision can be set by the AR System administrator. The AR System client tool used by AR System administrators and subadministrators to set up the system for use by support staff and users. This includes setting up forms, setting access permissions (users and groups), and creating filters, escalations, active links, menu lists, guides, and applications.
prompt bar property
Public group qualification qualification bar
range
read license
real data type
Remedy Administrator
Glossary-9
Remedy Import
The AR System client tool that enables AR System administrators to transfer data records from an archive file into a form. The AR System client tool through which a notification can be sent to a user. See also notification. The AR System client tool in which users enter and track requests through the resolution process. Users can also search the database, generate reports, and modify existing requests with Remedy User. The layout that users specify when generating a report from an AR System search. Users can choose the fields to print and the format of the report. A collection of information that describes an event (transaction), such as a problem or a service request. API calls still refer to requests as entries. One of a set of fields with specific rules and interpretations that are defined by the AR System. The part of the form window that displays the results of a search. The ability to define access control on a per-row basis in an SQL database, based on ownership of an action request either individually or as a member of a group. See also Assignee group, Assignee Group group, Submitter group. See form. See form view. The process in which users display a subset of requests according to search criteria that users define. A menu list with items that are retrieved from fields in a specified form.
Remedy Notifier Remedy User
report format
request
reserved field Results pane row-level access
schema schema view search search menu
Glossary-10
selection data type
The data type used for fields with a set of mutually exclusive choices. The selections are displayed as option buttons or as a list of items. A list that appears when an active link performs a search that returns more than one request. The core field in which the AR System tracks the various stages of the resolution process for a request. Information that shows what progress has been made on a request. Users can view status history from the Details pane when in modify mode in Remedy User. An individual with limited administrative access to the AR System as defined by an administrator. One of several special access control groups that the AR System provides. Members of this group have limited administrative access to the AR System as defined by an administrator. One of several special access control groups that the AR System provides. Users automatically belong to this implicit group for requests they have submitted. See also Assignee group, Assignee Group group. Fields that display data from other requests within the context of the current request. The data appears in a spreadsheet-style format. A pointer in Remedy User that enables users to open forms, applications, and guides. The row of buttons below the menu bar that enables easy access to commonly used menu commands. A graphics accelerator for a menu items that triggers an active link. See also button, menu item. Lines, boxes, text, and URL links used to enhance the usability and appearance of a form.
selection list Status field status history
subadministrator Subadministrator group
Submitter group
table field
task toolbar toolbar button trim
Glossary-11
trim data type
The data type of fields that enhance a forms usability and appearance. Trim includes lines, boxes, URL links, and text. These fields do not contain data. Any person with permission to access the AR System. See also access control, group, permissions. In Remedy User for UNIX, an operating system command (or an application that can run from an operating system command line) that is run from the Execute menu of the Search window. Users can define their own set of user commands. A value or set of values that a user can predefine. A user default overrides an AR System administrator default. See also administrator default. The form in which administrators add users to the AR System and specify the type of access each will have. A data element that changes according to the conditions. See form view. The location of fields in a user view. A structure that contains information about a single view. A character that users can enter to represent other characters in a search. For example, in search statements in character and diary fields, users can specify wildcards to match single characters, strings, or characters within a range or set. The actions that filters, active links, and escalations perform. A license that allows a user to modify and save data in existing requests as field and form permission settings allow. See also fixed license, floating license, read license.
user user command
user default
User form variable view view layout view user interface (VUI) wild card
workflow write license
Glossary-12
Index
A access control ARInternalIdList 3-11 see privileges 3-7 actionList parameter 3-34, 3-36, 6-8, 6-18, 6-34, 667, 6-81, 6-86, 6-149, 6-159, 6-165 actions OLE automation 3-46 push fields 3-45, 4-12 run process 4-13 set fields 3-38, 4-12 active links 3-6, 4-4, 6-1 ARActiveLinkActionList 3-13, 3-36 defining actions 3-343-49 OLE automation action 3-46 push fields action 3-45, 4-12 run process action 4-13 set fields action 3-38, 4-12 allocated memory, freeing 2-4, 3-58 appendedText member of ARStatusStruct 3-9, B-2 applications 3-5, 6-12 AR System header files ar.h 2-4 arerrno.h 2-4 arextern.h 2-4 arfree.h 2-4 arstruct.h 2-4, 3-33, 6-20, 6-40 ARCreate 3-15, 3-34 ActiveLink 6-2, 6-6 CharMenu 3-50, 6-4, 6-10 Container 3-54, 6-2, 6-12 Entry 3-32, 6-2, 6-15 Escalation 6-3, 6-17 Field 3-12, 3-21, 6-3, 6-19 Filter 6-3, 6-33 Schema 6-4, 6-35 SupportFile 6-4, 6-38 VUI (view) 3-25, 6-4, 6-40 ARDecode Diary 3-15, 6-5, 6-45 StatusHistory 6-5, 6-46 ARDelete 4-4 ActiveLink 6-2, 6-47
CharMenu 6-4, 6-48 Container 6-2, 6-49 Entry 6-2, 6-50 Escalation 6-3, 6-51 Field 6-3, 6-52 Filter 6-3, 6-54 MultipleFields 6-3, 6-55 Schema 6-4, 6-57 SupportFile 6-4, 6-59 VUI (view) 6-4, 6-60 ARExecuteProcess 6-5, 6-61 ARExpandCharMenu 3-50, 6-4, 6-63 ARExport 3-57, 6-5, 6-64 ARGet 3-34, 4-4 ActiveLink 6-2, 6-66 CharMenu 6-4, 6-69 Container 3-54, 6-2, 6-71 Entry 3-10, 3-32, 3-59, 4-3, 4-6, 4-11, 6-2, 6-74 EntryBLOB 6-2, 6-74, 6-75, 6-76, 6-115, B-4 EntryStatistics 3-15, 6-2, 6-78 Escalation 6-3, 6-80 Field 3-12, 3-21, 4-5, 6-3, 6-82 Filter 6-3, 6-85 FullTextInfo 6-5, 6-88 Schema 6-4, 6-117 ServerInfo 6-5, 6-119 ServerStatistics 6-5, 6-130 SupportFile 6-4, 6-136 TextForErrorMessage 6-5, 6-138, B-4 VUI (view) 3-25, 6-4, 6-139 ARGetList 4-4 ActiveLink 6-2, 6-90 CharMenu 6-4, 6-92 Container 6-2, 6-93 Entry 3-15, 4-6, 6-2, 6-95 EntryWithFields 6-2, 6-95, 6-97, B-4 Escalation 6-3, 6-99 Field 4-5, 6-3, 6-100 Filter 6-3, 6-102 Group 6-5, 6-103 Schema 4-5, 4-6, 6-4, 6-104 Server 3-40, 3-44, 6-5, 6-106 SQL 6-5, 6-108 SupportFile 6-4, 6-110 User 6-5, 6-112 VUI (view) 6-4, 6-114 ARGetMultipleEntries 6-2, 6-115 ARImport 3-57, 6-5, 6-141 ARInitialization 4-2, 4-3, 6-5, 6-143 ARMergeEntry 3-15, 6-3, 6-145
Index-1
ARRPC environment variable 6-180 ARSet 3-15, 3-34, 4-4 ActiveLink 6-2, 6-147 CharMenu 6-4, 6-151 Container 3-54, 6-2, 6-153 Entry 3-21, 3-32, 6-3, 6-156 Escalation 6-3, 6-158 Field 3-12, 3-21, 6-3, 6-161 Filter 6-3, 6-164 FullTextInfo 6-5, 6-167 Schema 6-4, 6-169 ServerInfo 6-5, 6-172 ServerPort 6-5, 6-180, B-4 SupportFile 6-4, 6-181 VUI (view) 3-25, 6-4, 6-182 ARTCPPORT environment variable 6-180 ARTermination 4-2, 4-3, 6-5, 6-184 ARVerifyUser 6-5, 6-185 attachment fields 6-74, 6-76, 6-115 C character menus 3-5, 4-4, 6-1 ARCharMenuFileStruct 3-51 ARCharMenuList 3-51 ARCharMenuQueryStruct 3-51 ARCharMenuSQLStruct 3-51 ARCharMenuStruct 3-50, 3-51 defining 3-503-52 cleanup, AR and Remedy Notifier Systems 4-2 column fields 6-19, 6-23, 6-31, 6-52, 6-100 COM Automation. See OLE Automation conList parameter 4-4 constants 2-4 definitions 2-4 containers 3-5, 4-4, 6-1 data structures for 3-523-56 retrieving lists of 3-52 retrieving or modifying 3-54 control fields 4-5, 6-19, 6-23, 6-28, 6-29, 6-30, 6-67, 6-100, 6-149 control parameter 3-6, 4-2, B-1 controlField parameter 6-7, 6-8, 6-67, 6-148, 6-149 core field IDs 2-4, 3-33 D data fields 3-6, 3-21, 3-22, 4-5, 6-19, 6-21, 6-24, 626, 6-27, 6-31, 6-83, 6-100, 6-162 data structures ARActiveLinkActionList 3-13, 3-36 ARActiveLinkActionStruct 3-36
ARArithOpAssignStruct 3-39, 3-41 ARArithOpStruct 3-1, 3-18, 3-19, 3-41 ARAssignFieldStruct 3-39, 3-40, 3-41 ARAssignSQLStruct 3-39, 3-44 ARAssignStruct 3-38, 3-39, 3-42 ARAttachLimitsStruct 3-23 ARBooleanList 3-34 ARByteList 3-14, 6-28, 6-42 ARCharLimitsStruct 3-23 ARCharMenuFileStruct 3-51 ARCharMenuItemStruct 3-51, 3-52 ARCharMenuList 3-51 ARCharMenuQueryStruct 3-51 ARCharMenuSQLStruct 3-51 ARCharMenuStruct 3-50, 3-51 ARColumnLimitsStruct 3-23 ARCompoundSchema 3-20, 3-21 ARContainerInfo 3-53 ARContainerInfoList 3-53, 4-4 ARControlStruct 3-6, 3-8, 3-9, 4-2, 4-3, B-1 ARCoordList 3-26, 6-23, 6-24, 6-25, 6-26, 6-31 ARDDEStruct 3-39, 3-43 ARDecimalLimitsStruct 3-23 ARDiaryLimitStruct 3-23 ARDiaryList 3-3 ARDisplayInstanceList 3-12, 3-24, 3-25 ARDisplayInstanceStruct 3-24, 3-25 AREntryIdList 3-29, 5-4, 6-74, 6-76 AREntryIdListList 3-34 AREntryListFieldList 3-31, 5-4 AREntryListFieldStruct 3-31, 5-4 AREntryListFieldValueList 3-30 AREntryListFieldValueStruct 3-30 AREntryListList 3-3, 3-29, 4-4, 5-4 AREntryListStruct 3-29, 5-4 ARExtReferenceStruct 3-56 ARFieldAssignList 3-38 ARFieldAssignStruct 3-38 ARFieldLimitStruct 3-22 ARFieldMappingStruct 3-27, 3-28 ARFieldValueList 3-12, 3-32, 3-33, 5-4 ARFieldValueListList 3-34 ARFieldValueOrArithStruct 3-17, 3-18, 3-19, 342 ARFieldValueStruct 3-33 ARFilterActionList 3-3, 3-12, 3-35 ARFilterActionStruct 3-4, 3-35 ARFunctionAssignStruct 3-39, 3-42 ARGroupInfoList 4-4 ARIntegerLimitsStruct 3-22
Index-2
ARInternalId 3-55 ARInternalIdList 3-11, 4-4, 5-4 ARJoinMappingStruct 3-28 ARJoinSchema 3-20 ARLoadARQualifierStruct 3-15, 4-6, 4-9, 6-5, 6144 ARNameList 3-3, 3-14, 3-23, 4-4, 5-4 ARNameType 3-53 ARPermissionList 3-11, 5-4 ARPermissionStruct 3-12 ARPropList 3-24, 3-25 ARPropStruct 3-25 ARPushFieldsList 3-45 ARPushFieldsStruct 3-45 ARQualifierStruct 3-12, 3-15, 3-17, 3-29, 3-40, 4-4, 5-4 ARRealLimitsStruct 3-22 ARReferenceList 3-54 ARReferenceStruct 3-13, 3-54, 3-55 ARRelOpStruct 3-17 ARServerNameList 4-4 ARSortList 3-31 ARSortStruct 3-32 ARStatHistoryValue 3-18, 3-19, 3-40 ARStatusHistoryList 5-4 ARStatusList 3-8, 3-9, 3-10, 3-59, 3-60, 4-3, 4-9, 5-4 ARStatusStruct 3-8, 3-11, 5-4 ARStructItemList 3-57, 3-58 ARStructItemStruct 3-57 ARTableLimitsStruct 3-23 ARUserInfoList 4-4 ARValueStruct 3-1, 3-12, 3-14, 3-18, 3-22, 3-25, 3-30, 3-33, 3-39 definitions 2-4 lists 3-3 NTStatusList 3-8, 3-60, 4-9 data type 3-13 data types ARBoolean 3-2 AREntryIdType 3-2, 3-29, 6-74, 6-76 ARInternalId 3-2 ARNameType 3-2 ARServerNameType 3-2 ARTimestamp 3-2 NTBoolean 3-2 NTNameType 3-2 NTServerNameType 3-2 daysOpen program 2-2, 2-5, 2-6, 5-2
debugging print.c routines 5-3 using driver 5-2 using log files 5-1 defining character menus 3-503-52 field display properties 3-24 field limits 3-21 filter, escalation, or active link actions 3-343-49 login information 3-63-8 privileges 3-113-12 query conditions 4-4, 4-6 search criteria 3-153-19 session information 3-63-8, B-5 definitions core and reserved field IDs 2-4, 3-33, 6-20, 6-40 data structures and constants 2-4 error codes 2-4 deleteOption parameter 6-52, 6-55, 6-57 dInstanceList parameter 3-24, 6-22, 6-83, 6-163 DLLs, required 2-1, B-2 documentation set xii dPropList parameter 3-25 driver program 2-2, 2-5, 2-7, 5-2, 5-4, 5-6, 5-7, 5-8 E elseList parameter 6-8, 6-18, 6-34, 6-67, 6-81, 6-86, 6-150, 6-159, 6-165 entries 3-6, 4-4, 6-1 AREntryIdList 3-29, 6-74, 6-76 AREntryListFieldList 3-31 AREntryListFieldValueList 3-30 AREntryListList 3-3, 3-29, 4-4 ARFieldValueStruct 3-33 ARSortList 3-31 ARSortStruct 3-32 checking the existence of 3-34 data structures for 3-283-34 retrieving as concatenated strings 3-29 retrieving as field/value pairs 3-30 retrieving lists 3-28 retrieving multiple 3-34 retrieving or modifying an entry 3-32 entryId parameter 4-6 entryList parameter 3-29, 3-30, 4-4, 4-6, 6-96, 6-98 error codes definitions 2-4 error messages 4-9
Index-3
escalations 3-6, 4-4, 6-1 ARFilterActionList 3-3, 3-12, 3-35 defining actions 3-343-49 push fields action 3-45, 4-12 run process action 4-13 set fields action 3-38, 4-12 executeMask parameter 6-7, 6-8, 6-67, 6-148, 6-149 existList parameter 3-34 exporting ARStructItemList 3-57, 3-58 data structures for 3-573-58 label definitions 2-4 external declarations 2-4 external references, defining 3-56 F fieldId parameter 4-5, 6-20, 6-22, 6-52, 6-82, 6-161 fieldList parameter 3-33, 4-6, 6-15, 6-55, 6-75, 6145, 6-146, 6-156 fieldMap parameter 3-27, 6-20, 6-83 fieldName parameter 6-20, 6-83, 6-161 fields 4-4, 6-1 ARAssignFieldStruct 3-41 ARByteList 6-28, 6-42 ARCoordList 6-23, 6-24, 6-25, 6-26, 6-31 ARDisplayInstanceList 3-12, 3-24, 3-25 AREntryIdListList 3-34 ARFieldAssignStruct 3-38 ARFieldLimitStruct 3-22 ARFieldMappingStruct 3-27, 3-28 ARFieldValueList 3-12, 3-32, 3-33 ARFieldValueListList 3-34 ARInternalIdList 4-4 ARJoinMappingStruct 3-28 ARPermissionList 3-11 ARPropList 3-24, 3-25 ARPropStruct 3-25 ARPushFieldsStruct 3-45 attachment fields 6-74, 6-76, 6-115 column fields 6-19, 6-23, 6-31, 6-52, 6-100 control fields 4-5, 6-19, 6-23, 6-28, 6-29, 6-30, 667, 6-100, 6-149 data fields 3-6, 3-21, 3-22, 4-5, 6-19, 6-21, 6-24, 6-26, 6-27, 6-31, 6-83, 6-100, 6-162 data structures for 3-213-28 defining display properties 3-24 defining limits 3-21 in join schemas 3-27 nondata fields 3-6 page fields 6-19, 6-23, 6-31, 6-52, 6-100
page holder fields 6-19, 6-23, 6-31, 6-52, 6-100 screen location 3-26 screen size 3-26 table fields 6-7, 6-19, 6-23, 6-31, 6-32, 6-52, 6100, 6-148 trim fields 6-19, 6-22, 6-25, 6-26, 6-27, 6-100 fieldType parameter 4-5 files header 2-3 library 2-5 support 6-38, 6-59, 6-110, 6-136, 6-181 filters 3-6, 4-4, 6-1 ARFilterActionList 3-3, 3-12, 3-35 defining actions 3-343-49 push fields action 3-45, 4-12 run process action 4-13 set fields action 3-38, 4-12 focusField parameter 6-7, 6-8, 6-67, 6-148, 6-149 free function 3-58, 4-2 FreeAR xi, 2-4, 3-34, 3-58, 3-60, 4-2, 4-9, 6-5, 6187 FieldValueList 3-34 QualifierStruct 6-144 StatusList 3-59, 3-60, 4-3, 4-11 freeing allocated memory 2-4, 3-58 FreeNT xi, 2-4, 3-58, 3-60, 4-2, 4-9, 6-5, 6-194 StatusList 3-60, 4-11 freeStruct parameter 3-58, 3-59, 6-193, 6-194 functions, deleted B-3 functions, new B-3 functions, other free 3-58, 4-2 malloc 3-58, 3-59 functions, Remedy external declarations 2-4 G getListFields parameter 3-30, 6-36, 6-96, 6-98, 6118, 6-170 groupByList parameter 6-79 groupList parameter 3-11, 4-4, 6-7, 6-12, 6-36, 6-64, 6-66, 6-67, 6-72, 6-103, 6-118, 6-148, 6153, 6-170 groups 4-4 ARGroupInfoList 4-4 privileges 6-13, 6-36, 6-72, 6-118, 6-154, 6-162, 6-170 guides 3-5, 6-12
Index-4
H header files 2-3 ar.h 2-4 arerrno.h 2-4 arextern.h 2-4 arfree.h 2-4 arstruct.h 2-4, 3-33, 6-20, 6-40 nt.h 2-4 nterrno.h 2-4 ntfree.h 2-4 ntsextrn.h 2-4 I ICOMAppObj GetActiveForm A-15 GetFormList A-12 GetServerList A-11 HasDefaultSession A-16 LoadForm A-14 Login A-9 Logout A-10 OpenForm A-13 OpenGuide A-17 RunMacro A-18 ICOMAppObj object A-8 ICOMField A-31 Disable A-34 MakeReadWrite A-33 MakeVisible A-32 ICOMFormWnd A-19 Close A-22 GetField A-24 GetFieldById A-25 GetFormName A-30 GetServerName A-29 GiveFieldFocus A-26 GiveFieldFocusById A-27 MakeVisible A-23 Modify A-21 Query A-28 Submit A-20 ICOMQueryResult A-35 ICOMQueryResultSet A-36 Item A-37 ID parameter 6-76 idList parameter 4-4, 4-5, 6-75, 6-101, 6-114 importing ARStructItemList 3-57, 3-58 data structures for 3-573-58 include files see header files 2-3
informational messages 4-9 initialization, AR and Remedy Notifier Systems 4-2 J join schemas defining a join 3-203-21 fields in 3-27 L library files 2-5 limit parameter 3-21, 6-21, 6-83, 6-162 lists generic structure 3-3 retrieving entries 3-28 loc parameter 6-76 login defining login information 3-63-8 information 4-2 server name 3-7, 3-40, 3-44 user name 3-7, 6-15, 6-63, 6-74, 6-76, 6-78, 6-90, 6-93, 6-95, 6-97, 6-104, 6-115, 6-145, 6-156, 6-185 M makefiles UNIX 2-6, B-3 Windows NT 2-7 malloc function 3-58, 3-59 memory, freeing allocated 2-4, 3-58 menuDefn parameter 3-50, 6-10, 6-63, 6-69, 6-152 menus 3-5, 4-4, 6-1 ARCharMenuFileStruct 3-51 ARCharMenuList 3-51 ARCharMenuQueryStruct 3-51 ARCharMenuSQLStruct 3-51 ARCharMenuStruct 3-50, 3-51 defining 3-503-52 messages 4-9 appended text 3-9 message number 3-9 message text 3-9 message type 3-9 multithreaded API programs 2-5, B-5
Index-5
N nameList parameter 4-4, 4-5, 4-6, 6-90, 6-92, 6-99, 6-102, 6-105 names server 3-7, 3-40, 3-44 user 3-7, 6-15, 6-63, 6-74, 6-76, 6-78, 6-90, 6-93, 6-95, 6-97, 6-104, 6-115, 6-145, 6-156, 6-185 nondata fields 3-6 notifications 6-5 NT System header files nt.h 2-4 nterrno.h 2-4 ntfree.h 2-4 ntsextrn.h 2-4 NTDeregisterServer 6-5, 6-195 NTGetListServer 6-5, 6-196 NTGetListUser 6-197 NTGetTextForErrorMessage 6-198 NTInitializationServer 4-2, 6-5, 6-199 NTNotificationServer 6-5, 6-200 NTRegisterServer 6-5, 6-202 NTSetServerPort 6-204 NTTCPPORT environment variable 6-204 NTTerminationServer 4-2, 6-5, 6-205 O OLE Automation ICOMAppObj object A-8 ICOMField interface A-31 ICOMFormWnd interface A-19 ICOMQueryResult interface A-35 ICOMQueryResultSet interface A-36 overview A-1 sample program A-3 OLE automation action 3-46 operations arithmetic 3-19 conditional 3-17 relational 3-17 option parameter 6-21, 6-50, 6-83, 6-157, 6-162 P page fields 6-19, 6-23, 6-31, 6-52, 6-100 page holder fields 6-19, 6-23, 6-31, 6-52, 6-100 parameters actionList 3-34, 3-36, 6-8, 6-18, 6-34, 6-67, 6-81, 6-86, 6-149, 6-159, 6-165 conList 4-4 control 3-6, 4-2, B-1 controlField 6-7, 6-8, 6-67, 6-148, 6-149
deleteOption 6-52, 6-55, 6-57 dInstanceList 3-24, 6-22, 6-83, 6-163 dPropList 3-25 elseList 6-8, 6-18, 6-34, 6-67, 6-81, 6-86, 6-150, 6-159, 6-165 entryId 4-6 entryList 3-29, 3-30, 4-4, 4-6, 6-96, 6-98 executeMask 6-7, 6-8, 6-67, 6-148, 6-149 fieldId 4-5, 6-20, 6-22, 6-52, 6-82, 6-161 fieldList 3-33, 4-6, 6-15, 6-55, 6-75, 6-145, 6146, 6-156 fieldMap 3-27, 6-20, 6-83 fieldName 6-20, 6-83, 6-161 fieldType 4-5 focusField 6-7, 6-8, 6-67, 6-148, 6-149 freeStruct 3-58, 3-59, 6-193, 6-194 getListFields 3-30, 6-36, 6-96, 6-98, 6-118, 6-170 groupByList 6-79 groupList 3-11, 4-4, 6-7, 6-12, 6-36, 6-64, 6-66, 6-67, 6-72, 6-103, 6-118, 6-148, 6-153, 6-170 id 6-76 idList 4-4, 4-5, 6-75, 6-101, 6-114 limit 3-21, 6-21, 6-83, 6-162 loc 6-76 menuDefn 3-50, 6-10, 6-63, 6-69, 6-152 nameList 4-4, 4-5, 4-6, 6-90, 6-92, 6-99, 6-102, 6105 option 6-21, 6-50, 6-83, 6-157, 6-162 permissions 3-11, 6-21, 6-83, 6-162 qualifier 3-17, 3-29, 4-6, 6-78, 6-95, 6-96, 6-97, 6-98, 6-144 qualString 4-6 query 6-18 results 6-79 schema 4-5, 4-6, 6-7, 6-15, 6-17, 6-20, 6-33, 6-35, 6-40, 6-50, 6-52, 6-55, 6-60, 6-67, 6-74, 6-76, 6-78, 6-81, 6-82, 6-86, 6-90, 6-95, 6-97, 6-99, 6-100, 6-102, 6-114, 6-115, 6-117, 6-139, 6144, 6-145, 6-148, 6-156, 6-159, 6-161, 6165, 6-169, 6-182 schemaType 6-105 serverList 4-4, 6-106, 6-196 sortList 3-31, 6-36, 6-96, 6-98, 6-118, 6-170 status 3-8, 3-11 structItems 3-58, 6-65, 6-142 userList 4-4, 6-112, 6-197 value 3-58, 6-193, 6-194 permissions parameter 3-11, 6-21, 6-83, 6-162 permissions see privileges 3-7 port, setting 6-180, 6-204
Index-6
portmapper 6-180, 6-204 print.c routines 5-3 private server, using 6-180 privileges ARPermissionStruct 3-12 defining 3-113-12 group 6-13, 6-36, 6-72, 6-118, 6-154, 6-162, 6170 user 3-7, 6-15, 6-61, 6-63, 6-74, 6-76, 6-78, 6-90, 6-93, 6-95, 6-97, 6-104, 6-108, 6-115, 6-145, 6-156 program number 6-180 prototypes, function 2-4 push fields action 3-45, 4-12 ARPushFieldsList 3-45 Q qualifier parameter 3-17, 3-29, 4-6, 6-78, 6-95, 6-96, 6-97, 6-98, 6-144 qualString parameter 4-6 query conditions 4-4, 4-6 parameter 6-18 R references, defining 3-55 reserved field IDs definitions 2-4, 6-20, 6-40 results parameter 6-79 return messages 4-9 RPC program number 6-180 run process action 4-13 S sample programs daysOpen 2-2, 2-5, 2-6, 5-2 driver 2-2, 2-5, 2-7, 5-2, 5-4, 5-6, 5-7, 5-8 schema parameter 4-5, 4-6, 6-7, 6-15, 6-17, 6-20, 633, 6-35, 6-40, 6-50, 6-52, 6-55, 6-60, 667, 6-74, 6-76, 6-78, 6-81, 6-82, 6-86, 690, 6-95, 6-97, 6-99, 6-100, 6-102, 6-114, 6-115, 6-117, 6-139, 6-144, 6-145, 6-148, 6-156, 6-159, 6-161, 6-165, 6-169, 6-182 schemas 3-4, 4-4, 6-1 ARCompoundSchema 3-20, 3-21 ARJoinSchema 3-20 ARPermissionList 3-11 schemas, data structures for 3-203-21 schemaType parameter 6-105 server port, setting 6-180, 6-204
serverList parameter 4-4, 6-106, 6-196 servers 4-4 ARServerNameList 4-4 name 3-7, 3-40, 3-44 session defining session information 3-63-8, B-5 sessionId member of ARControlStruct 3-7, B-2 set fields action 3-38, 4-12 ARFieldAssignList 3-38 sortList parameter 3-31, 6-36, 6-96, 6-98, 6-118, 6170 startup, AR and Remedy Notifier Systems 4-2 status parameter 3-8, 3-11 status, retrieving 3-83-11 structItems parameter 3-58, 6-65, 6-142 support files 6-1 T table fields 6-7, 6-19, 6-23, 6-31, 6-32, 6-52, 6-100, 6-148 TCD, specifying port with 6-180 termination, AR and Remedy Notifier Systems 4-2 toolbar icons ARByteList 3-14 trim fields 6-19, 6-22, 6-25, 6-26, 6-27, 6-100 U userList parameter 4-4, 6-112, 6-197 users 4-4 ARUserInfoList 4-4 name 3-7, 6-15, 6-63, 6-74, 6-76, 6-78, 6-90, 693, 6-95, 6-97, 6-104, 6-115, 6-145, 6-156, 6185 privileges 3-7, 6-15, 6-61, 6-63, 6-74, 6-76, 6-78, 6-90, 6-93, 6-95, 6-97, 6-104, 6-108, 6-115, 6-145, 6-156 V value parameter 3-58, 6-193, 6-194 values, data structures for 3-123-15 views (VUIs) 3-5, 4-4, 6-1 ARInternalIdList 4-4 ARPropList 3-24, 3-25 ARPropStruct 3-25 void, casting to 3-60 W warning messages 4-9
Index-7
Index-8
Reader Response
Action Request System 4.0 Programmers Guide
AR-400-PG-01.PDF December 1998
Remedy Corporation welcomes your ideas about how to improve its documentation. Please take a moment to answer the questions below. Explain any No responses in the Comments section, and include any other comments you may have. Mail this page to the address printed on the reverse side (the address is on the next page if you are using the PDF version of this guide), or fax it to (650) 903-9001 (US). You can also send comments through electronic mail to doc_feedback@remedy.com. Yes Does this manual contain all the information you expected? Is all the information in this manual technically accurate? Is this manual easy to read and understand? Are there enough examples and illustrations? Are the examples and illustrations accurate and helpful? Comments: u u u u u No u u u u u
Name: Company: Address: City: Country: Phone number:
Title:
State:
ZIP:
Email:

Place Stamp Here
Information Development Remedy Corporation 1505 Salado Dr., Bldg. 2 Mountain View, CA 94043 USA
Fold Here

Programmers 40

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Programmers 40

Uploaded by

Copyright:

Available Formats

December 1998 Part Number: AR-400-PG-01.

Action Request System Programmers Guide

Action Request System Programmers Guide

Action Request System Programmers Guide

Action Request System Programmers Guide

Overview of This Document

Related Remedy Documents

Action Request System Programmers Guide

Related Remedy Documents

Conventions Used in This Document

Action Request System Programmers Guide

Overview of the AR System API

AR System mail process

Remedy Notifier API

AR System server process

Remedy Notifier server process

Overview of AR System and Remedy Notifier Architecture

Action Request System Programmers Guide

Overview of the AR System API

User Tool Client Request

Others Server Response

Action or Data if successful

Access IfControl fails Parameter Validation If fails

Error message, and filter stops

Error message, and filter stops

Perform database operations Database error message If error

Overview of AR System Server Processing

When to Use API Programming

Action Request System Programmers Guide

Chapter 2 Getting Started

Environment Setup for Windows

Installing the API Files

Action Request System Programmers Guide

include (header files)

lib (library files)

src (source code)

include (header files) daysOpen driver

lib (library files)

driver (source code)

Directory Structure for API Files

API Header Files Remedy Notifier

Action Request System Programmers Guide

Sample Makefile for daysOpen Program

Action Request System Programmers Guide

Action Request System Programmers Guide

Chapter 3 Data Structures

HS Diploma Zero or One

Birth Date One Only

Credit Cards Zero or More

Names One or More

Notation Used to Represent Data Relationships

typedef unsigned char typedef char typedef char

Action Request System Programmers Guide

Structure Simple Data Type

Legend for Data Structure Diagrams

unsigned int ARFilterActionList

Generic List Structure

High-Level Object Relationships

Action Request System Programmers Guide

High-Level Object Relationships

High-Level Object Relationships

Login and Session Information

Action Request System Programmers Guide