Timer Services Interface › $TICALL FUNC=ADD

$TICALL FUNC=ADD

Adds a timer definition.

&CONTROL SHRVARS
-EXEC $TICALL FUNC=ADD
            [ CLASS=classname ]
            [ SUBCLASS=subclassname ]
              NAME=name
            [ SDATE=startdate ]
            [ EDATE=enddate ]
            [ STIME=starttime ]
            [ ETIME=endtime ]
              FREQ={ nnnn | HH.MM.SS }
            [ FTYPE={ MONTHS | DAYS | TIME } ]
            [ LIMIT={ nnnn | 1 } ]
            [ DAYLIST=(MON,TUE,…..) ]
            [ CATCHUP={ YES | NO } ]
            [ DELEXP={ YES | NO } ]
            [ STATUS={ ACTIVE | INACTIVE } ]
            [ SAVE={ YES | NO } ]
            [ ROUTE={ * | userid | MON | LOG | SYS } ]
            [ KEEP={ MON | LOG | SYS } ]
              COMMAND=command 
            [ DESC=description ]

Adds a new timer definition. If a same named definition already exists, then this call will fail.

Operands:

FUNC=ADD

Adds a timer definition.

CLASS=classname

Specifies a class name, maximum 8 characters. Timer definitions are categorized by class, subclass and a name. The name is mandatory but the class and subclass names are optional.

SUBCLASS=subclassname

Specifies a sub-class name, maximum 8 characters.

NAME=name

Specifies a name for this definition, maximum 12 characters. This is a required operand.

SDATE=startdate

Specifies the start date for this timer. Specify as a DATE8 format (YYYYMMDD). The default is the current system date.

EDATE=enddate

Specifies the end date for this timer. Specify as a DATE8 format (YYYYMMDD). There is no default.

STIME=starttime

Specifies the start time for this timer. Specify as HH.MM.SS. The default is the current system time.

ETIME=endtime

Specifies the end time for this timer. Specify as HH.MM.SS. There is no default.

FREQ={ nnnn | HH.MM.SS }

Specifies the timer interval between successive instances. Either a number of intervals or an hour/minute/second value is specified. The interval is determined by the FTYPE value. If a hour/minute/second value is specified, then FTYPE=TIME must be specified. Both the FREQ and FTYPE operands are only applicable if LIMIT is greater than one.

FTYPE={ MONTHS | DAYS | TIME }

Specifies the interval between successive instances. The actual interval is determined by the FREQ and FTYPE values. The TIME value represents seconds. The default is TIME. For example, FREQ=60 indicates every 60 seconds and FREQ=2 FTYPE=DAYS indicates every 2 days.

LIMIT = 0-9999

Specifies the number of instances that this timer will be activated. The frequency and interval between successive timer executions is determined by the FREQ and FTYPE operands. The default for LIMIT is 1 (one), indicating that this is a one-off timer. A value of 0 (zero) indicates that there is no limit and that there will be an infinite number of instances when the timer will be scheduled.

DAYLIST = (MON,TUE,WED,THU,FRI,SAT,SUN)

Specifies a list of days for which this timer is applicable. The default is all days are applicable.

CATCHUP = { YES | NO }

Specifies whether catchup is to be performed. This occurs if the next scheduled time for this timer has already passed. Catchup processing occurs at region initialization - any timers that were scheduled to occur whilst the region was down are scheduled for immediate execution at region initialization. The default is no catchup is performed.

DELEXP = { YES | NO }

Specifies whether this timer definition is to be deleted after expiry—that is, after the specified end date (EDATE) has passed. If EDATE was not specified, then the definition does not expire. The default is not to delete the timer definition at expiry.

STATUS = { ACTIVE | INACTIVE }

Specifies the actual status to be assigned to this timer definition. The status is changed to ACTIVE at a later time via a 'PUT' function call.

SAVE = { YES | NO }

Specifies whether the timer definition should be saved to the VFS file. SAVE=YES allows for timer definitions to be retained across system restarts.

ROUTE = { * | userid | MON | LOG | SYS }

Specifies the user ID under which this command is to be performed. The default ROUTE=* specifies the user ID executing the $TICALL.

KEEP = { MON | LOG | SYS }

Specifies the user ID under which this command is to be performed if the user ID specified by ROUTE has signed off. The default is LOG.

COMMAND = command

Specifies the command to be executed when the timer is scheduled to run. The command is up to 256 characters. If the command contains blanks, then it must be enclosed in quotes.

DESC = description

Specifies a description for this timer definition. The description is up to 256 characters. If the description contains blanks, then it must be enclosed in quotes.

Return Codes:

&RETCODE = 0

$TICALL completed successfully. Data is returned in the following variables:

$TICATCHUP

CATCHUP

$TICLASS

CLASS

$TICDATE

Create date

$TICOMMAND

COMMAND

$TIDELEXP

DELEXP

$TIEDATE

EDATE

$TIETIME

ETIME

$TIFREQ

FREQ

$TIFTYPE

FTYPE

$TIKEEP

KEEP

$TILIMIT

LIMIT

$TINAME

NAME

$TIROUTE

ROUTE

$TISDATE

SDATE

$TISTATUS

STATUS

$TISTIME

STIME

$TISUBCLASS

SUBCLASS

$TIUSER

Create user ID

$TIAUTH

User authority of $TIUSER

&RETCODE > 0

An error occurred. &SYSMSG is set with an error message.

Example: FUNC=ADD

&DOCMD = &STR 'SHOW USER' 
&TOMORROW = &DATECONV DATE8 &DATE8 DATE8 +1 
&DESC = &STR 'Show user at 2:00pm and 2:01pm tomorrow'
&CALL PROC=$TICALL SHARE=($TI>) PARMS=(FUNC=ADD CLASS=USER +
 NAME=CMD1 FREQ=60 LIMIT=2 SDATE=&TOMORROW STIME=14.00.00 +
 DESC=&DESC COMMAND=&DOCMD)

Note: If the text entered in the Description and Command fields contains imbedded blanks, they must be enclosed in quotes.