Automate Scheduler Using Macros

Automate Scheduler Using Macros

While every attempt has been made toensure that the information in this document isaccurate and complete, some typographicalerrors or technical inaccuracies may exist.Cognos does not accept responsibility forany kind of loss resulting from the use ofinformation contained in this document.This page shows the publication date. Theinformation contained in this document issubject to change without notice. Anyimprovements or changes to either theproduct or the document will be documentedin subsequent editions.This software/documentation containsproprietary information of CognosIncorporated. All rights are reserved.Reverse engineering of this software isprohibited. No part of this software/documentation may be copied,photocopied, reproduced, stored in aretrieval system, transmitted in any form or byany means, or translated into anotherlanguage without the prior written consent ofCognos Incorporated.Scheduler version 5.0.This edition published 1999.Copyright © 1999 Cognos Incorporated.Portions Copyright © Microsoft Corporation,One Microsoft Way, Redmond, Washington98052-6399 USA. All rights reserved.Portions Copyright © Sheridan SoftwareSystems, Inc.Cognos, the Cognos logo, the Cognos tagline "Better Decisions Every Day," Impromptu,PowerPlay, PowerCube, Scenario,4Thought, DataMerchant, PowerHouse,RealObjects, COGNOSuite, NovaView,and Cognos Accelerator are trademarks ofCognos Incorporated. All other trademarksmentioned are the property of their respectiveowners.U.S. Government Restricted Rights. Thesoftware and accompanying materials areprovided with Restricted Rights. Use,duplication for disclosure by the Governmentis subject to the restrictions in subparagraph(c)(1)(ii) of the Rights in Technical Data andComputer Software clause at DFARS252.227-7013, or subparagraphs (c) (1)and (2) of the Commercial ComputerSoftware - Restricted Rights at48CFR52.227-19, as applicable. TheContractor is Cognos Corporation,67 South Bedford Street,Burlington, MA 01803-5164.

Table of ContentsChapter 1: Run a Macro in Scheduler......................... 5Chapter 2: Scheduler OLE Automation ....................... 7Chapter 3: Objects .................................................... 9Chapter 4: Collections ............................................. 21Chapter 5: Methods ................................................ 25Chapter 6: Properties .............................................. 41Index.................................................................... 147Automate Scheduler Using Macros iii

Chapter 1: Run a Macro inSchedulerRun a CognosScript Macro UsingSchedulerDescriptionYou can schedule the execution of a CognosScript macro that runs anyOLE 2.0-compliant application with defined methods and properties. Forexample, you can run a macro that updates your local copy of adistributed Impromptu catalog at the end of every week. Because themacro will run on your computer, you must leave your computerswitched on with Scheduler running in order for the task to execute.The following procedure describes how to schedule a CognosScriptmacro to run at a specified time every day.Steps1. Open the Scheduler application window.2. From the Insert menu, click Recurring Task.3. In the File Name box, either type the file name and path of the newtask, or click Browse to locate the task.For example, you could type:UPDCATLG.MAC4. Type Update Local Catalog to identify the task in the Descriptionbox.5. Click the Timetable tab.6. Select Daily to run the task every day at the same time.7. In the Time box, set the time at which you want the task to run.The Effective From box shows the current date by default. The taskwill run every day at the same time starting today.Automate Scheduler Using Macros 5

Chapter 1: Run a Macro in Scheduler8. If the catalog or the database prompt for user IDs and passwords:• Click Security to show the Security tab (Insert Task dialog box).• Type a user class for the task in the User Class box.• Type the password for the user class in the first User Passwordbox.• If the database supports multiple user IDs, type the database userID for the task in the User box.• If the database supports multiple user IDs, type the passwordassociated with the user ID in the second User Password box.9. Click OK to save the task description.The Insert dialog box closes and the task description appears in thetask list in the Scheduled tab (Scheduler application window).10. Do not close Scheduler. To tidy your desktop, you can click theMinimize button on the top right of the Scheduler applicationwindow.Scheduler runs minimized, and the CognosScript macro will run atthe scheduled time on your computer.6 Automate Scheduler Using Macros

Chapter 2: Scheduler OLEAutomationAutomate Scheduler Using Macros 7

Chapter 2: Scheduler OLE AutomationIntroduction to Scheduler OLE AutomationScheduler exposes automation interfaces for the following objects andcollections:• An Application object that you can use to invoke Scheduler.• A Schedule object that enables you to work with Schedule tasks anda Schedules collection which groups your Schedule objects.• A CompletedJob object that enables you to work with Completedtasks and a CompletedJobs collection which groups yourCompletedJob object.• An Options object that enables you to work with Scheduler options.These objects are in the following hierarchy:8 Automate Scheduler Using Macros

Chapter 3: ObjectsAutomate Scheduler Using Macros 9

Chapter 3: ObjectsApplication ObjectDescriptionAn object providing access to various Scheduler collections, methodsand properties, and containing basic information about the OLE serverenvironment.DiscussionYou create an Application object to start Scheduler from within an OLEautomation script. Create the Scheduler Application object using the Dimcommand to create an object variable and then set it equal to thereference returned by the CreateObject function.ExampleThis example returns a list of all completed tasks, including any witherrors, and displays them in a message box.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strListOfTasks As StringDim strErrors As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")'get a reference to all tasks that have been completedSet objCompletedTasks = _objSchedApp.Completed strListOfTasks = ""For intCounter = 1 To objCompletedTasks.CountIf objCompletedTasks.Item(intCounter).HasErrors ThenstrErrors = " -> Error"ElsestrErrors = ""End IfSet objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrListOfTasks = strListOfTasks & _objCompletedTask.ScheduleDescription strErrors & Chr(13)Next intCounterMsgBox("There are " & Str(objCompletedTasks.Count) & _"completed tasks:" & Chr(13) & strListOfTasks)Set objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubMethod NameVisibleMutuallyExclusiveDescriptionSets the Scheduler main window tovisible.Notifies Scheduler that Impromptu isbeing automated.10 Automate Scheduler Using Macros

Chapter 3: ObjectsProperty NameCommentsCompanyNameCompletedEXEnameLegalCopyrightMajorMinorOptionsRegisteredCompanyRegisteredUserSchedulesDescriptionReturns the build date of the SchedulerOLE server executable.Returns the company name of theScheduler OLE server executable.Returns the collection of CompletedJobobjects.Returns the name of the Scheduler OLEserver executable.Returns the legal copyright of theScheduler OLE server executable.Returns the major build number of theScheduler OLE server executable.Returns the minor build number of theScheduler OLE server executable.Returns the Options object.Returns the company name to whichScheduler is registered.Returns the user to whom Scheduler isregistered.Returns the collection of Scheduleobjects.Automate Scheduler Using Macros 11

Chapter 3: ObjectsProperty NameEndTimeErrorMessageHasErrorsLastViewedResultSetScheduleSharedAsStartTimeDescriptionReturns the date and time the scheduledtask was completed.Returns the error message generatedduring the running of a specific task, ifany.Returns whether an error was generatedwhen a specific task ran.Returns the date and time the result setwas last viewed.Returns whether the completed task wasa remote task.Returns a reference to the parentSchedule object.Returns the last exported file name andlocation of the result set, if any.Returns the date and time the scheduledtask was started.Automate Scheduler Using Macros 13

Chapter 3: ObjectsOptions ObjectDescriptionAn object providing access to Scheduler options.DiscussionThe Options object is accessed through the Application object using theOptions property.Method NameSaveDescriptionSaves the changes to a new or changedOptions object.Property NameApplicationTrayExecuteAtExecuteOnIgnoredSinceIgnoreServerTasksNotifyWithIconNotifyWithSoundPollingFrequencyPurgeCompletedPurgeCompletedAfterDescriptionSets or returns whether to run Schedulerfrom the Taskbar Tray.Sets or returns whether a new task runsimmediately or at the specified time bydefault.Sets or returns whether a new task runslocally or remotely by default.Returns the date and time the run localmode was set.Sets or returns whether Scheduler runs inlocal mode.Sets or returns whether the Schedulericon flashes to notify the user of acompleted server task.Sets or returns whether a sound occurs tonotify the user of a completed server task.Sets or returns the number of minutesbetween connections with the RequestServer by Scheduler for updates onremote tasks.Sets or returns whether Schedulerautomatically purges local tasks uponcompletion.Sets or returns the number of days toelapse before automatically purging alocal completed task.14 Automate Scheduler Using Macros

Chapter 3: ObjectsProperty NameRunAtHourRunAtMinStartWithinUserDescriptionUserEmailWarnPriorToDeleteWarnPriorToExitDescriptionSets or returns the default hour for newtasks.Sets or returns the default minute for newtasks.Sets or returns the number of hours thatcan lapse before a late starting job doesnot run.Sets or returns the description of the user.Sets or returns the e-mail address of theuser.Sets or returns whether Schedulerprompts the user before deleting a task.Sets or returns whether Schedulerprompts the user before exiting whenthere are local tasks to run.Automate Scheduler Using Macros 15

Chapter 3: ObjectsSchedule ObjectDescriptionAn object providing access to a scheduled or incomplete task, andcontaining information about the task.DiscussionFor a run-once task, once a Scheduler completes a task, the Scheduleobject becomes inactive and Scheduler creates a CompletedJob object.For a recurring task, once an instance of the Scheduled task is complete,that instance of the Schedule object becomes a CompletedJob objectwhile the Scheduled task continues to be an active Schedule object untilthe date in the UntilDate property is reached. Access the Scheduleobjects in the Schedules collection to create and delete tasks, anddetermine the properties of scheduled tasks. The Schedule objectcontains useful information such as file names and locations to use inautomation scripts. Use the Item method to access the individualSchedule objects in the Schedules collection.Example 1This example demonstrates the use of the ExecuteOn property of theOptions object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectSet objSchedApp = CreateObject("Cognosbatcher.application")Set objOptions = objSchedApp.Options'an ExecuteOn property value of 5 indicates new tasks are'defaulted to local execution; a value of 6,'indicates new tasks are defaulted to server execution.If objOptions.ExecuteOn = 5 ThenMsgBox "Scheduler is currently configured to default" & _"new tasks to run locally."ElseIf objOptions.ExecuteOn = 6 ThenMsgBox "Scheduler is currently configured to default" & _"new tasks to run on the server."End IfSet objOptions = NothingSet objSchedApp = NothingEnd Sub16 Automate Scheduler Using Macros

Chapter 3: ObjectsExample 2This example schedules a new task whose results print automatically.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My print task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'single execution.ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'print the output of the report.PrintResults = True'PrinterName must be a valid printer available on this machine.PrinterName = "HP LaserJet 5Si/5Si MX"'print only one copy.PrintCopies = 1.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubMethod NameCreateUsingDeleteEditSaveDescriptionCreates a new Schedule object based onan existing Schedule object.Deletes the specified scheduled task.Prevents Scheduler from running a taskwhile the task is edited.Saves the changes to a new or changedSchedule object.Property NameCardinalDayCatlogUsrClsCatLogUsrPwCommandFileNameDescriptionSets or returns the specific day of themonth the task runs.Sets or returns the name of the cataloguser class.Sets the password for the catalog userclass.Sets or returns the path and file name forthe command script to run with theSchedule object.Automate Scheduler Using Macros 17

Chapter 3: ObjectsProperty NameCommandScriptCreateSnapshotDbUsrIdDbUsrPwEffectiveFromExecuteOnExportAsExportFileNameExportTypeHoldHTMLdirectoryHTMLprefixIncludeTOCOrdinalDayPrintCopiesPrintResultsPrinterNamePublishHTMLDescriptionSets or returns whether a command scriptruns while the scheduled report is open.Sets or returns whether to create anImpromptu report snapshot when theSchedule object runs.Sets or returns the name of the databaseuser.Sets the password for the database user.Sets or returns the date the scheduledtask can start to run.Sets or returns whether the task is runlocally or remotely.Sets or returns whether to export thereport.Sets or returns the path and the name ofthe file created from the results of theSchedule object.Sets or returns the type of file createdfrom the results of the Schedule object.Sets or returns whether a local task is onhold.Sets or returns the directory name forHTML files.Sets or returns the prefix for HTML filespublished from Impromptu results.Sets or returns whether to apply table ofcontents options.Sets or returns the first, second, third,fourth, or last day of the week in a monththe task runs.Sets or returns the number of copies of aScheduler report to print.Sets or returns whether to print thereport.Sets or returns the selected printer namefrom the printers visible to the computer.Sets or returns whether to publish thescheduled report as HTML when theSchedule object runs.18 Automate Scheduler Using Macros

Chapter 3: ObjectsProperty NameRecurCycRecurDayOfWkRunAtHourRunAtMinScheduleDescriptionScheduleIdScheduleNameScheduleTypeSnapshotFileNameSuppressMultipleResultSetsTOCoptionsUntilDateDescriptionSets or returns the frequency number fora recurring task regardless of unit.Sets or returns the day of the week or themonth the recurring scheduled task runs.Sets or returns the hour the task runs in a24-hour format.Sets or returns the minute the task is setto run.Sets or returns the description of theSchedule object.Returns the ID of the Schedule object.Sets or returns the path and file name ofthe report or other task to run for aSchedule object.Sets or returns whether the scheduledtask is a recurring task and if so, the unitat which it repeats.Sets or returns the path and file name ofthe snapshot associated with the Scheduleobject.Sets or returns whether to overwrite theprevious result set in a recurring remotetask.Sets or returns the specified table ofcontents options to apply to a scheduledImpromptu report.Sets or returns the date after which arecurring task no longer runs.Automate Scheduler Using Macros 19

Chapter 4: CollectionsAutomate Scheduler Using Macros 21

Chapter 4: CollectionsCompletedJobs CollectionDescriptionAn object that groups and provides access to CompletedJob objects.DiscussionCollections group objects. Access the CompletedJob objects in theCompletedJobs collection, to determine the properties of the completedtasks.ExampleThis example displays all completed tasks and enables the user to deletethem.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.Completed'this loop will start with the most recently completed tasksFor intCounter = objCompletedTasks.Count To 1 Step -1With objCompletedTasks.Item(intCounter)Set objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionintResponse = MsgBox("Delete this task?" & Chr(13) & _strTaskDescription, 292, "Completed Task" & _Str(intCounter))If intResponse = 6 ThenIf objCompletedTask.ExecuteOn = 6 and _.HasErrors True ThenintResponse = MsgBox _("View results for this task before deleting?" & _Chr(13) & strTaskDescription, 292, "View Results")If intResponse = 6 Then'view the results of the task.ViewResultsEnd IfintResponse = MsgBox _("Send the results of this task before deleting" & _Chr(13) & strTaskDescription, 292, "Send Results")If intResponse = 6 Then'send the results of the task.SendResultsEnd IfEnd If'the Delete method will remove the specified completed'task from the list of complete tasks..DeleteEnd IfEnd With22 Automate Scheduler Using Macros

Chapter 4: CollectionsNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubProperty NameCountItemDescriptionReturns the number of items in theCompletedJobs collection.Returns a CompletedJob object from theCompletedJobs collection.Schedules CollectionDescriptionAn object that groups and provides access to Schedule objects.DiscussionCollections group objects. Access the Schedule objects in the Schedulescollection, to determine the properties of the scheduled tasks.ExampleThis example returns a scheduled task and enables the user to changethe execution time to midnight.Sub Main()Dim objSchedApp As ObjectDim objSchedulerTasks As ObjectDim objSpecificTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objSchedulerTasks = objSchedApp.SchedulesSet objSpecificTask = objSchedulerTasks.Item(1)'the Edit method allows modification of this taskobjSpecificTask.Edit'RunAtHour and RunAtMin hold integers representing the hour'(in 24 hour format) and minute of scheduled execution.objSpecificTask.RunAtHour = 3objSpecificTask.RunAtMin = 33'the Save method will apply any modifications made to the'task since the invocation of the Edit methodobjSpecificTask.SaveSet objSpecificTask = NothingSet objSchedulerTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 23

Chapter 4: CollectionsProperty NameCountItemDescriptionReturns the number of items in theSchedules collection.Returns a Schedule object from theSchedules collection.24 Automate Scheduler Using Macros

Chapter 5: MethodsAutomate Scheduler Using Macros 25

Chapter 5: MethodsCreateUsing MethodSyntaxCreateUsing (ScheduleID)Applies ToScheduleDescriptionCreates a new Schedule object based on an existing Schedule object.DiscussionUse this method to copy existing scheduled tasks.ExampleThis example displays all scheduled tasks and enables the user to createnew copies of them.Sub Main()Dim objSchedApp As ObjectDim objScheduledTasks As ObjectDim objNewTask As ObjectDim intCounter As IntegerDim intResponse As IntegerDim strTaskDescription As StringDim strTaskID as StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objScheduledTasks = objSchedApp.SchedulesFor intCounter = 1 to objScheduledTasks.CountstrTaskID = objScheduledTasks.Item(intCounter).ScheduleIDintResponse = MsgBox _("Do you wish to create a new task based on this one?" & _Chr(13) & "Task ID:" & strTaskID & Chr(13)"Description:" & _objScheduledTasks.Item(intCounter).ScheduleDescription,292, _"Replicate this task?")If intResponse = 6 ThenSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.CreateUsing (intCounter).RunAtHour = Val(InputBox("Enter the execution hour in "&_"24 hour format","Execution Time")).RunAtMin = Val(InputBox("Enter the execution minute "&_"format","Execution Time")).EffectiveFrom = Date.SaveEnd WithSet objNewTask = NothingEnd IfNext intCounterSet objNewTask = NothingSet objScheduledTasks = NothingSet objSchedApp = NothingEnd Sub26 Automate Scheduler Using Macros

Chapter 5: MethodsParameterScheduleIDDescriptionRequired. Specifies the scheduleidentification (Schedule object from theSchedules collection) on which to basethe new schedule object.Type: StringNote: This parameter is the same as theScheduleID property of the Scheduleobject.Return TypeObjectDelete Method (Completed Jobs Object)SyntaxCompletedJob.DeleteApplies ToCompletedJobDescriptionDeletes• the specified completed task and the associated Schedule object fora local task that runs once.• the specified completed task, but not the associated Schedule objectfor an active recurring task.• the information about a completed task for a remote task that runsonce.DiscussionUse this method to remove the information about a completed task thatruns once or one instance of a recurring task. To remove every instanceof a recurring task, use the Delete method from the Schedule object.Note: Use this method only when Scheduler is not running. This avoidsproblems with the automatic time-driven routines.Return TypeNothingAutomate Scheduler Using Macros 27

Chapter 5: MethodsExample'This example displays all completed tasks and enables the user to deletethem.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.Completed'this loop will start with the most recently completed tasksFor intCounter = objCompletedTasks.Count To 1 Step -1With objCompletedTasks.Item(intCounter)Set objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionintResponse = MsgBox("Delete this task?" & _Chr(13) strTaskDescription, 292, "Completed Task " & _Str(intCounter))If intResponse = 6 Then'the Delete method will remove the specified completed'task from the list of complete tasks..DeleteEnd IfEnd WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd Sub28 Automate Scheduler Using Macros

Chapter 5: MethodsDelete Method (Schedule Object)SyntaxSchedule.Delete [ContinueOnError]Applies ToScheduleDescriptionDeletes the specified scheduled task.DiscussionUse this method to delete scheduled tasks and any associated completedtasks. This method sends a notice to the request server if it is a remoterequest. If the task is a remote task and an error occurs, Schedulerprompts the user for confirmation to proceed. Use the optionalparameter to ignore the error.ParameterContinueOnErrorDescriptionOptional. Specifies whether Scheduler ignoresserver errors and deletes a remote task.Type: BooleanNote: The valid range of this parameter isTrue or False.Default is False.Return TypeNothingAutomate Scheduler Using Macros 29

Chapter 5: MethodsExampleThis example displays all scheduled tasks and enables the user to deletethem.Sub Main()Dim objSchedApp As ObjectDim objScheduledTasks As ObjectDim intCounter As IntegerDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objScheduledTasks = objSchedApp.Schedules'This loop will start at the bottom of the list of tasksFor intCounter = objScheduledTasks.Count To 1 Step -1With objScheduledTasks.Item(intCounter)strTaskDescription = .ScheduleDescriptionintResponse = MsgBox("Delete this task?" & chr(13) & _strTaskDescription, 292, "Scheduled Task " & Str(intCounter))If intResponse = 6 Then'The Delete method will remove the specified task from the'the list of scheduled tasks. ContinueOnError parameter is'true, so user will not be notified if deletion of a'server task results in an error..Delete (True)End IfEnd WithNext intCounterSet objScheduledTasks = NothingSet objSchedApp = NothingEnd Sub30 Automate Scheduler Using Macros

Chapter 5: MethodsEdit MethodSyntaxSchedule.EditApplies ToScheduleDescriptionPrevents Scheduler from running a task while the task is edited.DiscussionUse this method before changing the properties of an existing Scheduleobject.Return TypeNothingExampleThis example returns a scheduled task and enables the user to changethe run time to midnight.Sub Main()Dim objSchedApp As ObjectDim objSchedulerTasks As ObjectDim objSpecificTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objSchedulerTasks = objSchedApp.SchedulesSet objSpecificTask = objSchedulerTasks.Item(1)'the Edit method enables modification of this taskobjSpecificTask.Edit'RunAtHour and RunAtMin hold integers representing the hour'(in 24 hour format) and minute of scheduled execution.objSpecificTask.RunAtHour = 3objSpecificTask.RunAtMin = 33'the Save method will apply any modifications made to the'task since the invocation of the Edit methodobjSpecificTask.SaveSet objSpecificTask = NothingSet objSchedulerTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 31

Chapter 5: MethodsMutuallyExclusive MethodSyntaxApplication.MutuallyExclusive (Flag)Applies ToApplicationDescriptionNotifies Scheduler that Impromptu is being automated.DiscussionBecause of Impromptu's multitasking limitation, this method is used toenable the application automating Scheduler to signal Scheduler thatImpromptu is being automated.ParameterFlagDescriptionRequired. Specifies whether Impromptu isbeing automated.Type: BooleanThe valid values areTrue - Impromptu is being automated.Scheduler stops any action that involvesautomating Impromptu such as creating anew Impromptu object.False - Impromptu is not being used.Scheduler can continue.Return TypeNothing32 Automate Scheduler Using Macros

Chapter 5: MethodsExampleThis example creates a new task which saves the scheduled report into asnapshot.Sub Main()Dim objSchedApp As ObjectDim objScheduledTasks As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationobjSchedApp.MutuallyExclusive FalseSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My snapshot task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'save the report as a snapshot.CreateSnapshot = True'must be a valid path and unique filename.SnapshotFileName = "C:\MyResults\MySnapshot.imr".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 33

Chapter 5: MethodsSave MethodSyntaxOptions.SaveApplies ToOptionsDescriptionSaves the changes to the Options object.DiscussionThe new information on the Options object is updated in the Schedulerdatabase.Return TypeNothingExampleThis example sets up the user email address and saves the Optionsobject.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectSet objSchedApp = CreateObject("Cognosbatcher.Application")'set up a reference to the Options objectSet objOptions = objSchedApp.OptionsobjOptions.UserEmail = "jdoe@somewhere.com"'the Save method commits any alterations made to the Options'properties; if Save is not used, the changes will be lost when'the reference to the Scheduler Application object is destroyed,'or when Scheduler is closedobjOptions.SaveSet objOptions = NothingSet objSchedApp = NothingEnd Sub34 Automate Scheduler Using Macros

Chapter 5: MethodsSave MethodSyntaxSchedule.Save (ImpApp)Applies ToScheduleDescriptionSaves the changes to a new or changed Schedule object.DiscussionThis method makes a new Schedule object or a modified Scheduleobject persistent.The Edit method must be used before making anychanges to an existing Schedule object. The Save method then finishesthe Edit session. An error can occur if the Schedule object was set (usingthe ExecuteOn property) to be processed by Request Server, butScheduler determines that the process does not require Request Serverbased on the information obtained from Impromptu. For information onwhich requests cannot be sent to the Request Server, see Scheduleronline Help.ParameterImpAppDescriptionOptional. Returns a reference to anImpromptu Application object, if it exists.Type: ObjectIf the Impromptu Application objectexists, Scheduler runs the Impromptuautomation code on the existing object.If the Impromptu Application object doesnot exist, Scheduler creates a newImpromptu object.Return TypeNothingAutomate Scheduler Using Macros 35

Chapter 5: MethodsExampleThis example returns a scheduled task and enables the user to changethe execution time to midnight.Sub Main()Dim objSchedApp As ObjectDim objSchedulerTasks As ObjectDim objSpecificTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objSchedulerTasks = objSchedApp.SchedulesSet objSpecificTask = objSchedulerTasks.Item(1)'the Edit method allows modification of this taskobjSpecificTask.Edit'RunAtHour and RunAtMin hold integers representing the hour'(in 24 hour format) and minute of scheduled execution.objSpecificTask.RunAtHour = 3objSpecificTask.RunAtMin = 33'the Save method will apply any modifications made to the'task since the invocation of the Edit methodobjSpecificTask.SaveSet objSpecificTask = NothingSet objSchedulerTasks = NothingSet objSchedApp = NothingEnd SubSendResults MethodSyntaxCompletedJob.SendResults [FileName]Applies ToCompletedJobDescriptionSends the results by• activating mail and attaching the file to the message for a local taskthat includes options such as save as snapshot or save as external fileformat.• exporting a document to the specified location enabling other usersto view the results for a remote task involving results that completedsuccessfully.36 Automate Scheduler Using Macros

Chapter 5: MethodsDiscussionThe default mail standard is MAPI. However, you can modify the Sendcapability to use your own multi-use OLE component so you can sendinformation via your own system. For more information, see Scheduleronline Help.ParameterFilenameDescriptionOptional (for remote result sets only).Specifies the filename of the exportedresults.Type: StringReturn TypeEmptyExampleThis example enables the user to send the results of a completed taskthat generated a snapshot or exported results.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.Completed'this loop will start with the most recently completed tasksFor intCounter = objCompletedTasks.Count To 1 Step -1With objCompletedTasks.Item(intCounter)Set objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionIf .Schedule.CreateSnapshot = True Or _.Schedule.ExportAs = True ThenintResponse = MsgBox("Send the results of this task" & _"?" & Chr(13) & strTaskDescription, _292, "Send Results")If intResponse = 6 Then'send the results of the task.SendResultsEnd IfEnd IfEnd WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 37

ViewResults MethodSyntaxCompletedJob.ViewResultsApplies ToCompletedJobDescriptionActivates Impromptu to view the results of a successfully completedserver task, and updates the time the completed task was last viewed.DiscussionUsing this method when Scheduler is running can cause problems withthe automatic time-driven routines. To avoid conflicts with the automatictime-driven routines, use it only when Scheduler is not running.Return TypeEmptyExampleThis example allows the user to view the results of completed remotetasks.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.Completed'this loop will start with the most recently completed tasksFor intCounter = objCompletedTasks.Count To 1 Step -1With objCompletedTasks.Item(intCounter)Set objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionIf objCompletedTask.ExecuteOn = 1 and .HasErrors True _Then intResponse = MsgBox("View results for this task" & _"?" & Chr(13) & strTaskDescription, 292, _"View Results")If intResponse = 6 Then'view the results of the task.ViewResultsEnd IfEnd IfEnd WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd Sub

Chapter 5: MethodsVisible MethodSyntaxApplication.VisibleApplies ToApplicationDescriptionSets the Scheduler main window to visible.DiscussionUse this method to force Scheduler to make the main window visibleand to keep Scheduler running. If Scheduler main window is not visibleand the reference to the Scheduler application object is set to Nothing,Scheduler is automatically closed. This method will only make Schedulervisible; it does not make it invisible.Return TypeNothingExampleThe next example shows the syntax for using the Visible method of theapplication object.Sub Main()Dim objSchedApp As ObjectSet objSchedApp = CreateObject("Cognosbatcher.Application")'make Scheduler visible, and therefore leave it open after'objSchedApp is terminatedobjSchedApp.VisibleSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 39

Chapter 6: PropertiesAutomate Scheduler Using Macros 41

Chapter 6: PropertiesApplicationTray PropertySyntaxOptions.ApplicationTrayApplies ToOptionsDescriptionSets or returns whether to run Scheduler from the Taskbar Tray.DiscussionUse this property to run Scheduler from the Taskbar Tray. If thisproperty is set to True, Scheduler runs from the Taskbar Tray. If thisproperty is set to False, Scheduler runs as a regular application.TypeBooleanAccessRead/WriteExampleThis example displays whether Scheduler is set to run from the TaskbarTray.Sub Main()Dim objSchedApp As ObjectDim objSchedOptions As ObjectDim strReturnValue As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objSchedOptions = objSchedApp.OptionsstrReturnValue = objSchedOptions.ApplicationTrayMsgBox "Will Scheduler run from the Taskbar Tray? " & _strReturnValueSet objSchedOptions = NothingSet objSchedApp = NothingEnd Sub42 Automate Scheduler Using Macros

Chapter 6: PropertiesCardinalDay PropertySyntaxSchedule.CardinalDayApplies ToScheduleDescriptionSets or returns the specific day of the month the task runs.DiscussionThis property is valid only when the ScheduleType property is set to 3.The valid range of this property is the number of days in each specificmonth.TypeIntegerAccessRead/WriteExampleThis example schedules a new task to be run on a monthly basis, usingcardinal days (the third day of every month).Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs the third day " & _"of every month".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up monthly, cardinal day base execution.ScheduleType = 3'execute on the third day of every month.CardinalDay = 3.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 43

Chapter 6: PropertiesCatLogUsrCls PropertySyntaxSchedule.CatLogUsrClsApplies ToScheduleDescriptionSets or returns the name of the catalog user class.DiscussionThis property is valid only when the task type is Impromptu orPowerPlay. The maximum length of this property is 31 characters. Usethis only when Impromptu or PowerPlay is started using an alternativeprocess such as a macro file, where Impromptu would expect to requesta catalog user ID.TypeStringAccessRead/Write44 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a macro to run and provides the catalog userclass and password, and the database user ID and password.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My macro task".ScheduleName = "C:\MyMacros\ScheduleMacro.mac".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'This will store MyUserClass as the catalog user class.CatLogUsrCls = "MyUserClass"'This will store MyCatalogPassword as the catalog user'password, in encrypted form..CatLogUsrPw = "MyCatalogPassword"'This will store MyDatabaseID as the database user ID.DbUsrID = "MyDatabaseID"'This will store MyDatabasePassword as the database user'password, in encrypted form..DbUsrPW = "MyDatabasePassword".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 45

Chapter 6: PropertiesCatLogUsrPw PropertySyntaxSchedule.CatLogUsrPwApplies ToScheduleDescriptionSets the password for the catalog user class.DiscussionThis property is valid only when the CatLogUsrCls property is set. Usethis only when Impromptu or PowerPlay is started using an alternativeprocess such as a macro file, where Impromptu would expect to requesta catalog user password. The maximum length of this property is 31characters.TypeStringAccessWrite46 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a macro to run and provides the catalog userclass and password, and the database user ID and password.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My macro task".ScheduleName = "C:\MyMacros\ScheduleMacro.mac".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'This will store MyUserClass as the catalog user class.CatLogUsrCls = "MyUserClass"'This will store MyCatalogPassword as the catalog user'password, in encrypted form..CatLogUsrPw = "MyCatalogPassword"'This will store MyDatabaseID as the database user ID.DbUsrID = "MyDatabaseID"'This will store MyDatabasePassword as the database user'password, in encrypted form..DbUsrPW = "MyDatabasePassword".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 47

Chapter 6: PropertiesCommandFileName PropertySyntaxSchedule.CommandFileNameApplies ToScheduleDescriptionSets or returns the path and file name for the command script to runwith the Schedule object.DiscussionThis property is valid only if the CommandScript property is set to true.The maximum length of this property is 255 characters.TypeStringAccessRead/WriteExampleThis example schedules a new report and indicates that an application isrun while the report is open.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.scheduletype=0.ScheduleDescription = "My CommandScript task".ScheduleName = "c:\program files\cognos\impromptu 5.0\" & _"imp.5.0 samples\reports\annual product sales.imr".RunAtHour = 18.RunAtMin = 45'run a command script every time this task is executed.CommandScript = True.CommandFileName="C:\MyProgramPath\MyProgram.exe".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd Sub48 Automate Scheduler Using Macros

Chapter 6: PropertiesCommandScript PropertySyntaxSchedule.CommandScriptApplies ToScheduleExampleSets or returns whether a command script runs while the scheduledreport is open.DiscussionThis property is valid only when the task type is Impromptu orPowerPlay. The values for this property are• True - the command script runs• False - the command script does not run.Set this property to True before providing the value forCommandFileName.TypeBooleanAccessRead/WriteExampleThis example schedules a new report and indicates that an application isrun while the report is open.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.scheduletype=0.ScheduleDescription = "My CommandScript task".ScheduleName = "c:\program files\cognos\impromptu 5.0\" & _"imp.5.0 samples\reports\annual product sales.imr".RunAtHour = 18.RunAtMin = 45'run a command script every time this task is executedCommandScript=True.CommandFileName = "C:\MyProgramPath\MyProgram.exe".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 49

Chapter 6: PropertiesComments PropertySyntaxApplication.CommentsApplies ToApplicationDescriptionReturns the build date of the Scheduler OLE server executable.TypeStringAccessReadExampleThis example lists the names of all tasks in Scheduler and the build dateof the Scheduler executable.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.CommentsSet SchApp = NothingSet SchObj = NothingEnd Sub50 Automate Scheduler Using Macros

Chapter 6: PropertiesCompanyName PropertySyntaxApplication.CompanyNameApplies ToApplicationDescriptionReturns the company name of the Scheduler OLE server executable.DiscussionUse this property to determine the name of the company responsible forthe Scheduler OLE server executable. By default, this property returnsthe value Cognos Incorporated.TypeStringAccessReadExampleThis example lists the names of all tasks in Scheduler and the name ofthe company responsible for the Scheduler executable.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.CompanyNameSet SchApp = NothingSet SchObj = NothingEnd SubAutomate Scheduler Using Macros 51

Chapter 6: PropertiesCompleted PropertySyntaxApplication.CompletedApplies ToApplicationDescriptionReturns the collection of CompletedJob objects.DiscussionUse this property to create a reference to the CompletedJobs collection.TypeObjectAccessReadExampleThis example returns a list of all completed tasks including errors anddisplays them in a message box.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strListOfTasks As StringDim strErrors As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")'get a reference to all tasks that have been completedSet objCompletedTasks = objSchedApp.CompletedstrListOfTasks = ""For intCounter = 1 To objCompletedTasks.CountIf objCompletedTasks.Item(intCounter).HasErrors ThenstrErrors = " -> Error"ElsestrErrors = ""End IfSet objCompletedTask =objCompletedTasks.Item(intCounter).SchedulestrListOfTasks = strListOfTasks & _objCompletedTask.ScheduleDescription & _strErrors & Chr(13)Next intCounterMsgBox("There are "& Str(objCompletedTasks.Count) & _"completed tasks:" Chr(13) & strListOfTasks)Set objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd Sub52 Automate Scheduler Using Macros

Chapter 6: PropertiesCount PropertySyntaxcollection.CountApplies ToCompletedJobsSchedulesDescriptionReturns the number of items in the CompletedJobs or Schedulescollection.DiscussionUse this property to obtain the number of items in the Schedulescollection. The valid range for this property is greater than or equal tozero. (>= 0)TypeLongAccessReadExampleThis example displays the number of tasks in both the Completed andthe Schedules collection.Sub Main()Dim objSchedApp As ObjectDim objSchedules As ObjectDim objCompletedTasks As ObjectDim intNumberComplete As IntegerDim intNumberSchedules As IntegerSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.CompletedSet objSchedules = objSchedApp.Schedules'get the number of tasks in the Completed collectionintNumberComplete = objCompletedTasks.CountMsgbox "There are " & Str(intNumberComplete) & _"tasks in the completed collection."'get the number of tasks in the Schedules collectionintNumberSchedules = objSchedules.CountMsgbox "There are " & Str(intNumberSchedules) & _"tasks in the schedules collection."Set objSchedules = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 53

Chapter 6: PropertiesCreateSnapshot PropertySyntaxSchedule.CreateSnapshotApplies ToScheduleDescriptionSets or returns whether to create an Impromptu report snapshot whenthe Schedule object runs.DiscussionIf this property is True, the Schedule object creates a snapshot when itruns. If this property is False, the Schedule object does not create asnapshot. If this property is True, and the SnapshotFileName property isNull, the newly-created snapshot uses the .ims extension with the reportfile name.TypeBooleanAccessRead/Write54 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example creates a new task which saves the scheduled report into asnapshot.Sub Main()Dim objSchedApp As ObjectDim objScheduledTasks As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationobjSchedApp.MutuallyExclusive FalseSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My snapshot task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'save the report as a snapshot.CreateSnapshot = True'must be a valid path and unique filename.SnapshotFileName = "C:\MyResults\MySnapshot.imr".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 55

Chapter 6: PropertiesDbUsrId PropertySyntaxSchedule.DbUsrIdApplies ToScheduleDescriptionSets or returns the name of the database user.DiscussionThis property is valid only when the task type is not Impromptu orPowerPlay. The maximum length of this property is 31 characters. Usethis only when an alternative process such as a macro starts Impromptuor PowerPlay, and where Impromptu would expect to request adatabase user ID.TypeStringAccessRead/Write56 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a macro to run and provides the catalog userclass and password, and the database user ID and password.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My macro task".ScheduleName = "C:\MyMacros\ScheduleMacro.mac".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'This will store MyUserClass as the catalog user class.CatLogUsrCls = "MyUserClass"'This will store MyCatalogPassword as the catalog user'password, in encrypted form..CatLogUsrPw = "MyCatalogPassword"'This will store MyDatabaseID as the database user ID.DbUsrID = "MyDatabaseID"'This will store MyDatabasePassword as the database user'password, in encrypted form..DbUsrPW = "MyDatabasePassword".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 57

Chapter 6: PropertiesDbUsrPw PropertySyntaxSchedule.DbUsrPwApplies ToScheduleDescriptionSets the password for the database user.DiscussionThis property is valid only when the DbUsrId property is set. Use thisonly when Impromptu or PowerPlay is started using an alternativeprocess such as a macro file, where Impromptu would expect to requesta database user password.TypeStringAccessWrite58 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a macro to run and provides the catalog userclass and password, and the database user ID and password.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My macro task".ScheduleName = "C:\MyMacros\ScheduleMacro.mac".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'This will store MyUserClass as the catalog user class.CatLogUsrCls = "MyUserClass"'This will store MyCatalogPassword as the catalog user'password, in encrypted form..CatLogUsrPw = "MyCatalogPassword"'This will store MyDatabaseID as the database user ID.DbUsrID = "MyDatabaseID"'This will store MyDatabasePassword as the database user'password, in encrypted form..DbUsrPW = "MyDatabasePassword".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 59

Chapter 6: PropertiesEffectiveFrom PropertySyntaxSchedule.EffectiveFromApplies ToScheduleDescriptionSets or returns the date the scheduled task can start to run.DiscussionFor a task that is run once, this property specifies the day to run the task.For a recurring task, EffectiveFrom specifies the date to start to considerrunning the task. If the UntilDate property is set, the value for thisproperty must be less than the UntilDate property.TypeDateAccessRead/Write60 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task to be run on a monthly basis usingordinal dates (the first Monday of every month) during the period fromMarch 15 to June 12, 1998.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs on the first " & _"Monday of every month".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up monthly execution, ordinal day.ScheduleType = 4'set up to run every month.RecurCyc = 1'set up to run on the first (OrdinalDay = 1)'Monday (RecurDayOfWk = Hex 2) of the month.RecurDayOfWk = &H02.OrdinalDay = 1'set up this task to only be considered for execution between'March 15, 1998 and June 12, 1998.EffectiveFrom = #3/15/1998#.UntilDate = #6/12/1998#.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 61

Chapter 6: PropertiesExampleThis example displays all completed tasks and their related details.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strErrors As StringDim strStartedAt As StringDim strEndedAt As StringDim strLastSeen As StringDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.CompletedFor intCounter = 1 To objCompletedTasks.CountWith objCompletedTasks.Item(intCounter)If .HasErrors ThenstrErrors = "Error: " & .ErrorMessageElsestrErrors = "No Errors"End IfstrStartedAt = .StartTimestrEndedAt = .EndTimeIf Not(.LastViewed=&H0) ThenstrLastSeen = "Last Viewed: " & str(.LastViewed)ElsestrLastSeen = "Results not yet viewed."End IfSet objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionMsgBox strTaskDescription & Chr(13) & "Start Time: " & _strStartedAt & Chr(13) & "End Time: " & _strEndedAt & chr(13) strLastSeen & _chr(13) & strErrors, 64, "Completed Task " & Str(intCounter)End WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 65

Chapter 6: PropertiesExecuteAt PropertySyntaxOptions.ExecuteAtApplies ToOptionsDescriptionSets or returns whether a new task runs immediately or at the specifiedtime by default.DiscussionUse this property to set the default time a new task runs. The values forthis property are• 2 - Execute Now• 7 - Specified TimeTypeIntegerAccessRead/Write66 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example demonstrates the ExecuteAt, RunAtHour and RunAtMinproperties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerDim strQualifier As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptionsIf .ExecuteAt=2 Then'Scheduler is set to use immediate execution'as the default for new tasksintResponse = msgbox("Scheduler is currently configured "&_"to default new tasks to immediate execution. Do you wish " & _"to change this?",259,"Immediate Execution")If intResponse = 6 Then.ExecuteAt = 7'switch to using the specified time in RunAtHour'and RunAtMin properties of the Options object.RunAtHour = val(inputbox("Type in a new default " & _"execution hour(24 hour clock) for new tasks or press" & _"ENTER to accept the current setting.", _"Default Execution Hour",.RunAtHour)).RunAtMin = val(inputbox("Type in a new default " & _"execution minute for new tasks or press ENTER to " & _"accept the current setting.","Default Execution" & _"Minute",.RunAtMin)).SaveEnd IfElseIf .ExecuteAt = 7 Then'Scheduler is set to use specified time execution'as the default for new tasksintResponse = msgbox("Scheduler is currently configured" & _"to default " & _"new tasks to execution at a specified time. " & _"Do you wish to change this?",259,"Delayed Execution")If intResponse = 6 Then.ExecuteAt = 2'switch to immediate execution as the default'for new tasksEnd IfEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 67

Chapter 6: PropertiesExecuteOn PropertySyntaxObject.ExecuteOnApplies ToOptionsScheduleDescriptionSets or returns• whether all new tasks run locally or remotely, by default, for theOptions object.• whether this task runs locally or remotely for the Schedule object.DiscussionUse this property to set the default location where a new task runs. As inScheduler, all rules regarding new tasks apply when this property is set.The values for this property are• 5 - My Computer (locally)• 6 - A Server (remotely)For a Schedule object, you can only set this property to a server for anImpromptu report without attributes that require user input. You cannotchange this property after the Schedule object is saved.TypeIntegerAccessRead/Write68 Automate Scheduler Using Macros

Chapter 6: PropertiesExample 1This example demonstrates the use of the ExecuteOn property of theOptions object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectSet objSchedApp = CreateObject("Cognosbatcher.application")Set objOptions = objSchedApp.Options'an ExecuteOn property value of 5 indicates new tasks are'defaulted to local execution; a value of 6, indicates new tasks'are defaulted to server execution.If objOptions.ExecuteOn = 5 ThenMsgBox "Scheduler is currently configured to default new " & _"tasks to run locally."ElseIf objOptions.ExecuteOn = 6 ThenMsgBox "Scheduler is currently configured to default new " & _"tasks to run on the server."End IfSet objOptions = NothingSet objSchedApp = NothingEnd SubExample 2This example schedules a server task that runs every day at 6:45pmoverwriting the previous result set.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleType = 1.ScheduleDescription = "My new server task".ScheduleName = "c:\MyReports\MyServerReport.imr"'an ExecuteOn value of 1 indicates execution is to'take place on a server;'a value of 0 indicates execution on the local machine.ExecuteOn = 1.RecurCyc = 1.EffectiveFrom = Date.RunAtHour = 18.RunAtMin = 45'since this is a recurring task, overwrite'the previous result set'every time the task is run.SuppressMultipleResultSets = True.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 69

Chapter 6: PropertiesEXEname PropertySyntaxApplication.EXEnameApplies ToApplicationDescriptionReturns the name of the Scheduler OLE server executable.DiscussionUse this property to determine the name of the Scheduler OLE serverexecutable.TypeStringAccessReadExampleThis example lists the names of all tasks in Scheduler and the name ofthe accessed Scheduler application.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.EXEnameSet SchApp = NothingSet SchObj = NothingEnd Sub70 Automate Scheduler Using Macros

Chapter 6: PropertiesExportAs PropertySyntaxSchedule.ExportAsApplies ToScheduleDescriptionSets or returns whether to export the report.DiscussionThis property is available only for Impromptu and PowerPlay reports. Thevalues for this property are• True - export the report• False - do not export the reportTypeBooleanAccessRead/WriteExampleThis example schedules a new task and exports the results to an Excelfile.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new exporting task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 13.RunAtMin = 20.EffectiveFrom = Date'export the results.ExportAs = True'export the results in Excel format.ExportType = "xls"'must supply a valid path and new file name.ExportFileName = "C:\MyExportFiles\ExcelExport.xls".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 71

Chapter 6: PropertiesExportFileName PropertySyntaxSchedule.ExportFileNameApplies ToScheduleDescriptionSets or returns the path and the name of the file created from the resultsof the Schedule object.DiscussionUse this property to set or determine the name of the exported file. Thisproperty is valid only when ExportAs is True. The maximum length ofthis property is 255 characters.TypeStringAccessRead/WriteExampleThis example schedules a new task and exports the results to an Excelfile.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new exporting task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 13.RunAtMin = 20.EffectiveFrom = Date'export the results.ExportAs = True'export the results in Excel format.ExportType = "xls"'must supply a valid path and new file name.ExportFileName = "C:\MyExportFiles\ExcelExport.xls".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd Sub72 Automate Scheduler Using Macros

Chapter 6: PropertiesExportType PropertySyntaxSchedule.ExportTypeApplies ToScheduleDescriptionSets or returns the type of file created from the results of the Scheduleobject.DiscussionUse this property to set or determine the type of export file for theresults of your Impromptu or PowerPlay report. You must use the threecharacter file extension without the dot, not the file type name, to setthis property.Note: Impromptu generates the exact file name entered by the user,while PowerPlay adds the three character extension of the file type. Forexample, if a user generates an Excel file from a scheduled report andenters "myfile" as the name of the file, Impromptu exports the file as"myfile" and PowerPlay exports the file as "myfile.xls"The export file types for an Impromptu report can be• dBASE (dbf)• Delimited ASCII (csv)• Excel (xls)• HotFile (ims)• Lotus 1-2-3 (wk1)• PowerPlay (dat)• SQL (sql)• Text (txt)• Transformer (iqd)The export file types for a PowerPlay report can be• Delimited ASCII (csv)• Excel (xls)TypeStringAccessRead/WriteAutomate Scheduler Using Macros 73

Chapter 6: PropertiesExampleThis example schedules a new task and exports the results to an Excelfile.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new exporting task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 13.RunAtMin = 20.EffectiveFrom = Date'export the results.ExportAs = True'export the results in Excel format.ExportType = "xls"'must supply a valid path and new file name.ExportFileName = "C:\MyExportFiles\ExcelExport.xls".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubHasErrors PropertySyntaxCompletedJob.HasErrorsApplies ToCompletedJobDescriptionReturns whether an error was generated when a specific task ran.DiscussionUse this property to determine whether an error was generated during theperformance of the task, and then use the ErrorMessage property toobtain the error message.The values for this property are• True - an error was generated• False - no error was geneartatedTypeBoolean74 Automate Scheduler Using Macros

Chapter 6: PropertiesAccessReadExampleThis example displays all completed tasks and their related details.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strErrors As StringDim strStartedAt As StringDim strEndedAt As StringDim strLastSeen As StringDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.CompletedFor intCounter = 1 To objCompletedTasks.CountWith objCompletedTasks.Item(intCounter)If .HasErrors ThenstrErrors = "Error: " & .ErrorMessageElsestrErrors = "No Errors"End IfstrStartedAt = .StartTimestrEndedAt = .EndTimeIf Not(.LastViewed=&H0) ThenstrLastSeen = "Last Viewed: " & str(.LastViewed)ElsestrLastSeen = "Results not yet viewed."End IfSet objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionMsgBox strTaskDescription & Chr(13) & "Start Time: " & _strStartedAt & Chr(13) & "End Time: " & _strEndedAt & chr(13) strLastSeen & _chr(13) & strErrors, 64,"Completed Task " Str(intCounter)End WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 75

Chapter 6: PropertiesHold PropertySyntaxSchedule.HoldApplies ToScheduleDescriptionSets or returns whether a local task is on hold.DiscussionThis property is ignored for remote and inactive tasks.The values for thisproperty are• True - the task is on hold• False - the task is not on holdTypeBooleanAccessRead/Write76 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example displays all tasks and allows the user to toggle their holdstatus. All completed tasks will show up as being "on hold". Attempts totoggle the hold status of a completed task will result in an error.Sub Main()Dim objSchedApp As ObjectDim intCounter As IntegerDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")For intCounter = 1 To objSchedApp.Schedules.CountWith objSchedApp.Schedules.Item(intCounter)If .Hold = True ThenstrQualifier = " is "ElsestrQualifier = " is not "End IfintResponse = MsgBox("The following task" & strQualifier & _"on hold:" & Chr(13) & .ScheduleDescription Chr(13) & _"Do you wish to change this?",292, "Toggle Hold status")If intResponse = 6 Then'toggle the current hold status; if this is a completed'task,this will not work, as completed tasks cannot be'editted..Edit.Hold = Not(.Hold).SaveEnd IfEnd WithNext intCounterSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 77

Chapter 6: PropertiesHTMLdirectory PropertySyntaxSchedule.HTMLdirectoryApplies ToScheduleDescriptionSets or returns the directory name for HTML files.DiscussionUse this property to set or determine the directory for HTML filespublished from Impromptu or PowerPlay reports. The maximum lengthof this property is 255 characters.TypeStringAccessRead/Write78 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task, and sets it to publish the results toHTML documents, including a table of contents with page numbers.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My HTML task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'set up the task to publish its results to files in HTML format.PublishHTML = True'HTML Directory must be a valid path.HTMLDirectory = "C:\HTML_Documents"'HTMLPrefix will be placed in the file name for each of the'HTML files'produced.HTMLPrefix = "IH_"'include a table of contents.IncludeTOC = True'include page numbers (Hex 02).TOCOptions = &H02.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 79

Chapter 6: PropertiesHTMLprefix PropertySyntaxSchedule.HTMLprefixApplies ToScheduleDescriptionSets or returns the prefix for HTML files published from Imprompturesults.DiscussionUse this property to set or determine the prefix to group the HTML filespublished from completed Impromptu reports. The maximum length ofthis property is 255 characters.TypeStringAccessRead/Write80 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task, and sets it to publish the results toHTML documents, including a table of contents with page numbers.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My HTML task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'set up the task to publish its results to files in HTML format.PublishHTML = True'HTML Directory must be a valid path.HTMLDirectory = "C:\HTML_Documents"'HTMLPrefix will be placed in the file name'for each of the HTML files'produced.HTMLPrefix = "IH_"'include a table of contents.IncludeTOC = True'include page numbers (Hex 02).TOCOptions = &H02.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 81

Chapter 6: PropertiesIgnoredSince PropertySyntaxOptions.IgnoredSinceApplies ToOptionsDescriptionReturns the date and time the run local mode was set.DiscussionUse this property to determine when run local mode was set.TypeDateAccessRead82 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example demonstrates the use of the IgnoreServerTasks andIgnoredSince properties of the Options object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'IgnoreServerTasks is Boolean indicates if Scheduler is'configured to run locally onlyIf .IgnoreServerTasks Then'IgnoredSince is a read only property that indicates the'last time IgnoreServerTasks was set to TRUEintResponse = MsgBox("Scheduler has been configured to "&_"run locally since " & .IgnoredSince & _". Would you like to switch to run using the server? " & _"(NOTE: If you do not have the connector option " & _"installed, Scheduler will always be set to run " & _"locally.)",259,"Run Locally")If intResponse = 6 Then.IgnoreServerTasks = False.SaveEnd IfElseintResponse = MsgBox("Scheduler has been configured to " & _"run using the server. Would you like to switch to " & _"run locally?",259,"Run on the Server")If intResponse = 6 Then.IgnoreServerTasks = True.SaveEnd IfEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 83

Chapter 6: PropertiesIgnoreServerTasks PropertySyntaxOptions.IgnoreServerTasksApplies ToOptionsDescriptionSets or returns whether Scheduler runs in local mode.DiscussionIf Impromptu Server Connector is not installed on your computer, thisproperty is always set to True by default.TypeBooleanAccessRead/Write84 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example demonstrates the use of the IgnoreServerTasks andIgnoredSince properties of the Options object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'IgnoreServerTasks is Boolean indicates if Scheduler is'configured to'run locally onlyIf .IgnoreServerTasks Then'IgnoredSince is a read only property that indicates the'last time IgnoreServerTasks was set to TRUEintResponse = MsgBox("Scheduler has been configured to " & _"run locally since " & .IgnoredSince & _". Would you like to switch to run using the server? " & _"(NOTE: If you do not have the connector option" & _" installed, Scheduler will always be set to run" & _" locally.)",259,"Run Locally")If intResponse = 6 Then.IgnoreServerTasks = False.SaveEnd IfElseintResponse = MsgBox("Scheduler has been configured to " & _"run using the server. Would you like to switch to run "&_"locally?",259,"Run on the Server")If intResponse = 6 Then.IgnoreServerTasks = True.SaveEnd IfEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 85

Chapter 6: PropertiesIncludeTOC PropertySyntaxSchedule.IncludeTOCApplies ToScheduleDescriptionSets or returns whether to apply table of contents options.DiscussionThis property is valid only for Impromptu reports. The values for thisproperty are• True - TOC options are applied• False - TOC options are not appliedNote: This property overrides any defaults set in Impromptu.TypeBooleanAccessRead/Write86 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task, and sets it to publish the results toHTML documents, including a table of contents with page numbers.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My HTML task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'set up the task to publish its results to files in HTML format.PublishHTML = True'HTML Directory must be a valid path.HTMLDirectory = "C:\HTML_Documents"'HTMLPrefix will be placed in the file name'for each of the HTML files produced.HTMLPrefix = "IH_"'include a table of contents.IncludeTOC = True'include page numbers (Hex 02).TOCOptions = &H02.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 87

Chapter 6: PropertiesItem PropertySyntaxcollection.Item(Index)Applies ToCompletedJobsSchedulesDescriptionReturns the item in the Schedules or CompletedJobs collection.DiscussionUse this method to select individual items in the collection. If the valuefor the index does not match any existing item in the collection, an erroroccurs.ParameterIndexDescriptionRequired. Specifies the position of theitem in the collection.Type: IntegerNote: The valid range of this parameter isthe number of objects in the specificcollection.Return TypeObject88 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example returns the first completed task, including any errors anddisplays it in a message box.Sub Main()Dim objSchedApp As ObjectDim objScheduleTask As ObjectDim objCompletedTask As ObjectDim strDescription As StringDim strErrorMessage As StringDim strErrors As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")'get a reference to the first completed task.Set objCompletedTask = objSchedApp.Completed.Item(1)Set objScheduleTask = objCompletedTask.SchedulestrDescription = objScheduleTask.ScheduleDescriptionIf objCompletedTask.HasErrors ThenstrErrorMessage = objScheduleTask.ErrorMessageMsgBox strDescription & " had the following error:" & _strErrorMessageElseMsgBox strDescription & " had no errors."End IfSet objScheduleTask = NothingSet objCompletedTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 89

Chapter 6: PropertiesLastViewed PropertySyntaxCompletedJob.LastViewedApplies ToCompletedJobDescriptionReturns the date and time the result set was last viewed.DiscussionFor remote result set requests, this property indicates when the resultswere last viewed within Impromptu. A null value indicates that theresults have not been read.TypeDateAccessRead90 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example displays all completed tasks and their related details.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strErrors As StringDim strStartedAt As StringDim strEndedAt As StringDim strLastSeen As StringDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.CompletedFor intCounter = 1 To objCompletedTasks.CountWith objCompletedTasks.Item(intCounter)If .HasErrors ThenstrErrors = "Error: " & .ErrorMessageElsestrErrors = "No Errors"End IfstrStartedAt = .StartTimestrEndedAt = .EndTimeIf Not(.LastViewed=&H0) ThenstrLastSeen = "Last Viewed: " & str(.LastViewed)ElsestrLastSeen = "Results not yet viewed."End IfSet objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionMsgBox strTaskDescription & Chr(13) & "Start Time: " & _strStartedAt & Chr(13) & "End Time: " & _strEndedAt & chr(13) & strLastSeen & chr(13)& _strErrors, 64, "Completed Task " & Str(intCounter)End WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 91

Chapter 6: PropertiesLegalCopyright PropertySyntaxApplication.LegalCopyrightApplies ToApplicationDescriptionReturns the legal copyright of the Scheduler OLE server executable.DiscussionUse this property to obtain the legal copyright of the Scheduler OLEserver executable.TypeStringAccessReadExampleThis example lists the names of all tasks in Scheduler and the legalcopyright associated with the Scheduler application.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.LegalCopyrightSet SchApp = NothingSet SchObj = NothingEnd Sub92 Automate Scheduler Using Macros

Chapter 6: PropertiesMajor PropertySyntaxApplication.MajorApplies ToApplicationDescriptionReturns the major build number of the Scheduler OLE server executable.DiscussionUse this property to determine the major build number of the SchedulerOLE server executable.TypeLongAccessReadExampleThis example lists the names of all tasks in Scheduler and the majorbuild number of the Scheduler application.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.MajorSet SchApp = NothingSet SchObj = NothingEnd SubAutomate Scheduler Using Macros 93

Chapter 6: PropertiesMinor PropertySyntaxApplication.MinorApplies ToApplicationDescriptionReturns the minor build number of the Scheduler OLE server.DiscussionUse this property to determine the minor build number of the SchedulerOLE server application.TypeLongAccessReadExampleThis example lists the names of all tasks in Scheduler and the minorbuild number of the Scheduler application.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.MinorSet SchApp = NothingSet SchObj = NothingEnd Sub94 Automate Scheduler Using Macros

Chapter 6: PropertiesNotifyWithIcon PropertySyntaxOptions.NotifyWithIconApplies ToOptionsDescriptionSets or returns whether the Scheduler icon flashes to notify the user of acompleted server task.DiscussionUse to notify the user of a completed server task. You can use thisproperty in conjunction with the NotifyWithSound property.TypeBooleanAccessRead/WriteAutomate Scheduler Using Macros 95

Chapter 6: PropertiesExampleThis example demonstrates the use of the NotifyWithIcon andNotifyWithSound properties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'if NotifyWithIcon is TRUE, Scheduler will flash an icon when'a remote task is completeIf .NotifyWithIcon ThenstrQualifier = ""ElsestrQualifier = "not "End IfintResponse = MsgBox("Scheduler is " & strQualifier & _"currently configured to notify the user with an flashing " & _"icon when a remote task is complete. Do you wish to " & _"change this setting?", 4,"Icon Notification")If intResponse = 6 Then.NotifyWithIcon = Not(.NotifyWithIcon).SaveEnd If'if NotifyWithSound is TRUE, Scheduler will beep when a'remote) task is completeIf .NotifyWithSound ThenstrQualifier = ""ElsestrQualifier = "not "End IfintResponse = msgbox("Scheduler is " & strQualifier & _"currently configured to notify the user with a beep when" & _"a remote task is complete. Do you wish to change this" & _"setting?",4,"Sound Notification")If intResponse = 6 Then.NotifyWithSound = Not(.NotifyWithSound).SaveEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub96 Automate Scheduler Using Macros

Chapter 6: PropertiesNotifyWithSound PropertySyntaxOptions.NotifyWithSoundApplies ToOptionsDescriptionSets or returns whether a sound occurs to notify the user of a completedserver task.DiscussionUse to notify the user of a completed server task only. This property canbe used in conjunction with the NotifyWithIcon property. You can mapa default sound through the Windows Control Panel.TypeBooleanAccessRead/WriteAutomate Scheduler Using Macros 97

Chapter 6: PropertiesExampleThis example demonstrates the use of the NotifyWithIcon andNotifyWithSound properties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'if NotifyWithIcon is TRUE, Scheduler will flash an icon when'a remote task is completeIf .NotifyWithIcon ThenstrQualifier = ""ElsestrQualifier = "not "End IfintResponse = MsgBox("Scheduler is " & strQualifier & _"currently configured to notify the user with an flashing " & _"icon when a remote task is complete. Do you wish to " & _"change this setting?", 4,"Icon Notification")If intResponse = 6 Then.NotifyWithIcon = Not(.NotifyWithIcon).SaveEnd If'if NotifyWithSound is TRUE, Scheduler will beep when a'(remote)task is completeIf .NotifyWithSound ThenstrQualifier = ""ElsestrQualifier = "not "End IfintResponse = msgbox("Scheduler is " & strQualifier & _"currently configured to notify the user with a beep when " & _"a remote task is complete. Do you wish to change this " & _"setting?",4,"Sound Notification")If intResponse = 6 Then.NotifyWithSound = Not(.NotifyWithSound).SaveEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub98 Automate Scheduler Using Macros

Chapter 6: PropertiesOptions PropertySyntaxApplication.OptionsApplies ToApplicationsDescriptionReturns the Options object.DiscussionUse this property to access the Options object.TypeIntegerAccessReadExampleThis example demonstrates the use of the ExecuteOn property of theOptions object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectSet objSchedApp = CreateObject("Cognosbatcher.application")Set objOptions = objSchedApp.Options'an ExecuteOn property value of 5 indicates new tasks are'defaulted to local execution; a value of 6, indicates new'tasks are defaulted to server execution.If objOptions.ExecuteOn = 5 ThenMsgBox "Scheduler is currently configured to " & _"default new tasks to run locally."ElseIf objOptions.ExecuteOn = 6 ThenMsgBox "Scheduler is currently configured to " & _"default new tasks to run on the server."End IfSet objOptions = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 99

Chapter 6: PropertiesOrdinalDay PropertySyntaxSchedule.OrdinalDayApplies ToScheduleDescriptionSets or returns the first, second, third, fourth, or last day of the week in amonth the task runs.DiscussionUse this property only when the ScheduleType is 4 (monthly ordinal day).The values for this property are• 01 - first• 02 - second• 03 - third• 04 - fourth• 05 - lastTypeIntegerAccessRead/Write100 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task to be run on a monthly basis usingordinal dates (the first Monday of every month) during the period fromMarch 15 to June 12, 1998.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs on the first " & _"Monday of every month".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up monthly execution, ordinal day.ScheduleType = 4'set up to run every month.RecurCyc = 1'set up to run on the first (OrdinalDay = 1)'Monday (RecurDayOfWk = Hex 2) of the month.RecurDayOfWk = &H02.OrdinalDay = 1'set up this task to only be considered for execution between'March 15, 1998 and June 12, 1998.EffectiveFrom = #3/15/1998#.UntilDate = #6/12/1998#.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 101

Chapter 6: PropertiesPollingFrequency PropertySyntaxOptions.PollingFrequencyApplies ToOptionsDescriptionSets or returns the number of minutes between connections with theRequest Server by Scheduler for updates on remote tasks.DiscussionUse this property to indicate the number of minutes for Scheduler towait between connections to the Request Server to receive updates onremote tasks. The valid range of minutes is 1-360.TypeIntegerAccessRead/WriteExampleThis example demonstrates the use of the PollingFrequency property ofthe Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intCurrentFrequency As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptionsintCurrentFrequency = .PollingFrequency'PollingFrequency contains an integer valuePollingFrequency = val(InputBox("The current interval " & _"between task updates from the server is " & _str(intCurrentFrequency) " minutes. Type in a new value " & _"or press ENTER to accept the current value.","Server " & _"Polling Frequency", intCurrentFrequency)).SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub102 Automate Scheduler Using Macros

Chapter 6: PropertiesPrintCopies PropertySyntaxSchedule.PrintCopiesApplies ToScheduleDescriptionSets or returns the number of copies of a Scheduler report to print.DiscussionUse this property only when the PrintResults property is set to True. Thevalues for this property are 1-999.TypeIntegerAccessRead/WriteExampleThis example schedules a new task whose results will be printedautomatically.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My print task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'single execution.ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'print the output of the report.PrintResults = True'PrinterName must be a valid printer available on this machine.PrinterName = "HP LaserJet 5Si/5Si MX"'print only one copy.PrintCopies = 1.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 103

Chapter 6: PropertiesPrintResults PropertySyntaxSchedule.PrintResultsApplies ToScheduleDescriptionSets or returns whether to print the report.DiscussionThis property can be specified for only Impromptu or PowerPlay reports.The values for this property are• True - print the report• False - do not print the report (Default)For local requests, you cannot set this property if no printers areinstalled on the computer.TypeBooleanAccessRead/Write104 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task whose results will be printedautomatically.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My print task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'single execution.ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'print the output of the report.PrintResults = True'PrinterName must be a valid printer available on this machine.PrinterName = "HP LaserJet 5Si/5Si MX"'print only one copy.PrintCopies = 1.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 105

Chapter 6: PropertiesPrinterName PropertySyntaxSchedule.PrinterNameApplies ToScheduleDescriptionSets or returns the selected printer name from the printers visible to thecomputer.DiscussionThe name of the printer must be valid. The maximum length of thisproperty is 255 characters.TypeStringAccessRead/WriteExampleThis example schedules a new task whose results will be printedautomatically.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My print task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'single execution.ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'print the output of the report.PrintResults = True'PrinterName must be a valid printer available on this machine.PrinterName = "HP LaserJet 5Si/5Si MX"'print only one copy.PrintCopies = 1.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd Sub106 Automate Scheduler Using Macros

Chapter 6: PropertiesPublishHTML PropertySyntaxSchedule.PublishHTMLApplies ToScheduleDescriptionSets or returns whether to publish the scheduled report as HTML whenthe Schedule object runs.DiscussionThis property is available only for Impromptu and PowerPlay reports. Thevalues for this property are:• True - publish the scheduled report as HTML• False - do not publish the schedule report as HTMLTypeBooleanAccessRead/WriteAutomate Scheduler Using Macros 107

Chapter 6: PropertiesExampleThis example schedules a new task, and sets it to publish the results toHTML documents, including a table of contents with page numbers.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My HTML task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'set up the task to publish its results to files in HTML format.PublishHTML = True'HTML Directory must be a valid path.HTMLDirectory = "C:\HTML_Documents"'HTMLPrefix will be placed in the file name'for each of the HTML files'produced.HTMLPrefix = "IH_"'include a table of contents.IncludeTOC = True'include page numbers (Hex 02).TOCOptions = &H02.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd Sub108 Automate Scheduler Using Macros

Chapter 6: PropertiesPurgeCompleted PropertySyntaxOptions.PurgeCompletedApplies ToOptionsExampleSets or returns whether Scheduler automatically purges local tasks uponcompletion.DiscussionUse this property to determine whether Scheduler purges completedtasks automatically.TypeBooleanAccessRead/WriteAutomate Scheduler Using Macros 109

Chapter 6: PropertiesExampleThis example demonstrates the use of the PurgeComplete andPurgeCompletedAfter properties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerDim strQualifier As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'PurgeCompleted is a Boolean propertyIf .PurgeCompleted ThenstrQualifier = ""ElsestrQualifier = " not"End IfintResponse = MsgBox("Scheduler currently is" & _strQualifier " configured to automatically purge " & _"completed tasks. Do you wish to toggle this " & _"setting?",259,"Toggle automatic purging?")If intResponse = 6 Then.PurgeCompleted = Not(.PurgeCompleted)End IfIf .PurgeCompleted Then'PurgeCompletedAfter is an integer value.PurgeCompletedAfter = Val(InputBox("Scheduler is " & _"currently configured to purge completed tasks " & _"automatically after" Str(.PurgeCompletedAfter) & _"days. Type in a new value or press ENTER to accept the" & _"current value.", _"Automatic purging of completed tasks", _.PurgeCompletedAfter))End If.SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub110 Automate Scheduler Using Macros

Chapter 6: PropertiesPurgeCompletedAfter PropertySyntaxOptions.PurgeCompletedAfterApplies ToOptionsDescriptionSets or returns the number of days to elapse before automaticallypurging a local completed task.DiscussionUse this property to indicate the number of days to wait beforeScheduler automatically deletes completed tasks. The PurgeCompletedproperty must be set to True. The valid days are 1-256.TypeIntegerAccessRead/WriteAutomate Scheduler Using Macros 111

Chapter 6: PropertiesExampleThis example demonstrates the use of the PurgeComplete andPurgeCompletedAfter properties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerDim strQualifier As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'PurgeCompleted is a Boolean propertyIf .PurgeCompleted ThenstrQualifier = ""ElsestrQualifier = " not"End IfintResponse = MsgBox("Scheduler currently is " & _strQualifier & " configured to automatically purge " & _"completed tasks. Do you wish to toggle this setting? " & _,259,"Toggle automatic purging?")If intResponse = 6 Then.PurgeCompleted = Not(.PurgeCompleted)End IfIf .PurgeCompleted Then'PurgeCompletedAfter is an integer value.PurgeCompletedAfter = Val(InputBox("Scheduler is " & _"currently configured to purge completed tasks " &_"automatically after" & Str(.PurgeCompletedAfter) & _"days. Type in a new value or press ENTER to accept " & _"the current value.", "Automatic purging of completed " & _"tasks",.PurgeCompletedAfter))End If.SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd SubRecurCyc PropertySyntaxSchedule.RecurCycApplies ToScheduleDesriptionSets or returns the frequency number for a recurring task regardless ofunit.112 Automate Scheduler Using Macros

Chapter 6: PropertiesDiscussionThe frequency number denotes how often a recurring task runsregardless of unit. For example, for every 2 days the frequency numberis 2 and for every 15 hours, the frequency number is 15. The range forthis property is 1-99 and the Schedule object must been of a recurringtype. Use the ScheduleType property to determine the unit at which therecurring task repeats.TypeIntegerAccessRead/WriteExampleThis example schedules a new task to be run on a monthly basis usingordinal dates (the first Monday of every month) during the period fromMarch 15 to June 12, 1998.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs on the first " & _"Monday of every month".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up monthly execution, ordinal day.ScheduleType = 4'set up to run every month.RecurCyc = 1'set up to run on the first (OrdinalDay = 1)' Monday (RecurDayOfWk = Hex 2) of the month.RecurDayOfWk = &H02.OrdinalDay = 1'set up this task to only be considered for execution between' March 15, 1998 and June 12, 1998.EffectiveFrom = #3/15/1998#.UntilDate = #6/12/1998#.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 113

Chapter 6: PropertiesRecurDayOfWk PropertySyntaxSchedule.RecurDayOfWkApplies ToScheduleDescriptionSets or returns the day of the week or the month the recurring scheduledtask runs.DiscussionThe day of the week can be the day(s) in a weekly schedule type, or aday in a monthly ordinal day type. The values for this property are• Hex 01 = Sunday• Hex 02 = Monday• Hex 03 = Tuesday• Hex 04 = Wednesday• Hex 05 = Thursday• Hex 06 = Friday• Hex 07 = SaturdayWhen the ScheduleType property is set to Weekly, you can set a unionof the values to indicate one or more days in the week. To expresshexadecimal values, precede the value with "&H".TypeIntegerAccessRead/Write114 Automate Scheduler Using Macros

Chapter 6: PropertiesExample'This example schedules a new task which will run on a weekly basis,every other week, on Mondays.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs every other Monday".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up weeky execution.ScheduleType = 2'set up to run every other week.RecurCyc = 2'set up to run on Mondays.RecurDayOfWk = 2.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 115

Chapter 6: PropertiesRegisteredCompany PropertySyntaxApplication.RegisteredCompanyApplies ToApplicationDescriptionReturns the company name to which Scheduler is registered.DiscussionUse this property to determine the company name to which Schedulerwas registered.TypeStringAccessReadExampleThis example lists the names of all tasks in Scheduler and the companyname registered for this copy of the Scheduler executable.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.RegisteredCompanySet SchApp = NothingSet SchObj = NothingEnd Sub116 Automate Scheduler Using Macros

Chapter 6: PropertiesRegisteredUser PropertySyntaxApplication.RegisteredUserApplies ToApplicationDescriptionReturns the user to whom Scheduler is registered.DiscussionUse this property to determine the user to whom Scheduler wasregistered.TypeStringAccessReadExampleThis example lists the names of all tasks in Scheduler and the userregistered for this copy of the Scheduler executable.Dim SchApp as ObjectDim SchObj as ObjectSub Main()Set SchApp = CreateObject("CognosBatcher.Application")For i = 1 to SchApp.Schedules.CountSet SchObj = SchApp.Schedules.Item(i)MsgBox SchObj.ScheduleNameNext iMsgBox SchApp.RegisteredUserSet SchApp = NothingSet SchObj = NothingEnd SubAutomate Scheduler Using Macros 117

Chapter 6: PropertiesResultSet PropertySyntaxCompletedJob.ResultSetApplies ToCompletedJobDescriptionReturns whether the completed task was a remote task.DiscussionThe values of this property are• True - the completed job was a remote task• False - he completed job was a local taskTypeBooleanAccessReadExampleThis example counts the number of remote tasks that exist in theScheduler database, and displays this in a message box.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim intCounter As IntegerDim intRemoteTasks As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objCompletedTasks = objSchedApp.CompletedintRemoteTasks = 0For intCounter = 1 To objCompletedTasks.Count'check the ResultSet property to determine if the completed'task is a remote task.If objCompletedTasks.Item(intCounter).ResultSet ThenintRemoteTasks = intRemoteTasks + 1End IfNext intCounterMsgBox "There are " &Str(objCompletedTasks.Count - intRemoteTasks) & _" local completed tasks and " & Str(intRemoteTasks) & _" remote completed tasks."Set objCompletedTasks = NothingSet objSchedApp = NothingEnd Sub118 Automate Scheduler Using Macros

Chapter 6: PropertiesRunAtHour PropertySyntaxObject.RunAtHourApplies ToOptionsScheduleDescriptionSets or returns• the default hour at which all new tasks run in a 24-hour format, forthe Options object.• the hour at which the task runs, for a Schedule object.DiscussionUse this property in conjunction with RunAtMin property. This propertyuses the military time format. The hours are 0-23 (military format). Forthe Options object, use this property when the ExecuteAt property is setto a specified time.TypeIntegerAccessRead/WriteAutomate Scheduler Using Macros 119

Chapter 6: PropertiesExample 1This first example demonstrates the ExecuteAt, RunAtHour andRunAtMin properties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerDim strQualifier As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptionsIf .ExecuteAt=2 Then'Scheduler is set to use immediate execution as the'default for new tasksintResponse = msgbox("Scheduler is currently configured "&_" to default new tasks to immediate execution. Do you "&_" wish to change this?" ,259,"Immediate Execution")If intResponse = 6 Then.ExecuteAt = 7'switch to using the specified time in RunAtHour'and RunAtMin properties of the Options object.RunAtHour = val(inputbox("Type in a new default " & _"execution hour (24 hour clock) for new tasks or " & _"press ENTER to accept the current setting. ", _"Default Execution Hour",.RunAtHour)).RunAtMin = val(inputbox("Type in a new default" &_"execution minute for new tasks or press ENTER " & _"to accept the current setting. ", _"Default Execution Minute",.RunAtMin)).SaveEnd IfElseIf .ExecuteAt = 7 Then'Scheduler is set to use specified time execution'as the default for new tasksintResponse = msgbox("Scheduler is currently configured " & _"to default new tasks to execution at a specified time. " & _"Do you wish to change this?",259,"Delayed Execution")If intResponse = 6 Then.ExecuteAt = 2'switch to immediate execution as the default'for new tasksEnd IfEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub120 Automate Scheduler Using Macros

Chapter 6: PropertiesExample 2This second example returns a scheduled task and enables the user tochange the execution time to midnight.Sub Main()Dim objSchedApp As ObjectDim objSchedulerTasks As ObjectDim objSpecificTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objSchedulerTasks = objSchedApp.SchedulesSet objSpecificTask = objSchedulerTasks.Item(1)'the Edit method allows modification of this taskobjSpecificTask.Edit'RunAtHour and RunAtMin hold integers representing the hour'(in 24 hour format) and minute of scheduled execution.objSpecificTask.RunAtHour = 3objSpecificTask.RunAtMin = 33'the Save method will apply any modifications made to the'task since the invocation of the Edit methodobjSpecificTask.SaveSet objSpecificTask = NothingSet objSchedulerTasks = NothingSet objSchedApp = NothingEnd SubRunAtMin PropertySyntaxObject.RunAtMinApplies ToOptionsScheduleDescriptionSets or returns• the default minute at which all new tasks run, for the Options object.• the minute at which the task runs, for a Schedule object.DiscussionUse this property in conjunction with RunAtHour property. The minutesare 0-59. For the Options object, use this property when the ExecuteAtproperty is set to specified time.TypeIntegerAccessRead/WriteAutomate Scheduler Using Macros 121

Chapter 6: PropertiesExampleThis first example demonstrates the ExecuteAt, RunAtHour andRunAtMin properties of the Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intResponse As IntegerDim strQualifier As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptionsIf .ExecuteAt=2 Then'Scheduler is set to use immediate execution as the'default for new tasksintResponse = msgbox("Scheduler is currently configured "&_"to default new tasks to immediate execution. Do you wish "&_"to change this?",259,"Immediate Execution")If intResponse = 6 Then.ExecuteAt = 7'switch to using the specified time in RunAtHour'and RunAtMin properties of the Options object.RunAtHour = val(inputbox("Type in a new default " & _"execution hour" (24 hour clock) for new tasks or " & _"press ENTER to accept the current setting. ", _"Default Execution Hour",.RunAtHour)).RunAtMin = val(inputbox("Type in a new default " & _"execution minute for new tasks or press ENTER to " & _"accept the current setting.", _"Default Execution Minute",.RunAtMin)).SaveEnd IfElseIf .ExecuteAt = 7 Then'Scheduler is set to use specified time execution'as the default for new tasksintResponse = msgbox("Scheduler is currently configured" & _"to default new tasks to execution at a specified time." & _"Do you wish to change this?",259,"Delayed Execution")If intResponse = 6 Then.ExecuteAt = 2'switch to immediate execution as the default'for new tasksEnd IfEnd IfEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub122 Automate Scheduler Using Macros

Chapter 6: PropertiesThis second example returns a scheduled task and enables the user tochange the execution time to midnight.Sub Main()Dim objSchedApp As ObjectDim objSchedulerTasks As ObjectDim objSpecificTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objSchedulerTasks = objSchedApp.SchedulesSet objSpecificTask = objSchedulerTasks.Item(1)'the Edit method allows modification of this taskobjSpecificTask.Edit'RunAtHour and RunAtMin hold integers representing the hour'(in 24 hour format) and minute of scheduled execution.objSpecificTask.RunAtHour = 3objSpecificTask.RunAtMin = 33'the Save method will apply any modifications made to the'task since the invocation of the Edit methodobjSpecificTask.SaveSet objSpecificTask = NothingSet objSchedulerTasks = NothingSet objSchedApp = NothingEnd SubSchedule PropertySyntaxCompletedJob.ScheduleApplies ToCompletedJobDescriptionReturns a reference to the parent Schedule object.DiscussionUse this property to access the parent Schedule object through theCompletedJob object.TypeObjectAccessReadAutomate Scheduler Using Macros 123

Chapter 6: PropertiesExampleThis example returns the first completed task, including any errors anddisplays it in a message box.Sub Main()Dim objSchedApp As ObjectDim objScheduleTask As ObjectDim objCompletedTask As ObjectDim strDescription As StringDim strErrorMessage As StringDim strErrors As StringSet objSchedApp = CreateObject("Cognosbatcher.Application")'get a reference to the first completed task.Set objCompletedTask = objSchedApp.Completed.Item(1)Set objScheduleTask = objCompletedTask.SchedulestrDescription = objScheduleTask.ScheduleDescriptionIf objCompletedTask.HasErrors ThenstrErrorMessage = objScheduleTask.ErrorMessageMsgBox strDescription & " had the following error: " & _strErrorMessageElseMsgBox strDescription & " had no errors."End IfSet objScheduleTask = NothingSet objCompletedTask = NothingSet objSchedApp = NothingEnd Sub124 Automate Scheduler Using Macros

Chapter 6: PropertiesScheduleDescription PropertySyntaxSchedule.ScheduleDescriptionApplies ToScheduleDescriptionSets or returns the description of the Schedule object.DiscussionUse this property to set or determine the description of the Scheduleobject. The maximum length of this property is 64 characters.TypeStringAccessRead/WriteExampleThis example schedules a new task to run every third day.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, every third day".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up daily execution.ScheduleType = 1'set up to run every third day.RecurCyc = 3.RunAtHour = 11.RunAtMin = 45.EffectiveFrom = Date.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 125

Chapter 6: PropertiesScheduleId PropertySyntaxSchedule.ScheduleIdApplies ToScheduleDescriptionReturns the ID of the Schedule object.DiscussionUse this property to determine the ID associated with each Scheduleobject.TypeStringAccessRead126 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example displays all scheduled tasks and enables the user to createnew copies of them.Sub Main()Dim objSchedApp As ObjectDim objScheduledTasks As ObjectDim objNewTask As ObjectDim intCounter As IntegerDim intResponse As IntegerDim strTaskDescription As StringDim strTaskID as StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objScheduledTasks = objSchedApp.SchedulesFor intCounter = 1 to objScheduledTasks.CountstrTaskID = objScheduledTasks.Item(intCounter).ScheduleIDintResponse = MsgBox("Do you wish to create a new task " & _"based on thisone?" & _Chr(13) & "Task ID: " & strTaskID & _Chr(13) "Description: " & _objScheduledTasks.Item(intCounter).ScheduleDescription, _292, "Replicate this task?")If intResponse = 6 ThenSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.CreateUsing (intCounter).RunAtHour = Val(InputBox("Enter the execution hour in "&_"24 hour format","Execution Time")).RunAtMin = Val(InputBox("Enter the execution minute "&_"format", "Execution Time")).EffectiveFrom = Date.SaveEnd WithSet objNewTask = NothingEnd IfNext intCounterSet objNewTask = NothingSet objScheduledTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 127

Chapter 6: PropertiesScheduleName PropertySyntaxSchedule.ScheduleNameApplies ToScheduleDescriptionSets or returns the path and file name of the report or other task to runfor a Schedule object.DiscussionUse this property to set or determine the path and name of the file runby a Schedule object. This property must be of non-zero length andmust specify a file known to the Windows file system. This propertycannot be changed once a schedule is saved. The maximum length ofthis property is 255 characters.TypeStringAccessRead/WriteExampleThis example schedules a new task to run every third day.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, every third day".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up daily execution.ScheduleType = 1'set up to run every third day.RecurCyc = 3.RunAtHour = 11.RunAtMin = 45.EffectiveFrom = Date.CatLogUsrCls = "Creator".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd Sub128 Automate Scheduler Using Macros

Chapter 6: PropertiesSchedules PropertySyntaxApplication.SchedulesApplies ToApplicationDescriptionReturns the collection of Schedule objects.DiscussionUse this property to access the Schedules collection.TypeStringAccessReadExampleThis example returns a scheduled task and enables the user to changethe execution time to midnight.Sub Main()Dim objSchedApp As ObjectDim objSchedulerTasks As ObjectDim objSpecificTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objSchedulerTasks = objSchedApp.SchedulesSet objSpecificTask = objSchedulerTasks.Item(1)'the Edit method allows modification of this taskobjSpecificTask.Edit'RunAtHour and RunAtMin hold integers representing the hour'(in 24 hour format) and minute of scheduled execution.objSpecificTask.RunAtHour = 3objSpecificTask.RunAtMin = 33'the Save method will apply any modifications made to the'task since the invocation of the Edit methodobjSpecificTask.SaveSet objSpecificTask = NothingSet objSchedulerTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 129

Chapter 6: PropertiesScheduleType PropertySyntaxSchedule.ScheduleTypeApplies ToScheduleDescriptionSets or returns whether the scheduled task is a recurring task and if so,the unit at which it repeats.DiscussionUse the RecurCyc property to determine the frequency number for arecurring task. The values for this property are• 0 - single execution• 1 - daily task• 2 - weekly task• 3 - monthly cardinal day (day in the month) task• 4 - monthly ordinal day (first, second, third, fourth or last day of themonth) task• 5 - hourly taskNote: You cannot change this property once the Schedule object issaved.TypeIntegerAccessRead/Write130 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task to be run on a monthly basis usingordinal dates (the first Monday of every month) during the period fromMarch 15 to June 12, 1998.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs on the first " & _"Monday of every month".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up monthly execution, ordinal day.ScheduleType = 4'set up to run every month.RecurCyc = 1'set up to run on the first (OrdinalDay = 1)' Monday (RecurDayOfWk = Hex 2) of the month.RecurDayOfWk = &H02.OrdinalDay = 1'set up this task to only be considered for execution between' March 15, 1998 and June 12, 1998.EffectiveFrom = #3/15/1998#.UntilDate = #6/12/1998#.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 131

Chapter 6: PropertiesSharedAs PropertySyntaxCompletedJob.SharedAsApplies ToCompletedJobDescriptionReturns the last exported file name and location of the result set, if any.DiscussionUse this property to determine the last shared name of the result set.TypeStringAccessReadExampleThis example loops through all completed tasks and displays those thatcontain the shared file name and location in a message box.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedSchedule As ObjectDim intCounter As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objCompletedTasks = objSchedApp.CompletedFor intCounter = 1 To objCompletedTasks.CountSet objCompletedSchedule = objCompletedTasks.Item(intCounter)'check the SharedAs propertyIf len(trim(objComletedSchedule.ShareAs))> 0 ThenMsgBox "Task: " & _objCompletedSchedule.Schedule.ScheduleDescription & _chr(13) "Share Name: " & _objCompletedTasks.Item(intCounter).SharedAsEnd IfNext intCounterSet objCompletedSchedule = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd Sub132 Automate Scheduler Using Macros

Chapter 6: PropertiesSnapshotFileName PropertySyntaxSchedule.SnapshotFileNameApplies ToScheduleDescriptionSets or returns the path and file name of the snapshot associated withthe Schedule object.DiscussionUse this property to determine the path and file name of the snapshot tosave with the results of the Impromptu report run by the Scheduleobject. The maximum length of this property is 255 characters.Note: If this property returns Null, this does not mean that a snapshot isnot created. When this property is empty, the report name is used tocreate the snapshot with an .ims extension. Use the CreateSnapshotproperty to determine whether to create the snapshot.TypeStringAccessRead/WriteAutomate Scheduler Using Macros 133

Chapter 6: PropertiesExampleThis example creates a new task which saves the scheduled report into asnapshot.Sub Main()Dim objSchedApp As ObjectDim objScheduledTasks As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")'ensure that Scheduler has access to Impromtpu automationobjSchedApp.MutuallyExclusive FalseSet objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My snapshot task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'save the report as a snapshot.CreateSnapshot = True'must be a valid path and unique filename.SnapshotFileName = "C:\MyResults\MySnapshot.imr".SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubStartTime PropertySyntaxCompletedJob.StartTimeApplies ToCompletedJobDescriptionReturns the date and time the scheduled task was started.DiscussionUse this property to obtain the date and time the task started. If thecompleted task was remote, it is the time the task started on the client,which is then localized to the time on the server using Universal TimeCoordinates (UTC).Use the EndTime property to obtain the date and time the taskcompleted. The difference between the StartTime and EndTimeproperties gives you the duration of the task.For more information on UTC, see the Request Server Guide.134 Automate Scheduler Using Macros

Chapter 6: PropertiesTypeDateAccessReadExampleThis example displays all completed tasks and their related details.Sub Main()Dim objSchedApp As ObjectDim objCompletedTasks As ObjectDim objCompletedTask As ObjectDim intCounter As IntegerDim strErrors As StringDim strStartedAt As StringDim strEndedAt As StringDim strLastSeen As StringDim strTaskDescription As StringSet objSchedApp = CreateObject("CognosBatcher.Application")Set objCompletedTasks = objSchedApp.CompletedFor intCounter = 1 To objCompletedTasks.CountWith objCompletedTasks.Item(intCounter)If .HasErrors ThenstrErrors = "Error: " & .ErrorMessageElsestrErrors = "No Errors"End IfstrStartedAt = .StartTimestrEndedAt = .EndTimeIf Not(.LastViewed=&H0) ThenstrLastSeen = "Last Viewed: " & str(.LastViewed)ElsestrLastSeen = "Results not yet viewed."End IfSet objCompletedTask = _objCompletedTasks.Item(intCounter).SchedulestrTaskDescription = objCompletedTask.ScheduleDescriptionMsgBox strTaskDescription & Chr(13) & "Start Time: " & _strStartedAt & Chr(13) & "End Time: " & _strEndedAt & chr(13) strLastSeen & chr(13) & _strErrors, 64, "Completed Task " & Str(intCounter)End WithNext intCounterSet objCompletedTask = NothingSet objCompletedTasks = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 135

Chapter 6: PropertiesStartWithin PropertySyntaxOptions.StartWithinApplies ToOptionsDescriptionSets or returns the number of hours that can lapse before a late startingjob does not run.DiscussionThe hours for this property are 1-12.TypeIntegerAccessRead/WriteExampleThis example demonstrates the use of the StartWithin property for theOptions object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim intCurrentStartWithin As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'StartWithin holds an integer valueintCurrentStartWithin = .StartWithin.StartWithin = Val(InputBox("Scheduler is currently " & _"configured so that " & str(intCurrentStartWithin) & _"hours may elapse before a late job will not be " & _"considered for execution. Type in a new value or press "&_"ENTER to accept the current one.", _"Start Within Hours",intCurrentStartWithin)).SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub136 Automate Scheduler Using Macros

SuppressMultipleResultSets PropertySyntaxSchedule.SuppressMultipleResultSetsApplies ToScheduleDescriptionChapter 6: PropertiesSets or returns whether to overwrite the previous result set in a recurringremote task.DiscussionThis property is available only to remote result set requests. The valuesfor this property are• True - the previous result set, if it exists, is overwritten each time arecurring remote task runs (default).• False - a new result set is created each time a recurring remote taskruns.TypeBooleanAccessRead/WriteAutomate Scheduler Using Macros 137

Chapter 6: PropertiesExampleThis example schedules a server task that runs every day at 6:45pmoverwriting the previous result set.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleType = 1.ScheduleDescription = "My new server task".ScheduleName = "c:\MyReports\MyServerReport.imr"'an ExecuteOn value of 1 indicates execution is to take place'on a server; a value of 0 indicates execution'on the local machine.ExecuteOn = 1.RecurCyc = 1.EffectiveFrom = Date.RunAtHour = 18.RunAtMin = 45'since this is a recurring task, overwrite the previous result'set every time the task is run.SuppressMultipleResultSets = True.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubTOCoptions PropertySyntaxSchedule.TOCoptionsApplies ToScheduleDescriptionSets or returns the specified table of contents options to apply to ascheduled Impromptu report.DiscussionThe values for this property are• Hex 01 = separate pages• Hex 02 = include page numbersTo express hexadecimal values, precede the value with "&H".TypeInteger138 Automate Scheduler Using Macros

Chapter 6: PropertiesAccessRead/WriteExampleThis example schedules a new task, and sets it to publish the results toHTML documents, including a table of contents with page numbers.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My HTML task".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr".ScheduleType = 0.RunAtHour = 18.RunAtMin = 45.EffectiveFrom = Date'set up the task to publish its results to files in HTML format.PublishHTML = True'HTML Directory must be a valid path.HTMLDirectory = "C:\HTML_Documents"'HTMLPrefix will be placed in the file name for each'of the HTML files produced.HTMLPrefix = "IH_"'include a table of contents.IncludeTOC = True'include page numbers (Hex 02).TOCOptions = &H02.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 139

Chapter 6: PropertiesUntilDate PropertySyntaxSchedule.UntilDateApplies ToScheduleDescriptionSets or returns the date after which a recurring task no longer runs.DiscussionThis property must be greater than the EffectiveFrom Property and isapplicable only if the ScheduleType property denotes a recurring task.Null clears the date.TypeVariantAccessRead/Write140 Automate Scheduler Using Macros

Chapter 6: PropertiesExampleThis example schedules a new task to be run on a monthly basis usingordinal dates (the first Monday of every month) during the period fromMarch 15 to June 12, 1998.Sub Main()Dim objSchedApp As ObjectDim objNewTask As ObjectSet objSchedApp = CreateObject("CognosBatcher.Application")Set objNewTask = CreateObject("CognosBatcher.Schedule")With objNewTask.ScheduleDescription = "My new task, runs on the first " & _"Monday of every month".ScheduleName = "C:\Program Files\Cognos\Impromptu 5.0\" & _"Imp.5.0 Samples\Reports\Annual Product Sales.imr"'set up monthly execution, ordinal day.ScheduleType = 4'set up to run every month.RecurCyc = 1'set up to run on the first (OrdinalDay = 1)' Monday (RecurDayOfWk = Hex 2) of the month.RecurDayOfWk = &H02.OrdinalDay = 1'set up this task to only be considered for execution between' March 15, 1998 and June 12, 1998.EffectiveFrom = #3/15/1998#.UntilDate = #6/12/1998#.RunAtHour = 18.RunAtMin = 45.SaveEnd WithSet objNewTask = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 141

Chapter 6: PropertiesUserDescription PropertySyntaxOptions.UserDescriptionApplies ToOptionsDescriptionSets or returns the description of the user.DiscussionUse this property to identify the user of this installation of Scheduler.The user description is sent with remote server requests. The maximumlength of this property is 75 characters.TypeStringAccessRead/WriteExampleThis example demonstrates the use of the UserDescription property ofthe Options object.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'UserDescription provides Read & Write accessMsgBox "Scheduler User Description: " & .UserDescription.UserDescription = "John Doe - Senior Vice President".SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub142 Automate Scheduler Using Macros

Chapter 6: PropertiesUserEmail PropertySyntaxOptions.UserEmailApplies ToOptionsDescriptionSets or returns the email address of the user.DiscussionBecause this property is a string, you must enter the exact email addressfor any messaging to work properly. This email address is sent withremote server requests. The maximum length of this property is 75characters.TypeStringAccessRead/WriteExampleThis example demonstrates the use of the Options object, and itsUserEmail property.Sub Main()Dim objSchedApp As ObjectDim objOptions As ObjectSet objSchedApp = CreateObject("Cognosbatcher.Application")'set up a reference to the Options objectSet objOptions = objSchedApp.OptionsWith objOptions'UserEmail is a property of the Options objectMsgBox "Scheduler User E-Mail:" & .UserEmail'UserEmail provides read & write access.UserEmail = "jdoe@somewhere.com"'the Save method commits any alterations made to the Options'properties; if Save is not used, the changes will be lost'when the reference to the Scheduler Application object is'destroyed, or when Scheduler is closed.SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd SubAutomate Scheduler Using Macros 143

Chapter 6: PropertiesWarnPriorToDelete PropertySyntaxOptions.WarnPriorToDeleteApplies ToOptionsDescriptionSets or returns whether Scheduler prompts the user before deleting atask.DiscussionUse this property to warn the user that a task is about to be deleted andenable the user to cancel the action. If this property is set to True, awarning appears. If this property is set to False, no warning appears.TypeBooleanAccessRead/WriteExampleThis example demonstrates the use of the WarnPriorToDelete propertyof the Options object.Sub main()Dim objSchedApp As ObjectDim objOptions As ObjectDim strQualifier As StringDim intResponse As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'WarnPriorToDelete is a Boolean propertyIf .WarnPriorToDelete ThenstrQualifier = ""ElsestrQualifier = " not"End IfintResponse = MsgBox("Scheduler is currently configured" & _" so that it will" & strQualifier & _" warn the user prior to deleting a row. Do you wish to " & _" toggle this setting?", 259, "Toggle Delete Warning")If intResponse = 6 Then.WarnPriorToDelete = Not(.WarnPriorToDelete)End If.SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub144 Automate Scheduler Using Macros

Chapter 6: PropertiesWarnPriorToExit PropertySyntaxOptions.WarnPriorToExitApplies ToOptionsDescriptionSets or returns whether Scheduler prompts the user before exiting whenthere are local tasks to run.DiscussionUse this property to remind the user that if Scheduler is closed, thepending local tasks will not run. If this property is set to True, a warningappears. If this property is set to False, no warning appearsTypeBooleanAccessRead/WriteAutomate Scheduler Using Macros 145

Chapter 6: PropertiesExampleThis example demonstrates the use of the WarnPriorToExit property ofthe Options objectSub Main()Dim objSchedApp As ObjectDim objOptions As ObjectDim strQualifier As StringDim intResponse As IntegerSet objSchedApp = CreateObject("Cognosbatcher.Application")Set objOptions = objSchedApp.OptionsWith objOptions'WarnPriorToExit is a Boolean propertyIf .WarnPriorToExit ThenstrQualifier = ""ElsestrQualifier = " not"End IfintResponse = MsgBox("Scheduler is currently configured so " & _"that it will" & strQualifier & _"warn the user prior to exit if there are tasks still to "&_"be executed. Do you wish to toggle this setting?", _259, "Toggle Exit Warning")If intResponse = 6 Then.WarnPriorToExit = Not(.WarnPriorToExit)End If.SaveEnd WithSet objOptions = NothingSet objSchedApp = NothingEnd Sub146 Automate Scheduler Using Macros

Index—A—accessing, 16collection of CompletedJob objects, 52Options object, 99Schedule object, 123Application.Comments, 50Application.CompanyName, 51Application.Completed, 52Application.EXEname, 70Application.LegalCopyright, 92Application.Major, 93Application.Minor, 94Application.MutuallyExclusive (Flag), 32Application.Options, 99Application.RegisteredCompany, 116Application.RegisteredUser, 117Application.Schedules, 129Application.Visible, 39ApplicationTray Property, 42—B—build numbers, 94getting, 93—C—CardinalDay, 43catalog user class name, 44CatLogUsrCls, 44CatLogUsrPw, 46collection, 53collections, 22, 23CompletedJobs, 22command script paths, 48CommandFileName, 48CommandScript, 49, 50CompanyName, 51Completed, 52completed server tasks, 95notifying, 97completed tasks, 27identifying remote tasks, 118purging, 109, 111CompletedJobsending results, 36viewing results, 38CompletedJob object, 12CompletedJob objectscounting, 53CompletedJob objects,objectsgroupingaccessing, 22CompletedJob.Delete, 27CompletedJob.EndTime, 62CompletedJob.ErrorMessage, 64CompletedJob.HasErrors, 74CompletedJob.LastViewed, 90CompletedJob.ResultSet, 118CompletedJob.Schedule, 123CompletedJob.SharedAs, 132CompletedJob.StartTime, 134CompletedJob.ViewResults, 38CompletedJobs Collection(Scheduler), 22connectingto Request Server, 102Schedule.Delete, 29Count, 53CreateSnapshot, 54—D—database, 56days of the week, 100DbUsrId, 56DbUsrPw, 58default hours, 119, 121Delete, 29Automate Scheduler Using Macros 147

IndexDelete Method, 27deleting taskswarn before, 144description of user, 142—E—Edit, 31, 32EffectiveFrom, 60email addresses, 143EndTime, 62ErrorMessage, 64errorstask, 74executable name, 70ExecuteAt, 66EXEname, 70exitingwarning, 145ExportAs, 71, 72exporting, 71, 72ExportType, 73—F—CompletedJob.SendResults, 36filenameresult sets,export location, 132—G—getting, 43build number, 94catalog user class name, 44collection of CompletedJob objects, 52command script, 49, 50command script filenames, 48company name, 51days of the week, 100directory of HTML files, 78executable name, 70export type, 73exporting report options, 71, 72hour tasks run, 119, 121items, 88legal copyright, 92major build number, 93name of the database user, 56names of schedule, 128Options object, 99prefix for HTML, 80, 82print copies, 103printer names, 106publishing HTML option, 107recurring task frequency, 112recurring tasks, 114, 130registered company name, 116, 117save as snapshot option, 54schedule descriptions, 125schedule identification, 126Schedule objects, 129Scheduler run modes, 84snapshot file name, 133start time lapse hours, 136TOC options, 86, 138user descriptions, 142—H—HasErrors, 74Hold, 76HTMLpublishing settings, 107HTMLdirectory, 78HTMLprefix, 80, 82—I—IgnoreServerTasks, 84IncludeTOC, 86incomplete tasks, 16Item, 88—L—LastViewed, 90late starting jobs, 136LegalCopyright, 92local mode, 84—M—macros, 5Major, 93Minor, 94—N—NotifyWithIcon, 95NotifyWithSound, 97—O—Object.RunAtHour, 119Object.RunAtMin, 121objectsgroupingaccessing, 23148 Automate Scheduler Using Macros

IndexOLE automation methods, 12, 14, 16Delete, 27, 29Edit, 31, 32SendResults, 36ViewResults, 38OLE automation PropertiesCompleted, 52OLE automation properties, 12, 14, 16, 73, 117CardinalDay, 43CatLogUsrCls, 44CatLogUsrPw, 46CommandFileName, 48CommandScript, 49, 50CompanyName, 51Count, 53CreateSnapshot, 54DbUsrId, 56DbUsrPw, 58EffectiveFrom, 60EndTime, 62ErrorMessage, 64ExecuteAt, 66ExecuteOn, 68EXEname, 70ExportAs, 71, 72HasErrors, 74Hold, 76HTMLdirectory, 78HTMLprefix, 80, 82IgnoreServerTasks, 84IncludeTOC, 86Item, 88LastViewed, 90LegalCopyright, 92Major, 93NotifyWithIcon, 95NotifyWithSound, 97Options, 99OrdinalDay, 100PollingFrequency, 102PrintCopies, 103PrinterName, 106PrintResults, 104PublishHTML, 107PurgeCompleted, 109PurgeCompletedAfter, 111RecurCyc, 112RecurDayofWk, 114RegisteredCompany, 116, 117ResultSet, 118RunAtHour, 119, 121Schedule, 123ScheduleDescription, 125ScheduleId, 126ScheduleName, 128Schedules, 129ScheduleType, 130SharedAs, 132SnapshotFileName, 133StartTime, 134StartWithin, 136SuppressMultipleResultSets, 137the CompletedJobs collection, 22the Schedules collection, 23TOCoptions, 138UntilDate, 140UserDescription, 142UserEmail, 143WarnPriorToDelete, 144WarnPriorToExit, 145OLE automation Properties,Minor, 94opened last, 90options, 14Options object, 14, 99Options.ApplicationTray, 42Options.ExecuteAt, 66Options.IgnoredSince, 82Options.IgnoreServerTasks, 84Options.NotifyWithIcon, 95Options.NotifyWithSound, 97Options.PollingFrequency, 102Options.PurgeCompleted, 109Options.PurgeCompletedAfter, 111Options.Save, 34Options.StartWithin, 136Options.UserDescription, 142Options.UserEmail, 143Options.WarnPriorToDelete, 144Options.WarnPriorToExit, 145OrdinalDay, 100overwriting result sets, 137—P—passwordscatalog user class, 46database users, 58PollingFrequency, 102prefix for HTML, 82PrintCopies, 103PrinterName, 106printingreports, 104PrintResults, 104PublishHTML, 107PurgeCompleted, 109PurgeCompletedAfter, 111Automate Scheduler Using Macros 149

Index—R—RecurCyc, 112RecurDayOfWk, 114recurring tasks, 130RegisteredCompany, 116, 117remote task, 118report printing, 104result sets, 90, 132overwritting, 137results, 36viewing, 38ResultSet, 118RunAtHour, 119, 121running new tasks, 68immediatelyat specified time, 66—S—save as snapshot option, 54saving, 34Schedule, 123Schedule object, 23, 123schedule object, 16Schedule objects, 88counting, 53Schedule.CardinalDay, 43Schedule.CatLogUsrCls, 44Schedule.CatLogUsrPw, 46Schedule.CommandFileName, 48Schedule.CommandScript, 49Schedule.CreateSnapshot, 54Schedule.DbUsrPw, 58Schedule.Edit, 31Schedule.EffectiveFrom, 60Schedule.ExportAs, 71Schedule.ExportFileName, 72Schedule.ExportType, 73Schedule.Hold, 76Schedule.HTMLdirectory, 78Schedule.HTMLprefix, 80Schedule.IncludeTOC, 86Schedule.OrdinalDay, 100Schedule.PrintCopies, 103Schedule.PrinterName, 106Schedule.PrintResults, 104Schedule.PublishHTML, 107Schedule.RecurCyc, 112Schedule.RecurDayOfWk, 114Schedule.Save (ImpApp), 35Schedule.ScheduleDescription, 125Schedule.ScheduleId, 126Schedule.ScheduleName, 128Schedule.ScheduleType, 130Schedule.SnapshotFileName, 133Schedule.SuppressMultipleResultSets, 137Schedule.TOCoptions, 138Schedule.UntilDate, 140scheduled, 60scheduled tasks, 16deleting, 29end time, 62start time, 134ScheduleDescription, 125ScheduleId, 126ScheduleName, 128Scheduler objects, 31, 32Scheduler optionsaccessing, 14Schedules, 129Schedules Collection (Scheduler), 23ScheduleType, 130scheduling, 114SendResults, 36server taskscompleted, 95settingcatalog user class name, 44catalog user class passwords, 46command script, 49, 50command script filenames, 48days of the week, 100export types, 73password of the database user, 58printer names, 106report options, 104the dates scheduled tasks start running, 60SharedAs, 132SnapshotFileName, 133sounds, 97starting late jobs, 136StartTime, 134StartWithin, 136SuppressMultipleResultSets, 137—T—task errors, 74tasks, 12place on holdtake off hold, 76recurring, 112, 114scheduled, 16, 123stopping recurring, 140time150 Automate Scheduler Using Macros

Indexending for a task, 62TOCoptions, 138—U—UntilDate, 140user names, 56UserDescription, 142UserEmail, 143—V—viewingCompletedJobs, 90ViewResults, 38visible method, 39—W—warningsbefore deleting tasks, 144before leaving Scheduler, 145WarnPriorToDelete, 144WarnPriorToExit, 145—X—xecuteOn, 68Automate Scheduler Using Macros 151