File control - commands, options, and conditions - II

Control operations

In this post I'll discuss the following group of functions in CICS.

* Interval control - comprising functions whose execution is dependent on time.
* Task control - comprising functions to temporarily relinquish control or to synchronize
resource usage.
* Program control - comprising functions affecting the flow of control between application
programs.
* Storage control - comprising functions to obtain and release areas of main storage.
* Transient data control - comprising functions for the transfer of data between CICS tasks and
between the CICS region and other regions.
* Temporary storage control - comprising functions for the temporary storage of data.


Interval control

The CICS interval control program, in conjunction with a time-of-day clock maintained by CICS, provides functions that can be performed at the correct time; such functions are called time-controlled functions. The time of day is obtained from the operating system at intervals whose frequency, and thus the accuracy of the time-of-day clock, depends on the task mix and the frequency of task switching operations. Using interval control commands you can:

* Request the current date and time of day (ASKTIME)
* Select the format of date and time (FORMATTIME)
* Delay the processing of a task (DELAY)
* Request notification when specified time has expired (POST)
* Wait for an event to occur (WAIT EVENT)
* Start a task and store data for the task (START)
* Retrieve data stored (by a START command) for a task (RETRIEVE)
* Cancel the effect of previous interval control commands (CANCEL).

Request current date and time of day (ASKTIME)

ASKTIME|
[ABSTIME(data-area)]|

You use this command to update the date and CICS time-of-day clock, and the fields EIBDATE and EIBTIME in the EIB. These two fields contain initially the date and time when the task started. The command returns the current time in the form of the number of milliseconds since 0000 hours on January 1, 1900.
The following example shows you how the ABSTIME option works:

EXEC CICS ASKTIME ABSTIME(utime)

After execution, 'utime' might contain the value 002694057952138 in milliseconds.

Select the format of date and time (FORMATTIME)

FORMATTIME
ABSTIME(data-value)
[YYDDD(data-area)]
[YYMMDD(data-area)]
[YYDDMM(data-area)]
[DDMMYY(data-area)]
[MMDDYY(data-area)]
[DATE(data-area)]
[DATEFORM(data-area)]
[DATESEP[(data-area)]]
[DAYCOUNT(data-area)]
[DAYOFWEEK(data-area)]
[DAYOFMONTH(data-area)]
[MONTHOFYEAR(data-area)]
[YEAR(data-area)]
[TIME(data-area)
[TIMESEP[(data-area)]]]

You use this command to transform the absolute date and/or time into any of a variety of formats.

The following example shows the effect of some of the options of the command:

EXEC CICS FORMATTIME ABSTIME(utime)
DATESEP('-') DDMMYY(date)
TIME(time) TIMESEP

Task control

The CICS task control program provides functions that synchronize task activity, or that control the use of resources.

CICS processes tasks according to priorities assigned by the system programmer. Control of the processor is given to the highest priority task that is ready to be processed and is returned to the operating system when no further work can be done by CICS or by user-written application programs.

Task control commands are provided to:

* Suspend a task (SUSPEND).

* Schedule the use of a resource by a task (ENQ and DEQ).


A task can issue the SUSPEND command to relinquish control and allow tasks higher on the active chain to proceed. This facility can be used to prevent processor-intensive tasks from monopolizing the processor. As soon as no other task higher on the active chain is waiting to be processed, control is returned to the issuing task; that is, the task remains dispatch able.

Scheduling the use of a resource by a task is sometimes useful in order to protect the resource from concurrent use by more than one task, that is, to make the resource serially reusable. Each task that is to use the resource issues an ENQ (enquire) commands. The first task to do so has the use of the resource immediately, but subsequent ENQ commands for the resource, issued by other tasks, result in those tasks being suspended until the resource is available. Each task using the resource should issue a DEQ (dequeue) command when it has finished with it. The resource then becomes available and the next task to have issued an ENQ command is resumed and given use of the resource. The other tasks obtain the resource in turn, in the order in which they enquired upon it.


Program control

The CICS program control program governs the flow of control between application programs in a CICS system. The name of an application program referred to in a program control command must have been defined as a program to CICS.

Program control commands are provided to:

* Link one user-written application program to another, anticipating subsequent return to the
requesting program (LINK). The COMMAREA option allows data to be passed to the
requested application program.

* Transfer control from one user-written application program to another, with no return to the
requesting program (XCTL). The COMMAREA option allows data to be passed to the
requested application program.

* Return control from one user-written application program to another or to CICS (RETURN).
The COMMAREA option allows data to be passed to a newly-initiated transaction.

* Load a designated application program, table, or map into main storage and return control to
the requesting program (LOAD).

* Delete a previously loaded application program, table, or map from main storage (RELEASE).


Application program logical levels

Application programs running under CICS are executed at various logical levels. The first program to receive control within a task is at the highest logical level. When an application program is linked to another, expecting an eventual return of control, the linked-to program is considered to reside at the next lower logical level. When control is simply transferred from one application program to another, without expecting return of control, the two programs are considered to reside at the same logical level.

Link to another program anticipating return (LINK)

LINK
PROGRAM(name)
[COMMAREA(data-area)
[LENGTH(data-value)]]

Conditions: NOTAUTH, PGMIDERR,
LENGERR

This command is used to pass control from an application program at one logical level to an application program at the next lower logical level. If the linked-to program is not already in main storage, it will be loaded. When the RETURN command is executed in the linked-to program, control is returned to the program initiating the linkage at the next sequential executable instruction.

The following example shows how to request a link to an application program called PROG1:

EXEC CICS LINK PROGRAM('PROG1')

The LENGTH option specifies the length of the data being passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are Unpredictable and may result in the LENGERR condition being set.

The linked-to program operates independently of the program that issues the LINK command with regard to handling exceptional conditions, attention identifiers, and abends. For example, the effects of HANDLE commands in the linking program are not inherited by the linked-to program, but the original HANDLE commands are restored on return to the linking program. Figure 40 illustrates the concept of logical levels.

Transfer program control (XCTL)

XCTL
PROGRAM(name)
[COMMAREA(data-area)
[LENGTH(data-value)]]

Condition: NOTAUTH, PGMIDERR, LENGERR

This command is used to transfer control from one application program to another at the same logical level. The program from which control is transferred is released. If the program to which control is transferred is not already in main storage, it will be loaded.

The following example shows how to request a transfer of control to an application program called PROG2:

EXEC CICS XCTL PROGRAM('PROG2')

The LENGTH option specifies the length of the data to be passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are unpredictable and may result in the LENGERR condition being set.

Return program control (RETURN)

RETURN
[TRANSID(name)
[COMMAREA(data-area)
[LENGTH(data-value)]]]

Condition: INVREQ, LENGERR

This command is used to return control from an application program either to an application program at the next higher logical level or to CICS.

When the RETURN command is issued in a lower-level program (that is, a linked-to program), control will be passed back to the level that is one logical level higher than the program returning control. If the task is associated with a terminal, the TRANSID option can be used at the lower level to specify the transaction identifier of the next transaction to be associated with that terminal. The transaction identifier will come into play only after the highest logical level has relinquished control to CICS using the RETURN command, and after input has been received from the terminal. Any input entered from the terminal, other than an attention key, will be interpreted wholly as data. In addition, the COMMAREA option can be used to pass data to the new task that will be started

No resource security checking occurs on the RETURN TRANSID command. However, transaction security checking is still available when CICS attaches the returned transaction.

The LENGTH option specifies the length of the data to be passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are Unpredictable and may result in the LENGERR condition being set. The COMMAREA and LENGTH options can be used only when the RETURN command is returning control to CICS; the INVREQ condition will occur otherwise. If the COMMAREA option specifies a zero value as the address of the data area, INVREQ is returned.