5. Provide task synchronization based on time-dependent events.
6. Provide automatic time-ordered task initiation with associated data retention and recovery support.
The services enumerated in items 1 through 3 are CICS/VS system services and require no action on the part of the application
programmer. The services enumerated in items 4 through 6 are available to the application programmer through use of the interval control macro instruction (DFHIC).
The application programmer must specify parameter values when using the DFHIC macro instruction. The values can be specified in either of two ways:
• By including the parameters in operands of the DFHIC macro instruction by which time services are requested, or
• By coding instructions that place the parameter values in fields of the TCA prior to issuing the CFHIC macro instruction.
The second of these approaches provides flexibility in that the
parameter values of a single DFHIC macro instruction can vary to meet the logic needs of the applicaticn program.
The application programmer can check the CICS/VS response to a
request for time services as explained under "Test Response to a Request for Time Services." If the programmer does not check for a particular response, and if the condition corresponding to that response occurs, program flow proceeds to the next sequential instruction in the
application program. All operands that can be included in the DFHIC macro instruction are discussed in detail under "DFHIC Macro
Instruction" in Chapter 7.
TIME-OF-~AY SERVICES (GETIME)
In the course of normal operation, CICS/VS maintains the current·
time of day in binary form at CSACTODB and in packed decimal form at CSATODP. The binary representation is expressed as a four-byte positive value in hundredths of a second. The packed decimal r~presentation is expressed as a four-byte positive signed value of the form HHMMSSt+
where the seconds are truncated to tenths of a second. The binary value is updated periodically during task dispatching, and the packed decimal value is updated when returning from an operating system WAIT.
The accuracy of these values at any given moment depends on the task mix and the frequency of task switching operations.
The application programmer can ensure that one cr both of these time-of-day values are updated to a current setting by issuing the
DFHIC TYPE=GETIME,
macro instruction. This macro instruction causes one or both forms of the time of day to be updated in the CSA and, optionally, places the requested form of the time of day in a four-byte field specified by the application programmer. When the programmer wants the time of day to be returned in a field other than those of the CSA. either the symbolic label of the four-byte field must be specified in the DFHIC
TYPE=GETn~E macro instruction or the address of the field must be placed in TCAICDA prior to issuing the DFHIC TYPE=GETIME macro instruction.
TIME
Note: For performance reasons, i t should be recognized that lengthy conversion routines must be executed whenever updating of the packed
decimal representation of tirre of day is requested.
The following example shows how to request that the time of day be placed at the storage locations represented by the symbolic label CLOCK.
DFHIC TYPE=GETIME, FORM=PACKED, TIMADR=CLOCK
REQUEST CURRENT TIME-OF-DAY
*
PACKED DECIMAL FORM
*
SYMBOLIC ADDRESS FOR RESPONSE The following examples show hcw to request that the time of day be placed in a field selected prior to (and independent of) execution of the DFHIC TYPE=GFTIME macro instruction.
For Assembler language:
MVC TCAICDA,=A(CLOCK) MOVE ADDR FOR RESPONSE TO TCA
· ·
DFHIC TYPE=GETIME,
·
REQUEST CURRENT TIME-OF-DAYFORM= PACKED, PACKED DEC~ FORM
TIMADR=YES RESPONSE ADDRESS GIVEN For ANS COBOL:
MOVE CLOCKADR TO TCAICDA. NOTE MOVE ADDR FOR RESP TO TCA.
· ·
DFHIC TYPE=GETIME,
·
REQUEST CURRENT TIME-OF-DAY FORM=PACKED, PACKED DECIMAL FORMTIMADR=YES RESPONSE ADDRESS GIVEN
For PL/I:
TCAICDA=ADDR(CLOCK) ; /*MOVE ADDR FOR RESP TO TCA*/
· ·
DFHIC TYPE=GETIME,
·
REQUEST CURRENT TIME-OF-DAY FORM=PACKED, PACKED DECIMAL FORMTIMADR=YES RESPONSE ADDRESS GIVEN
TIME-ORDERED TASK SYNCHRONIZATION (WAIT OR POST)
The task synchronization feature of CICS/VS time management provides the capability to either delay the processing of a requesting task until a specified time occurs or to signal the requesting task when a specified interval of time has elapsed. It also supports the
cancellation of a pending tine-ordered synchronization event by another task. (See "Time-Ordered Request Cancellation (CANCEL)" later in this section. )
Delay the processinq of ~ Task (WAIT)
The application programmer can request that the processing of a task be suspended until a specified time of day or for a specified interval of time by issuing the
132 CICS/vS Application Programmer's Reference Manual
* *
*
*
*
*
DFHIC TYPE=WAIT,
macro instruction. This macro instruction causes the requesting task to temporarily suspend processing, and to resume control at a specified time of day or after a specified interval of time has elapsed. I t supersedes and cancels any previously initiated £FHIC TYPE=POST request for the task.
A numeric value specified in the DFHIC TYPE=WAIT macro instruction (or before this macro instruction is issued) is used by CICS/VS to calculate the time of day the requested time service is to be provided.
If the calculated time of day is the same as the current clock time, or up to and including six hours preceding the current clock time, the specified time is considered to have elapsed (occurred) and the
requested service is provided immediately. If the calculated time of day is in advance of the current clock time, the requested service is provided when the specified time occurs. If the calculated time of day precedes the current clock time by more than six hours, the requested service is provided the next day at the specified time.
*
As a means of symbolically identifying the request and any data associated with it, a unique request identification is assigned to each time-ordered request. The application programmer can specify a request identification to be assigned to his DFHIC TYPE=WAIT request. If none is assigned by the programmer, CICS/VS assigns a unique request
identification. A request identification should be specified by the application programmer if he wishes to provide another task with the capability of canceling the unexFired WAIT request. (See the discussion of the DFHIC TYPE=CANCEL macro instruction.)
The following example shows how to temporarily suspend the processing of a task for a specified Feriod of time:
DFHIC TYPE=WAIT, INTRVAL=500, REQID=GXLBZQMR
DELAY TASK PROCESSING, WAIT 5 MINUTES 0 SECONDS UNIQUE REQUEST ID
The following examples show how to request the suspension of a task until the time of day stored previously in TCAICRT is reached. A request identification previously selected by the user is stored in TCAICQID as a unique identifier for this request for time service.
For Asserrbler language:
MVC TCAICRT,=PL4'124500' MVC TCAICQID,UNIQCODE
DFHIC TYPE=WAIT, TIME=YES, REQIO=YES For ANS COBOL:
MOVE 124500 TO TCAICR~.
MOVE UNIQCODE TO TCAICQID.
MOVE 12:45 TO TCA
UNIQUE REQUEST ID TO TCA
DELAY TASK PROCESSING EXPIRATION TIME GIVEN UNIQUE 10 GIVEN
NOTE MOVE 12:45 TO TCA.
NOTE UNIQUE REQUEST ID TO TCA.
- - - - - - - - - - - --- - - - - -
-* *
* *
DFHIC TYPE=WAIT, TIME=YES, REQID=YES
TCAICRT= 124500;
TCAICQID=UNIQCODEi DFHIC TYPE=WAIT,
TIME=YES, REQID=YES
DELAY TASK PROCESSING EXPIRATION TIME GIVEN UNIQUE ID GIVEN
/*MOVE 12:45 TO TCA*/
/*u~IQUE REQUEST ID TO TCA*/
DELAY TASK PROCESSING EXPIRATION TIME GIVEN UNIQUE ID GIVEN
Signal the Expiration of ~ Specified Time (~)
The application programmer can request that CICS/VS indicate to the requesting task when a given time has expired by issuing the
DFHIC TYPE=POST,
macro instruction. In response to this macro instruction, CICS/VS makes a timer event control area available to the user for testing.
This four-byte storage area is initialized to binary zeros and its address is returned to the requesting task in TCAICTEC.
When CICS/VS determines that the time specified in a CFHIC TYPE=POST macro instruction has expired, byte 0 of the timer event control area is set to a hexadecimal 40 and byte 2 is set to a hexadecimal 80. This form of posting is compatible with the completion code postings
performed by the operating systems. The timer event control area can be used as the event contrel area referred to in a DFHKC TYPE=WAIT macro instruction. (See the discussion of task synchronization under
"Task services.")
The timer event control area ~rovided to the user is not released
* *
* *
*
or altered (exceft as described above) until one of the following events occurs:
• The task issues a subsequent DFHIC TYPE=WAIT, DFHIC TYPE=POST, DFHIC TYPE=INITIATE, or DFHIC TYFE=PUT macro request.
• The task issues a DFHIC TYPE=CANCEL macro request to nullify the DFHIC TYPE=POST request (this releases the storage area occupied by the timer event contrel area).
• The task terminates, normally or abnormally.
A task can have only one LFHIC TYPE=POST request active at any given time. Any DFHIC TYPE=WAIT, DFHIC TYPE=POST, DFHIC TYPE=INITIATE, or DFHIC TYPE=PUT request supersedes and cancels a previously issued DFHIC TYPE=POST request by the task.
Note: The expiration of any CICS/VS time-ordered event is determined by CICS/VS when i t is performing its task dispatching function.
Therefore, for II posting" to occur, the application programmer must
ensure that the task relinquishes control of CICS/VS before each testi'ng of the timer event control area. This can be done directly by issuing the DFHKC TYPE=WAIT or DFHKC TYPE=CHAP macro instruction (see the
discussion of task synchronization under "Task Services") or indirectly
134 CICS/VS Application Programmer's Reference Manual
by requesting a CICS/VS service which in turn initiates a task service on behalf of the task.
A numeric value specified in or before issuing the DFHIC TYPE=POST macro instruction is used by CICS/VS to calculate the time of day at which the requested time service is to be provided. If the calculated time of day is the same as the current clock time, or up to and
including six hours preceding the current clock time, the specified time is considered to have elapsed (occurred) and the requested service is provided immediately. If the calculated time of day is in advance of the current clock time, the requested service is provided when the specified time occurs. If the calculated time of day precedes the current clock time by more than six hours, the requested service is provided the next day at the specified time.
The application programmer can specify a request identification to be assigned to a posting request. If not, CICS/VS assigns a unique request identification, which is returned to the application program in TCAICQID in the form "DFHNNNNN". In either case, the request
identification provides a means of symbolically identifying the request.
The following example shows how to request that CICS/VS provide a signal for the task when a specified interval of time has elapsed:
DFHIC TYPE=POST, INTRVAL=30
SIGNAL WHEN INTERVAL PASSES INTERVAL IS 30 SECONDS
The following examples shew how to dynamically request that CICS/VS provide a signal for the task when the time of day previously stored in TCAICRT is reached. Since no request identification is specified by the application programmer, CICS/VS automatically assigns one and returns i t to the application program at TCAICQID .•
For Assembler language:
MVC TCAICRT,PACKTIME STORE CALCULATED EXPIR TIME
· ·
OFHIC TYPE=POST, SIGNAL WHEN TIME OCCURS
TIME=YES EXPIRATION TIME GIVEN
MVC UNIQCODE,TCAICQIO SAVE CICS/VS UNIQUE REQUEST ID For ANS COBOL:
MOVE PACKTIME TO TCAICRT. NOTE STORE CALC EXPIR TIME.
· ·
DFHIC TYPE=POST, SIGNAL WHEN TIME OCCURS
TIME=YES EXPIRATION TIME GIVEN
MOVE TCAICQID TO UNIQCODE. SAVE CICS/vS UNIQUE REQUEST ID For PL/I:
T CAICRT= PACKT IME; /*STORE CALCULATED EXPIR TIME*/
· ·
DFHIC TYPE=POST, SIGNAL WHEN TIME OCCURS
TIME=YES EXPIRATION TIME GIVEN
UNIQCOOE=TCAICQID; SAVE CICS/vS UNIQUE REQUEST 10
*
*
*
*
AUTOMATIC TIME-ORDERED TASK INITIATION (INITIATE OR PUT)
This feature of time management allows a task to initiate another task at some future time and, optionally, to pass data to that task.
Task Initiation without Data (INITIATE)
The application programmer can request that another task be initiated at some future time by issuing the
DFHIC TYPE=INITIATE,
macro instruction. Through this macro instruction, the application programmer provides the transaction identificaticn of the task to be initiated at some future time and other information pertaining to the task. CICS/VS queues the request until the specified time occurs.
Then, as soon as all necessary resources are available (for example, a terminal), the task is initiated. Only one task is initiated if multiple DFHIC TYPE=INITIATE requests for the sarre transaction and terminal expire at the same time cr ~rior to terminal availability.
No data can be passed to the future task by means of the DFHIC
TYPE=INITIATE macro instruction. (TO do so, see "Task Initiation with Data (PUT)," which follows.) This request supersedes and cancels any previously initiated DFHIC TYPE=FOST request by the initiating task.
A numeric value specified in or before issuing the DFHIC
TYPE=INITIATE macro instruction is used by CICS/VS to calculate the time of day at which the requested time service is to be provided. If the calculated time of day is the same as the current clock time, or up to and including six hours preceding the current clock time, the specified time is considered to have elapsed (occurred) and the
requested service is provided immediately. If the calculated time of day is in advance of the current clock time, the requested service is provided when the specified time occurs. If the calculated time of day precedes the current clock time by more than six hours, the requested service is provided the next day at the specified time.
As stated earlier, a unique request identification is assigned to each time-ordered request as a means of symbolically identifying the request and any data associated with it. The application programmer can specify an identifier for his initiation request, or he can let CICS/VS assign one, in which case i t is returned to the application program in TCAICQID in the form "DFHNNNNN".
The application programmer must specify the transaction
identification of the future task, either in the BFHIC TYPE=INITIATE macro instruction or by placing i t in TCAICTI before issuing the macro instruction. CICS/VS validates the transaction identification by scanning the program control table (PCT). If the specified identifier is not found in the table, CICS/VS does not provide the requested service; a response code is placed at TCAICTR (for Assembler language or PL/I) or at TCAICRC (for ANS COBO~ to indicate that the transaction identification is not valid.
If the future task must communicate with a terroinal, the application programmer must also specify a terminal identification, either in the macro instruction or by placing i t beforehand in TCAICTID. If i t fails to locate the terminal identification in the TCT, CICS/VS validates the terminal identification ~ scanning the terminal control table
(TCT), providing a response code at TCAICTR (for Assembler language or PL/I) or at TCAICRC (for ANS COBOL) without servicing the request.
136 CICS/vS Application Programmer's Reference Manual
*
The following example shows how to request autcmatic initiation of a specified task not associated with a terminal:
OFHIC TYPE=INITIATE, INTRVAL=10000, TRANSIO=TRNL
REQUEST TASK INITIATION IN ONE HOUR
TRANSACTION IDENTIFICATION The following examples show how to dynamically request automatic initiation of a task associated with a terminal. The task initiation time, transaction identification, and terminal identification are moved to fields of the TCA before the DFHIC TYPE=INITIATE macro instruction is issued. Since no request identification is specified by the
application programmer, CICS/vS automatically assigns one and returns i t to the application program at TCAICQID.
For Assembler language:
MVC TCAICRT,=PL4'10000', MOVE ONE HOUR TO TCA MVC TCAICTI,=CL4'TRN1' TRANSACTION ID TO TCA MVC TCAICTIO,=CL4'STA5' TERMINAL ID TO TCA
· ·
·
DFHIC TYPE=INITIATE, REQUEST TASK INITIATION INTRVAL=YES , INTERVAL OF TIME GIVEN TRMIDNT=YES TERMINAL ID GIVENMVC UNIQCODE,TCAICQID SAVE CICS/vS UNIQUE REQUEST ID For ANS COBOL:
MOVE 10000 TO TCAICR!'. NOTE MOVE ONE HOUR TO TCA.
MOVE 'TRN1' TO TCAICTI. NOTE TRANSACTION ID TO TCA.
MOVE 'STASi TO TCAICTID. NOTE TERMINAL ID TO TCA.
· ·
DFHIC TYPE=INITIATE,
·
REQUEST TASK INITIATION INTRVAL=YES, INTERVAL OF TIME GIVEN TRMIDNT=YES TERMINAL ID GIVENMOVE TCAICQID TO UNIQOODE. SAVE CICS/vS UNIQUE REQUEST ID For PL/I:
TCAICRT=10000; /*MOVE ONE HOUR TO TCA*/
TCAICTI=' TRN1 • ; /*TRANSACTION 10 TO TCA*/
TCAICTID= 'STAS' ; /*TERMINAL 10 TO TCA*/
.. ·
·
* *
*
*
*
*
DFHIC TYPE=INITIATE, REQUEST TASK INITIATION * INTRVAL=YES, I~TERVAL OF TIME GIVEN
TFMIDNT=YES TERMINAL ID GIVEN
UNIQCODE=TCAICQID; SAVE CICS/vS UNIQUE REQUEST ID Task Initiation with ~ (PUT)
The application programme~ can pass data to another task that is to be initiated at some future time by issuing the
*
DFHIC TYPE=PUT,
macro instruction. This macro instruction is used to provide the transaction identification, the location of the data to be stored, and other information applicable to the task to be initiated. CICS/VS stores the data and queues the request until the specified time occurs.
As soon as all necessary resources are available (for example, a
terminal), the task is initiated. CICS/VS temporary storage management facilities support this facility of time management.
The DFHIC TYPE=PUT macro instruction is used only when data is to be passed to a task to be initiated at some future time. It supersedes and cancels any previously initiated DFHIC TYPE=POST request of the task. If only task initiation at a future time is needed, the DFHIC TYPE=INITIATE macro instruct'ion should be used.
*
If the task to be initiated is associated with a terminal, the initial DFHIC TYPE=PUT request causes the task to be initiated at the specified time. Subsequent PUTS with the same terminal identification, transaction identification, and expiration time are used to store data for subsequent retrieval by the initiated task. If the task to be
initiated is not associated with a terminal, each DFHIC TYPE=PUT request results in a task being initiated at the specified time. That is, only one physical data record can be passed to a task not associated with a terminal. (See "Retrieve Time-Ordered Data. It)
Most operands of the DFHIC TYPE=PUT macro instruction are analogous to similar operands of the DFHIC TYPE=INITIATE· macro instruction. The discussions of time calculation, request identification, transaction identification, and terminal identification given under "Task Initiation without Data (INITIATE)" apply to DFHIC TYPE=PUT in the same manner as they apply to DFHIC TYPE=INITIATE (see the preceding subsection of this manual). In addition, because the DFHIC TYPE=PUT macro instruction permits data to be passed, the application programmer must specify the symbolic address of the field containing the data. The label
may
be provided as a parameter of the macro instruction or move the addressMost operands of the DFHIC TYPE=PUT macro instruction are analogous to similar operands of the DFHIC TYPE=INITIATE· macro instruction. The discussions of time calculation, request identification, transaction identification, and terminal identification given under "Task Initiation without Data (INITIATE)" apply to DFHIC TYPE=PUT in the same manner as they apply to DFHIC TYPE=INITIATE (see the preceding subsection of this manual). In addition, because the DFHIC TYPE=PUT macro instruction permits data to be passed, the application programmer must specify the symbolic address of the field containing the data. The label