Job Interface

The Job object (IJob) is returned by the CreateJob function that is provided through the ComScript connection interface. Through this object, the functionality of the Job utility can be used in programs that are written in any COM supporting development environment.

The following functionality is provided:

Properties

Name	Type	Access	Description
AlternativeReportName	String	Read/Write	An alternative report name can be set to use for the Batch Controller. In this way the report used can be run more than once simultaneous even if this has been disabled in the Job Queue settings.
AppName	String	Read/Write	When set it defines the application to look for jobs in the functions AddJobRequest(<JobName>) and JobIdByJobName(<JobName>). This property may be set to a different application than used when connecting the ComScript Module to an application. Note: the <ComsScript Object>.AppName and the <Job Object>.AppName should be set to the same value in order to run the job of the correct application. Note: When set to a non existent application the write will fail, the value will be left unchanged and the properties ErrorCode and ErrorDescription will be set accordingly.
BatchId	Integer	Read/Write	When set to zero before and AddJobRequest() it will reflect the JobId as shown in the Job list of the Control Center after the call to AddJobRequest(). If set to a non zero value it will remain unchanged.
DeadlockPriority	Integer64	Read/Write	When two processes try to lock the same record, the process that comes second will fail with a deadlock error. When using an MSSQL Database server this property can be set to a value ranging from -10 to 10 (default 0). When the values set for both processes differ, the process with the lowest value will fail, even when it was the first to lock the record. Note: For MSSQL Server only.
Debug	Boolean	Read/Write	When set to True the report will start in debug mode. I.e. the report will wait after startup for the debugger to connect to it enabling debugging of the job. See the Start Debugging page on information on how to debug the job in the AMT Debugger.
ErrorCode	Integer	Readonly	Reads the error code of the Job Object. The code will be zero if there was no error. This code is only valid if the property Wait was set to 'TRUE'.
ErrorDescription	String	Readonly	Reads the error description of the Job Object. If there was no error 'OK' is returned. This description will only be valid if the property Wait was set to 'TRUE'.
FileName	String	Read/Write	Should be set to the executable (.exe or .wsf) version of the report to start by the call to AddJobRequest. The absolute path or UNC path to this executable should be used.
GlobalParameter	String	Read/Write	Can be used to pass global parameters to the report.
InitialResult	Integer	Read/Write	Initial value for the system variable SI-REPORTRESULT at start of the report.
JobId	Integer	Readonly	This property is set to the Id number or a job as shown in the Joblist in the Control Center after returning from the call to AddJobRequest().
JobName	String	Read/Write	When not set previously this property will be set to the name of the executed job after returning form the call to AddJobRequest(). Otherwise it will be left unchanged.
JobState	Integer	Readonly	If, before starting the report, the property Wait has been set to True, upon return this property will contain the exit state of the executed report. If Wait has been set to False the return state will be Undefined.
JobText	String	Read/Write	A free to choose text to use inside the script.
Language	String	Read/Write	The language to use if the report is Multilanguage. It will be copied to the system variable SI-LANGUAGE inside the report.
MaximumNumberOfRestarts	Integer	Read/Write	Gets or sets the maximum number of retries after a job crashes. The default number of restarts is 5.
ParentRequestId	Integer	Read/Write	The RequestId of the process that started the current job.
ProcessId	Integer	Readonly	The Windows ProcessId of the running job.
ProcessJobId	Integer	Readonly	Returns the Process job id.
ProcessOk	Boolean	Read/Write	If AddJobRequest was called with the Wait property set to TRUE, this property will be set to True if the called job exited with no error. If Wait was set to False the return value will always be False.
QueueName	String	Read/Write	In this property the name of the batch queue to place this job in can be set. When no queue is specified, the queue defined at the job will be used, as shown in the Available Jobs list of the Control Center. Will be set to the name of the queue used when the job is running.
RecoverCriticalReport	Boolean	Read/Write	Can be set to True to recover a crashed report that uses the SAVERECOVERY option.
ReportParameter	String	Read/Write	If inside the report a special report parameter is defined this property can be used to pass information to this parameter. The maximum size of this parameter is 1024 characters.
RequestId	Integer	Readonly	After return from the call to AddJobRequest this property is set to the id of the request used in the AMT-COBOL system.
RestartAt	String	Read/Write	Parameter that can be used to send information about a starting point to a script, this parameter can be set in the Control Center when starting a job of type script.
RunAs	String	Read/Write	The batch controller will retrieve the specified user from the LoginAccounts and use the specified credentials for the start of the job. The job will then run under those credentials. If the account is not found/disabled it will fail to start the report.
Running	Boolean	Readonly	Returns true when the current job is in the running state.
ScriptParameter	String	Read/Write	If the job to execute is a script, this property can be used to pass parameters to the script.
StartDate	String	Read/Write	The date to execute the job in the format CCYYMMDD.
StartedDateTime	String	Readonly	The date-time when the job was started by the batchcontroller in the format CCYYMMDDhhmmssnnn.
StartTime	String	Read/Write	The time to execute the job in the format hhmm. Please note that StartDate should also be set in order to start at that specific time.
Station	String	Read/Write	The name of the initiating station of the job to use in the logfiles.
TaskString	String	Readonly	An XML string used to pass the TaskValue and custom Task Values to and from a report or script.
TaskValue	String	Read/Write	A value that is passed to and from a report or script. Note: To return the TaskValue to the calling report or script the function SaveTaskValue() should be invoked in the called report or script after changing the value of TaskValue.
TraceFileMessages	String	Read/Write	The name of the trace file to write a copy of all messages (SME) to. When the file already exists the messages will be appended. When a relative file name is used the file will be created in the logfile folder of the AMT-COBOL environment. Note: The files are created and written directly by the report itself (i.e. not through the filecontroller). They will not be removed automatically by the batchcontroller.
User	String	Read/Write	Name of the user to use in the logging for this job.
UserGroup	String	Read/Write	Defines the user group name. This name has to be specified case sensitive, otherwise the report will not be shown in the Job Management tabsheet of LionScreens. The job will always be visible in the Job Management option of the Control Center.
Wait	Boolean	Read/Write	When set to True the function AddJobRequest will wait for the job to finish before returning to the script. If set to False, the job request will just be placed in batch queue and return to the script immediately. When setting Wait to True it is wise to also set WaitTimeout to detect hanging of the report. Default is True (wait for the job to finish).
WaitTimeout	Integer	Read/Write	When the Wait property has been set to True, this property can be used to create a timeout in case the execution time of the report is much longer than expected. In the properties ErrorCode and ErrorDescription is then visible that a timeout occurred.

Functions

Function Name	Return type	Parameters		Description
Function Name	Return type	Name	Type	Description
AddAcceptFile	Void	Name	String	Adds an acceptfile to use for request of the report.
AddBackupDir	Void	PrintId	String	Sets the backup directory for the printer settings of PrintId. When a backup directory is set the FormId setting will be overwritten.
		BackupDir	String

AddBannerIdFile	Void	PrintId	String	Adds a Banner file to the printer settings of PrintId. BannerFile should be given as absolute path/filename combination.
		BannerFile	String

AddDefaultBackupDir	Void	BackupDir	String	Sets the backup directory for the default print settings. The FormId setting will be overwritten.
AddDefaultBanner	Void	BannerFile	String	Adds a Banner file to the default printer settings. Should be given as an absolute path/filename combination.
AddDefaultFormId	Void	FormId	String	Adds a FormId to the default printer settings. When set the printfiles will be placed in a subdirectory named <FormId> within the prints directory. This setting will be overwritten when a Backup directory is set.
AddDefaultNumberOfCopies	Void	NumberOfCopies	Integer	Adds the number of copies to print to the default printer settings.
AddDefaultPrinter	Void	Printer	String	Adds a printer to the default printer settings.
AddDefaultPrintFileName	Void	PrintFile	String	Adds the print filename to the default printer settings.
AddDefaultPrintSetting	Void	PrintFile	String	This function sets default print settings for the default printer with PrintId PROUT. These settings will be used as defaults when a Print object is created. Some can be overwritten inside the Print object.
		Printer	String
		DontPrint	Boolean
		NumberOfCopies	Integer
		PrintBanner	Boolean
		NoDateSubdirectory	Boolean

AddExtractFile	Void	FileId	String	Sets the initial filename of the extract file to use for the given FileId. This will be overruled when using 'namefile'. The file created will be kept after execution of the report started by the job object.
		Filename	String

AddExtractRetainFile	Void	FileId	String	Sets the initial filename of the extract file to use for the given FileId. This will be overruled when using 'namefile'. When RetainFile is set to True the file created will be kept after execution of the report started by the job object, otherwise it will be deleted automatically.
		Filename	String
		RetainFile	Boolean
AddFormId	Void	PrintId	String	Adds a FormId to the printer settings of PrintId. When set the printfiles will be placed in a subdirectory named <FormId> within the print directory. This setting is overwritten when a Backup directory is set.
		FormId	String

AddJobRequest	Integer	JobName	String	Adds a job request for the job given in JobName. Upon success the RequestId is returned otherwise -1. The job in JobName has to be a job in the application set in the AppName property of the Job Class. JobType describes the type of job (1 for Script, 2 Batch, 3 Report, 4 Executable, 5 Amt COBOL program). The optional ProcessJobId parameter can be used to recover a specific job entry. Note: When type is 4 (external windows executable), information can be passed to the executable using the windows environment variables and the exit code of the executable can be retrieved through the custom task value system.
		JobType	Integer
		[ProcessJobId]	Integer
AddJobRequestById	Integer	JobId	Integer	Adds a job request for the job given in JobId. Upon success the RequestId is returned otherwise -1. JobId is the Id of the Job as given in the available job list in the Control Center. The Job Id can be retrieved in the script with the function JobIdByJobName().
AddNumberOfCopies	Void	PrintId	String	Sets the number of copies to print in the printer settings of PrintId
		NumberOfCopies	Integer

AddPrinter	Void	PrintId	String	Adds a printer to the printer settings of PrintId.
		Printer	String

AddPrintFileName	Void	PrintId	String	Sets the print filename for the printer settings of PrintId.
		PrintFilename	String

AddPrintSetting	Void	PrintId	String	Sets all the printer settings for the given PrintId.
		PrintFile	String
		Printer	String
		DoNotPrint	Boolean
		NumberOfCopies	Integer
		PrintBanner	Boolean
		NoDateSubdirectory	Boolean
ChangeCobolPrintfile	Void	Source	String	For OS2200, changes the name of an existing printfile if it has been freed from the system.
		Destination	String

ChangePrintFileName	Void	Source	String	Changes the name of an existing print file in the system database. Only the filename in the system database gets changed, not the actual file. Can be used when a filename gets changed by another process and the name in the system database should match the new name. Both Source and Destination are represented in full path\filename but are not case sensitive.
		Destination	String

ClearBatchFiles	Void	---		Clears all the entries in the system tables for this run of this job.
ClearPrintFileNames	Void	---		Clears the current list of print filenames in the print settings
ClearPrintSettings	Void	---		Clears all the printer settings set locally inside the Job object.
ClearTaskValues	Void	---		Clears all the Task values set for this job.
GetAppendToPrintFile	Boolean	PrintId	String	Returns the current value of the AppendToPrintFile setting of the provided PrintId.
GetBackupDir	String	PrintId	String	Returns the backup directory set for the specified PrintId
GetBannerIdFile	String	PrintId	String	Returns the banner file set for the specified PrintId
GetDefaultAppendToPrintFile	Boolean	---		Returns the default value for the AppendToPrintFile setting
GetDefaultBackupDir	String	---		Returns the default backup directory set for this job
GetDefaultBanner	String	---		Returns the default banner file set for this job
GetDefaultDontPrint	Boolean	---		Returns the value set for the don't print option for this job
GetDefaultFormId	String	---		Returns the default FormId set for this job
GetDefaultNoDateSubdirectory	Boolean	---		Returns the value set for the no date subdirectory option for this job
GetDefaultNumberOfCopies	Integer	---		Returns the number of copies to print set for this job
GetDefaultPrintBanner	Boolean	---		Returns the value set for the print banner option for this job
GetDefaultPrinter	String	---		Returns the printer set to use for this job
GetDefaultPrintFilename	String	---		Returns the print filename set to use for this job
GetDefaultPrintHookParameters	String	---		Returns the default print hook parameters for the whole job
GetDontPrint	Boolean	PrintId	String	Returns the value set for the don't print option of the specified PrintId
GetExtractFileName	String	FileId	String	Returns the extract filename set for the specified FileId
GetFormId	String	PrintId	String	Returns the Form Id set for the specified Print Id
GetMessageObjectsByBatchId	List of Message Objects	BatchId	Integer	Returns a list of Amt Message objects for the job(s) specified in BatchId. In the objects both the messages and the message types are available.
GetMessagesByBatchId	String	BatchId	Integer	Returns the messages for the job(s) specified in BatchId.
GetMessagesByRequestId	String	RequestId	Integer	Returns the messages for the job specified in RequestId.
GetNoDateSubdirectory	Boolean	PrintId	String	Returns the value set for the no date subdirectory of the specified PrintId
GetNumberOfCopies	Integer	PrintId	String	Returns the number of copies to print set for the specified PrintId
GetPrintBanner	Boolean	PrintId	String	Returns the value set for the print banner option of the specified PrintId
GetPrinter	String	PrintId	String	Returns the printer set for the specified PrintId
GetPrintFilename	String	PrintId	String	Returns the print filename set for the specified PrintId
GetPrintHookParameters	String	PrintId	String	Returns the print hook parameters for the specified PrintId
GetTVCustom	String	Key	String	Returns the value of the Custom Task value with the give key.
GetTVSwitch	String	Sw	String	Returns the state of the given switch, True or False.
Initialize	Void	---		Initializes the existing Job object, can be used to reset the object in order to allow a new job to be executed.
Kill	Integer	---		Kills the current running job, whatever the state of that job is. Returned is the RequestId of the kill action. If the 'User' property has been filled in, that value will be used in the Control Center to show who killed the job.
RemovePrintFileName	Void	PrintFilename	String	Remove the entry with the given filename from the system tables.
RunAmtProgram	Integer	JobName	String	Run an AMT COBOL program inside the script without the batchcontroller
SaveTaskValue	Void	---		Saves the altered TaskValue and Custom Task Values to the system database in order to pass these values back to the calling report or script.
SendInput	Boolean	InputValue	String	Sends a message to a job that is waiting for an input request. Returns true if succeeded.
SendInterrupt	Boolean	Value	Integer	Sends an interrupt request to a job. An interrupt value must be entered as value. In a Report this value will be available in the system variable SI-REPORTRESULT. Returns true if succeeded.
SetAppendToPrintFile	Void	PrintId	String	When AppendToPrintFile is set to True a print to an existing printfile will append to that file of the provided PrintId. When set to False the printfile will get overwritten.
		AppendToPrintFile	Boolean

SetDefaultAppendToPrintFile	Void	AppendToPrintFile	Boolean	When DefaultAppendToPrintFile is set to True a print to an existing printfile will append to that file for the whole job. When set to False the printfile will get overwritten.
SetDefaultDontPrint	Void	DoNotPrint	Boolean	Sets the DontPrint switch in the printer settings for the default printer. When set to True the printfile will not be printed, but just created as printfile.
SetDefaultNoDateSubDirectory	Void	NoDate	Boolean	Sets the NoDateSubDir switch in the printer settings for the default printer. When set to True no dated subdirectory will be created inside the prints directory, the FormId directory or the Backup directory.
SetDefaultPrintBanner	Void	PrintBanner	Boolean	Sets the PrintBanner switch in the printer settings for the default printer. When set to True the default banner or the banner file set will be printed.
SetDefaultPrintHookParameter	Void	Parameters	String	Sets the print hook parameters for the whole job, these parameters can then be passed to the Print File Hook.
SetDontPrint	Void	PrintId	String	Sets the DontPrint switch in the printer settings of PrintId. When set to True the printfile will not be printed, but just created as printfile.
		DoNotPrint	Boolean

SetNoDateSubdirectory	Void	PrintId	String	Sets the NoDataSubdirectory switch in the printer settings of PrintId. When set to True no dated subdirectory will be created inside the prints directory, the FormId directory or the Backup directory.
		NoDate	Boolean

SetPrintBanner	Void	PrintId	String	Sets the PrintBanner switch in the printer settings of PrintId. When set to true the default banner or the banner file set will be printed.
		Banner	Boolean

SetPrintHookParameters	Void	PrintId	String	Sets the print hook parameters for the provided PrintId, these parameters can then be passed to the Print File Hook.
		Parameters	String

SetTVCustom	Void	Key	String	Sets the Task value for the given Key for the use inside the report.
		Value	String

SetTVSwitch	Void	Sw	String	Sets the Task value Switch to either True or False. The value of the switch can be used and changed inside the report.
		OnOff	Boolean

Stop	Integer	---		Stops the execution of the current job in a nicely fashion. I.e. it waits until a Commit() is executed inside the report before stopping the report. The returned value is the RequestId of the Stop action.
WakeUp	Integer	---		Sends a Wakeup signal to the current sleeping job. The returned value is the RequestId of the WakeUp action.
WakeUpParameter	Integer	Parameter	Strings	Sends a Wakeup signal to the current sleeping job and passes the Parameter to that job. The returned value is the RequestID of the Wakeup action.

Example

PowerShell

#See ComScript Connection Interface
...

$ComScr.Connect()

#Create an object of the Job Interface to be able to run jobs of the application.

$Job = $ComScr.CreateJob()

#Start the report COMSCRIPTTEST.

$Job.User = "rsteffens"

$Job.UserGroup = "Users"

$Job.JobName = "COMSCRIPTTEST"

$Job.ReportParameter = "Eddy"

[void]$Job.AddJobRequest("COMSCRIPTTEST", 3)

#Check if an error occurred and log if so.

if ($Job.ErrorCode -ne 0) {

[void]$Msg.AddMsgInformation("ErrorCode is: $($Job.ErrorCode)")

[void]$Msg.AddMsgInformation("ErrorDescription is: $($Job.ErrorDescription)")

} else {

[void]$Msg.AddMsgInformation("Report succeeded.")

}

# Finally release the variables and clean up the session.
$ComScr.Dispose()