Home >Documents >Programmers 40

Programmers 40

Date post:22-Feb-2015
Category:
View:372 times
Download:7 times
Share this document with a friend
Transcript:

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

v

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

Action Request System Programmers Guide

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

Action Request System Programmers Guide

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

x

Action Request System Programmers Guide

Preface

AudienceThis 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 DocumentChapter 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 DocumentsThe 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

Action Request System Programmers Guide

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 DocumentSome 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: Indicates data to be entered by the user. Example: Type /bin/aruser. Indicates a series of menu selections. Example: Choose File Exit. Used in the left margin to indicate a step-by-step procedure.

bold courier

xiv

Action Request System Programmers Guide

Chapter 1 Introduction

This chapter shows you how the AR System API works with the AR System.

Overview of the AR System APIAs 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 filearserverd ntserverd armaild

Windows NT filearserver.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

Action Request System Programmers Guide

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 errorand 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

arserverdserver process

EO = Execution order

Figure 1-2

Overview of AR System Server Processing

Introduction

1-3

When to Use API ProgrammingThe 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.

s

s

s

s

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

Action Request System Programmers Guide

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 WindowsThe following information applies to Windows NT, Windows 95, and Windows 98 environments: Compilers

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 to your path or put your executable file in ).

Libraries

s

s

DLLs

s

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

2-2

Action Request System Programmers Guide

Header Files

UNIX

Windows NT

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 FilesThe include directory contains the nine API header files shown in Table 2-1. Table 2-1 AR Systemar.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 or FreeNT 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

Action Request System Programmers Guide

Library Files

Library FilesThe 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 filesarapi40.dll, arapi40.lib nts.lib

UNIX fileslibar.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 CodeThe 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

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

UNIXThe 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

Action Request System Programmers Guide

Makefiles

Windows NTCreating 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 .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

Action Request System Programmers Guide

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 TypesIn 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

Action Request System Programmers Guide

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.

ListsLists 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 ARStruct } ARList; numItems; *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 ARFilterActionListPointer

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 RelationshipsBefore 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

Action Request System Programmers Guide

High-Level Object Relationships

API Program

Applications

Schemas

Guides

Menus

Views

Fields

Entries

Filters

Escalations

Active links

subtype

Nondata fields

Data fields

Figure 3-4

High-Level Object Relationships

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 InformationAlmost 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

Action Request System Programmers Guide

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 InformationNearly 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 TextPointer

Message Number

Appended TextPointer

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

Action Request System Programmers Guide

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 inarerrno.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-10 1 AR_RETURN_OK NT_RETURN_OK

AR_RETURN_WARNING NT_RETURN_WARNING

2

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 statusListStack Heap

3

messageType messageNum

2 197 Unrecognized keyword

[0]messageText appendedText

messageType messageNum

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]messageText appendedText

messageType messageNum

[2]messageText appendedText

Figure 3-7

3-10

Action Request System Programmers Guide

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 InformationPermission 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-20 1 2

AR_PERMISSIONS_NONE

AR_PERMISSIONS_VISIBLE Group can see the schema or container. AR_PERMISSIONS_HIDDEN

Table 3-30 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 ValuesOne 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

Action Request System Programmers Guide

Representing Values

s s

ARActiveLinkActionList (see Figure 3-21) ARReferenceStruct (see Figure 3-29)

ARValueStruct Data Type

unsigned int

Keyword

Integer

Real

CharacterPointer

}union

}DiaryPointer

Enumerated

unsigned int

long

double char char

unsigned long

Time

Bitmask

Byte ListPointer

DecimalPointer

AttachmentPointer

Unsigned Long

Coordinate ListPointer

ARTimestamp

unsigned long

ARByteList

char

ARAttachStruct

unsigned longARCoordList

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-40 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

5

AR_DATA_TYPE_DIARY

6

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

Action Request System Programmers Guide

Representing Qualifications

Note:

When passing a diary value to ARCreate or ARSet 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 QualificationsMany 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 OperandPointer

Not ConditionPointer

}union

}Relational OperatorPointer

Right OperandPointer

ARQualifierStruct

ARRelOpStruct Right Operand

ARQualifierStruct

ARQualifierStruct

Left Operand

ARFieldValueOrArithStruct

ARFieldValueOrArithStruct

}union

}Field ID Value Arith OpPointer

Status History

ARInternalId

ARValueStruct See Figure 3-9

ARArithOpStruct Left Operand

ARStatHistoryValue

Right Operand

ARFieldValueOrArithStruct

ARFieldValueOrArithStruct

Figure 3-10

Structures Used to Represent Any Qualification

3-16

Action Request System Programmers Guide

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-50 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 OperatorsQualifications 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 OperatorsQualifications 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-61 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 OperationThe 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-71 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)

4

AR_STAT_HISTORY

3-18

Action Request System Programmers Guide

Qualifications that Use Relational Operators

Defining an Arithmetic Result ValueARArithOpStruct 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-91 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

SchemasCompound 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

Action Request System Programmers Guide

Fields

Table 3-101 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-110 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

FieldsThe 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 LimitsThe 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 DecimalARNameType 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-120 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

Action Request System Programmers Guide

Defining Field Limits

Table 3-124

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

8

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 PropertiesThe 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 PropertiesPointer

ARPropList ARDisplayInstanceStruct Display Properties

Pointer

ARPropStruct

VUI ID

ARInternalId Property Tag Value

ARPropList

unsigned long

ARValueStruct See Figure 3-9

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

Action Request System Programmers Guide

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 usingARValueStruct (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 LocationThe 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

Action Request System Programmers Guide

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 SchemasBecause 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-141 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-150 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.

EntriesThe 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 ListsThe 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

Action Request System Programmers Guide

Retrieving Entry Lists

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 StringsThe ARGetListEntry function returns an entryList output parameter that is a pointer t

Click here to load reader

Reader Image
Embed Size (px)
Recommended