This topic provides an overview of the API structure. 

All API activity takes place in the context of a client session, which is represented by a Scheduler object. Your client application must create an Application object and then use its Connect or ConnectRemote methods to establish sessions. 

Each session (Scheduler object) represents a connection to a single adTempus server, using the identity of a Windows user. All API activity (including the ability to connect to the server in the first place) is governed by the adTempus security framework, which uses Windows security. 

A single client application may have as many sessions as it requires. For example, the adTempus Console allows you to connect to many servers at once; each server is a separate session. 

Each session (Scheduler object) should be thought of as single-threaded. That is, your application should only be doing one thing at a time with the session. If two different pieces (e.g., threads) of your application are trying to use a single Scheduler object at the same time, you may end up with unpredictable results. 

Most of the API components are data objects, which represent data stored in the database. Many of these classes (and their properties) correspond closely to the dialog boxes in input controls in the adTempus Console. 

All data objects derive from the IADTObject interface, which provides some common properties and methods. Each object is uniquely identified by its OID (object identifier), a 77-character string composed of two GUIDs that identify the class and identity of the object. OIDs are used throughout the API to identify and retrieve objects. 

Data objects cannot be directly created by your code. To create a new data object you must use the Scheduler.CreateObject method, which ensures that you have the appropriate permission to create the object, and also initializes the object with the proper client context. 

Data objects also implement the IProvideValidation interface. The Validate method of this interface causes the object to validate itself and return error messages for any problems that are found. Validate only validates the object you call it for, not any subordinate objects (for example, if you call the method for a Job, it only validates the job, not any steps, triggers, etc., attached to the job). If you are building a user-interface application, you should therefore validate each new or modified object as the user leaves the dialog box, web page, or equivalent user interface component that is responsible for it. 

For example, in the adTempus Console, each time the user clicks OK in a dialog box, the Console validates whatever object the user was editing in that dialog and shows error messages if appropriate. 

Data objects cannot be shared between client sessions. That is, if an object is created or retrieved using a particular Scheduler instance, you cannot use that object with any other Scheduler instance. Attempting to do so will result in error ADT_E_FOREIGN_ITEM. 

Data objects cannot be shared between "parents," unless they are specifically designated as shareable (see below). For example, if you create a JobStep and attach it to a job, you cannot then attach that same JobStep to another job. The API will not prevent you from doing this, but if you do so you will end up with corrupted data. 

Some data objects can be shared between "parents." These objects implement the IADTIndependentObject interface. For example, the NotificationAddress represents a notification recipient and is meant to be shared among jobs. An object implements IADTIndependentObject if it can be shared under at least some circumstances, but the object may not always be suitable for sharing. For example, a Script object can be shared if its Shared property is True, but not otherwise. 

The IADTIndependentObject also provides methods that allow you to save and delete the object. 

"Top-level" objects (such as jobs, scripts, notification recipients) implement the IADTSecuredObject, which allows you to edit the security settings for those objects. Any action you take on such an object is subject to security checks; if you do not have permission to perform an action it will fail with error ADT_E_NO_PERMISSION. 

Classes that do not implement IADTSecuredObject are generally secured by their "parent." For example, a JobStep does not have security settings of its own, because a JobStep always belongs to a Job, which does have security settings. As a result of this, for objects such as JobSteps:

• The object does not have Save or Delete methods: it is saved or deleted only when its parent is.
• The object cannot be directly retrieved using Scheduler.GetObject or other methods (GetObject will fail with error ADT_E_NO_DIRECT_RETRIEVAL if you try to retrieve one of these objects). Instead, you must retrieve the object from the appropriate collection owned by its parent (e.g., the Steps collection of the Job).