Interval Control CICS Interval control provides a variety of time related functions. They are ASKTIME, FORMATTIME, START, RETRIEVE, DEL...
CICS Interval control provides a variety of time related functions. They are ASKTIME, FORMATTIME, START, RETRIEVE, DELAY, POST and CANCEL commands.
The EIBTIME and EIBDATE fields in the EIB block provide the date and time the task was dispatched. These fields are not updated when the task executes and this may not be acceptable for long running tasks. For this reason the ASKTIME and FORMATTIME commands are provided to get the time / date which is current at the time of the call. The ASKTIME and FORMATTIME commands provide you with a variety of choices in the way the date / time may be formatted. The EIB fields today have the following format:-
EIBDATE
contains the date the task is started; this field is updated by the ASKTIME command. The date is in packed decimal form (0CYYDDD+) where C shows the century with values 0 for the 1900s and 1 for the 2000s. For example, the dates 31 December 1999 and 1 January 2000 have EIBDATE values of 0099365 and 0100001 respectively. The field is represented in COBOL as PIC S9(7) COMP-3 or in PL/I as FIXED DEC(7,0).EIBTIME
contains the time at which the task is started (this field is updated by the ASKTIME command). The time is in packed decimal form (0HHMMSS+).
The fields are represented in COBOL as PIC S9(7) COMP-3 and in PL/I as FIXED DEC(7,0).
The ASKTIME command places the absolute elapsed time from 0000hours on January 1st 1900 in milliseconds in your specified data area which must be a PIC S9(15) COMP-3 field. In PL/I it must be a DECIMAL FIXED(15) field.
The ASKTIME command
EXEC CICS
ASKTIME [ABSTIME(data-area) ]
END-EXEC
Note that the receiving data area is optional because the call updates the EIBDATE and EIBTIME fields as well.
In most cases, you don’t need to specify a receiving field if the format of the EIBTIME and EIBDATE is acceptable. If you need a different format, you can specify a receiving area and then call FORMATTIME using the data area as an argument.
The FORMATTIME command
EXEC CICS
FORMATTIME ABSTIME(data-area)
[DDMMYY(data-area)]
[DDMMYYYY(data-area)]
[MMDDYY(data-area)]
[MMDDYYYY(data-area)]
[YYDDD(data-area)]
[YYDDMM(data-area)]
[YYMMDD(data-area)]
[YYYYDDD(data-area)]
[YYYYDDMM(data-area)]
[YYYYMMDD(data-area)]
[DATE(data-area) [DATEFORM(data-area)]]
[FULLDATE(data-area)]
[DATESEP [(data-value)]]
[DAYCOUNT(data-area)]
[DAYOFWEEK(data-area)]
[DAYOFMONTH(data-area)]
[MONTHOFYEAR(data-area)]
[YEAR(data-area)]
[TIME(data-area) [TIMESEP [(data-value)]]]
END-EXEC
Options
ABSTIME The data area corresponding to this is the return value from ASKTIME and is a PIC S9(15) COMP-3 field. It is the elapsed time in milliseconds from midnight of 1st January 1900.
YY..DD..MM These represent different formats in which the formatted date is returned. Make sure that the data-area which is a receiving field is big enough to hold the returned character string. A ‘/’ is used as the separator if DATESEP is specified but the optional data value is omitted. Make sure that the data area includes space for the separators too.
DAYCOUNT,DAYOFWEEK,DAYOFMONTH,MONTHOFYEAR,YEAR,TIME are set into fullword fields of type PIC S9(8) COMP.
TIMESEP If you specify TIMESEP but don’t give a value the ‘:’ is used to separate the hours, minutes and seconds.
Condition: INVREQ
Example
The following example shows the effect of some of the options of the command. Let "utime" contain the value 002837962864828 in milliseconds.
EXEC CICS ASKTIME ABSTIME(utime)
EXEC CICS FORMATTIME ABSTIME(utime)
DATESEP('-') DDMMYY(date)
TIME(time) TIMESEP
This gives the values 06-12-89 for "date" and 19:01:05 for "time".
Automatic time-ordered transaction initiation
This facility allows you to start a new task using a START command. You can pass data to the started task, that can be retrieved by the started task using the RETRIEVE command. You can also request a CANCEL command for the started task before it starts. This is because the START command also accepts arguments which let you specify when or after what time interval the new task is to be started. The START command runs the started task asynchronously. In other words the task issuing the START command and the started task can run concurrently. In contrast the LINK is a synchronous call as the caller blocks until the linked to program exits. Also the linked to program and the program issuing the LINK run as one task.
How a task is scheduled
The START command is serviced by the CICS component INTERVAL CONTROL. It creates a ICE or interval control element whenever a START command is issued. The ICE contains information about the task to be started, including its transaction-id, Terminal-id, expiration time and the data to be passed to the started task. Interval Control uses Temporary Storage to store the passed data.
Since many tasks may issue START commands, and they may have different expiration periods, it is likely that a number of ICE’s may exist in the CICS region at any point of time. CICS code periodically checks the ICE’s to see if any expiration time has been reached and the new task can be started.
Note that the task issuing the START command blocks only until CICS creates a ICE to register the START request. The issuing task unblocks after the ICE is created and the passed data is written to the TS and can do whatever other processing it chooses.
The START command
EXEC CICS
START TRANSID(name)
INTERVAL(hhmmss)
TIME(hhmmss)
AFTER [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
AT [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
[ TERMID(name) ]
[ SYSID(name) ]
[ FROM(data-area) [ LENGTH(data-value)]]
[ RTERMID(name) ]
[ RTRANSID(name) ]
[ QUEUE(name) ]
[ REQID(name) ]
[ NOCHECK ]
[ PROTECT ]
END-EXECOptions
TRANSID A four character transaction identifier.
INTERVAL Specifies the expiration time interval. You can code a literal in the form hhmmss. If you specify a data area it must be a PIC S9(7) COMP-3 field and the value must be in the form 0hhmmss.
TIME Specifies a time of the day. You can code a literal in the form 0hhmmss. If you specify a data area it must be a PIC S9(7) COMP-3 field and the value must be in the form 0hhmmss.
AFTER Specifies that the HOURS, MINUTES and SECONDS options indicate the time of day when the task is to be started. If INTERVAL, TIME, AFTER and AT are all omitted, interval(0) isassumed.
HOURS, Each is a PIC S9(8) COMP full word. Hours can be from 0-99
MINUTES, minutes can be from 0 to 59 or 0 to 5999
SECONDS. Seconds can be from 0 to 59 or 0 to 359999
If INTERVAL, TIME, FOR and UNTIL are omitted, INTERVAL(0) is assumed.
TERMID Specifies a one to four character terminal ID. If omitted the task is not attached to any terminal and cannot perform any terminal I/O.
SYSID A one to four character Connection name that represents a remote system where the transaction is to be started.
REQID Specifies a one to eight character name you specify to uniquely identify this request. It can be used to CANCEL the START request before the new task has started. CANCEL has no effect after the new task has started. You can allow CICS to generate a REQID in the EIBREQID field as an alternative to generating one yourself.
FROM Specifies the data-area from where the data is to be passed to the started task.
LENGTH Specifies the length of the data-area from where data is to be passed to the started task. It is a half word field PIC S9(4) COMP.
RTRANSID Specifies a one to four character name that is passed to the started task. The started task fetches this using the RTRANSID option of the RETRIEVE command.
QUEUE Specifies a one to eight character name that is passed to the started task. The started task fetches this using the QUEUE option of the RETRIEVE command.
NOCHECK Specifies that the task issuing the START command should not wait until the remote system has confirmed that the START was successfully processed.
PROTECT Specifies that the task should not be started until the task issuing the START takes a syncpoint.
Conditions:
INVREQ The START command is invalid. Possible causes are the expiration period specification is out of range, or REQID already exists. For example ss may be specified as 70.
IOERR An I/O error occurred.
ISCINVREQ An undeterminable error occurred at the remote system.
LENGERR A length error occurred. Occurs if the length is not greater than 0. The maximum length, to be on safe side should not exceed 30000.
SYSIDERR The remote system could not be accessed / located.
TERMIDERR The terminal is not known to CICS.
TRANSIDERR the transaction id is not known to CICS.
Notes
- The START command is useful to divide an application functions into two separate independent tasks, which can run concurrently. It can also be used to start transactions at a predetermined time or after a time interval.
- If more than one START command is issued for the same target transaction, the first started task can retrieve all the passed data by issuing RETRIEVE calls more than once. If it does this CICS does not start a new started task for each start request.
- If you specify only one of HOURS | MINUTES | SECONDS, you are not bound by the limit of 60 for seconds and minutes or 24 for hours. You can use the higher limits.
The CANCEL command
EXEC CICS
CANCEL [ REQID(name)]
[ TRANSID(name) ]
[ SYSID(name) ]
END-EXEC
Options
TRANSID A four character transaction identifier of the transaction that you want cancelled. Not normally used, as REQID is more specific. You just specify CANCEL if you want to cancel a POST command from the same task.
SYSID A one to four character Connection name that represents a remote system where a DELAY, POST or START command is to be cancelled.
REQID Specifies a one to eight character name that is associated with the command you want cancelled. The only case where REQID is not required is when you want to cancel a POST command you issued earlier from the same task. In this case don’t code any of the options. REQID is required if you code SYSID or TRANSID.
Conditions
INVREQ The START command is invalid.
ISCINVREQ An undeterminable error occurred at the remote system.
NOTFND There is no unexpired ICE with the REQID specified.
SYSIDERR The remote system could not be accessed / located.
Notes
- The key element used by CICS to identify the command you want cancelled is the REQID. You can get this by fetching it from the EIBREQID field of the EIB after a START, DELAY or POST command. Alternately you can specify your own application generated REQID in the REQID field of the START, DELAY or POST command.
- The CANCEL command wont work if the expiration interval of the ICE has already expired. If you do so you will get a NOTFND condition.
The DELAY command
This command lets you suspend the issuing task until the time interval has expired, or a specific time of day has arrived.
EXEC CICS DELAY
{
INTERVAL(hhmmss)
TIME(hhmmss)
FOR [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
UNTIL [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
}
[ REQID(name) ]
END-EXECOptions
INTERVAL Specifies the duration for the delay. You can code a literal in the form hhmmss. If you specify a data area it must be a PIC S9(7) COMP-3 field and the value must be in the form 0hhmmss.
TIME Specifies a time of the day when the delay will end. You can code a literal in the form hhmmss. If you specify a data area it must be a PIC S9(7) COMP-3 field and the value must be in the form 0hhmmss.
FOR Specifies in HOURS, MINUTES and SECONDS the delay.
UNTIL Specifies in HOURS, MINUTES and SECONDS the time of the day when the delay will end.
HOURS, Each is a PIC S9(8) COMP full word. Hours can be from 0-99
MINUTES, minutes can be from 0 to 59 or 0 to 5999
SECONDS. Seconds can be from 0 to 59 or 0 to 359999
If INTERVAL, TIME, FOR and UNTIL are omitted, INTERVAL(0) is assumed.
REQID Specifies a one to eight character name used to uniquely identify this delay command.
Conditions
EXPIRED The TIME or UNTIL option has already expired. The default action is to return control immediately to your program.
INVREQ The command is not valid or the hours, minutes or seconds are out of range. Default action is to terminate the task.
Notes
- One good use of the DELAY command is to retry operations that have failed due to transient conditions. Such operations are worth a retry after a suitable delay. This delay, or momentary suspension of task execution can be achieved by the DELAY command.
- One trivial use is to momentarily suspend a transaction that is notorious for consuming resources. This makes for better sharing of resources across transactions.
The RETRIEVE command
EXEC CICS
RETRIEVE {INTO(data-area) | SET(pointer-ref) }
[ LENGTH(data-area) ]
[ RTRANSID(data-area) ]
[ RTERMID(data-area) ]
[ QUEUE(data-area) ]
[ WAIT ]
END-EXEC
Options
INTO Specifies the data area that will contain the data sent via the FROM option of the START command.
LENGTH Specifies the length of the INTO area on input. Must be Half word PIC S9(4) COMP. On return from the call has the length of the data actually retrieved.
RTRANSID Specifies a four character area that will contain the data sent via the RTRANSID option of the START command.
RTERMID Specifies a four character area that will contain the data sent via the RTERMID option of the START command.
QUEUE Specifies a eight character area that will contain the data sent via the QUEUE option of the START command.
WAIT Suspend this task until another ICE expires and the data associated with that START command is available.
Conditions
ENDDATA No data is available for the STARTED task.
ENVDEFERR The retrieve command specified a INTO, SET, RTRANSID, RTERMID or QUEUE option and no such option was specified in the START command.
INVREQ The command is not valid.
IOERR An I/O error occurred.
LENGERR The length specified was not enough to fetch the complete data retrieved.
NOTFND The data has been deleted by another task.
Notes
- You can code a iterative server process which issues RETRIEVE repeatedly until ENDDATA is raised. This prevents more similar tasks from being started. You can use the WAIT option to good effect if you are expecting more data in the short term.
- The RTRANSID, RTERMID and QUEUE are provided to pass specific types of data to the started task. See asynchronous client server scenarios described earlier in this material.
- You should always check for the ENDDATA condition.
The POST command
The POST command creates a Timer event control area that expires when a specified time interval has expired. You can then use a WAIT EVENT command to block the task until the posted event expires.
EXEC CICS POST
{
INTERVAL(hhmmss)
TIME(hhmmss)
AFTER [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
AT [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
}
SET(pointer-ref)
[ REQID(name) ]
END-EXECOptions
INTERVAL Specifies the duration after which the event is POSTED. You can code a literal in the form hhmmss. If you specify a data area it must be a PIC S9(7) COMP-3 field and the value must be in the form 0hhmmss.
TIME Specifies a time of the day when the event expires. You can code a literal in the form hhmmss. If you specify a data area it must be a PIC S9(7) COMP-3 field and the value must be in the form 0hhmmss.
AFTER Specifies in HOURS, MINUTES and SECONDS the time interval after which the event expires.
AT Specifies in HOURS, MINUTES and SECONDS the time of the day when the event will expire.
HOURS, Each is a PIC S9(8) COMP full word. Hours can be from 0-99
MINUTES, minutes can be from 0 to 59 or 0 to 5999
SECONDS. Seconds can be from 0 to 59 or 0 to 359999
If INTERVAL, TIME, FOR and UNTIL are omitted, INTERVAL(0) is assumed.
REQID Specifies a one to eight character name used to uniquely identify this POST command. You can omit this field and allow CICS to generate a REQID in the EIBREQID field. This REQID can be used to CANCEL the POST command.
SET Specifies a Full Word binary field PIC S9(8) COMP where CICS places the address of the Timer Event Control area.
EXPIRED The time you specified in the interval or time option has already expired.
INVREQ The command is invalid, or the HOURS, MINUTES or SECONDS are out of range.
Notes
- One useful implementation of this command is to force a minimum response time on the transaction. Do this by issuing a POST at the start of the program and then issuing a WAIT EVENT just before sending the final data.
The WAIT EVENT command
EXEC CICS
WAIT EVENT ECADDR(pointer-ref)
END-EXEC
Options
ECADDR The pointer returned by the POST command in the SET field. This is a binary full word field PIC S9(8) COMP.
Conditions
INVREQ The address of the timer event control area is invalid.
Example of START tranid SM01
IDENTIFICATION DIVISION.
PROGRAM-ID. SAMP1.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-VARS.
03 WS-START-DATA PIC X(30)
VALUE "START DATA FROM SAMP1".
03 WS-START-DATA-LEN PIC S9(04) COMP VALUE 30.
03 WS-RESP PIC S9(08) COMP VALUE 0.
PROCEDURE DIVISION.
PERFORM MAIN-PARA
PERFORM END-PARA.
MAIN-PARA.
EXEC CICS
START
TRANSID("SM02")
FROM(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
TERMID(EIBTRMID)
RESP(WS-RESP)
END-EXEC.
END-PARA.
EXEC CICS
RETURN
END-EXEC.
Example of RETRIEVE tranid SM02
IDENTIFICATION DIVISION.
PROGRAM-ID. SAMP2.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-VARS.
03 WS-START-DATA PIC X(30).
03 WS-START-DATA-LEN PIC S9(04) COMP VALUE 30.
03 WS-RESP PIC S9(08) COMP VALUE 0.
PROCEDURE DIVISION.
PERFORM MAIN-PARA
PERFORM END-PARA.
MAIN-PARA.
EXEC CICS
RETRIEVE
INTO(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
RESP(WS-RESP)
END-EXEC
EXEC CICS
SEND TEXT FROM(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
RESP(WS-RESP)
END-EXEC.
END-PARA.
EXEC CICS
RETURN
END-EXEC.
Example of DELAY tranid SM03
The program goes to ICWAIT for 30 seconds
IDENTIFICATION DIVISION.
PROGRAM-ID. SAMP3.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-VARS.
03 WS-START-DATA PIC X(30)
VALUE "SAMP3 STARTING...".
03 WS-START-DATA-LEN PIC S9(04) COMP VALUE 30.
03 WS-RESP PIC S9(08) COMP VALUE 0.
PROCEDURE DIVISION.
PERFORM MAIN-PARA
PERFORM END-PARA.
MAIN-PARA.
EXEC CICS
SEND TEXT FROM(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
RESP(WS-RESP)
END-EXEC
EXEC CICS
DELAY
FOR
SECONDS(30)
RESP(WS-RESP)
END-EXEC
MOVE "SAMP3 ENDING AFTER DELAY ...." TO WS-START-DATA
EXEC CICS
SEND TEXT FROM(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
RESP(WS-RESP)
END-EXEC.
END-PARA.
EXEC CICS
RETURN
END-EXEC.
Example of POST tranid SM04
The program goes to EKCWAIT for 30 seconds
IDENTIFICATION DIVISION.
PROGRAM-ID. SAMP4.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-VARS.
03 WS-START-DATA PIC X(30)
VALUE "SAMP4 STARTING...".
03 WS-START-DATA-LEN PIC S9(04) COMP VALUE 30.
03 WS-TIMER-PTR PIC S9(8) COMP VALUE 0.
03 WS-TIMER-PTR-LEN PIC S9(4) COMP VALUE 4.
03 WS-RESP PIC S9(08) COMP VALUE 0.
PROCEDURE DIVISION.
PERFORM MAIN-PARA
PERFORM END-PARA.
MAIN-PARA.
EXEC CICS
SEND TEXT FROM(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
RESP(WS-RESP)
END-EXEC
EXEC CICS
POST
AFTER
SECONDS(20)
SET(WS-TIMER-PTR)
RESP(WS-RESP)
END-EXEC
EXEC CICS
WAIT EVENT
ECADDR(WS-TIMER-PTR)
RESP(WS-RESP)
END-EXEC
MOVE "SAMP4 ENDING" TO WS-START-DATA
EXEC CICS
SEND TEXT FROM(WS-START-DATA)
LENGTH(WS-START-DATA-LEN)
RESP(WS-RESP)
END-EXEC.
END-PARA.
EXEC CICS
RETURN
No comments
Post a Comment