This general macro is used to enter a program after a specified interval of
time has elapsed. The control program will save this request and
transfer control to the specified program at the correct time. A new
entry control block (ECB) is created when the specified program is
entered. The ECB is created on the same I-stream, in the same
subsystem, and subsystem user as the creating ECB.
Format
- label
- A symbolic name can be assigned to the macro statement.
- M
- The time increment in minutes.
- S
- The time increment in seconds.
- prog
- The four character alphanumeric name of the program to be activated must
be specified either as parameter two or as its keyword alternate. The
first character must be alphabetic. This method generates a V-con which
is resolved at link edit time into a Program Allocation Table (PAT)
displacement. This is the preferred method for specifying the program
name.
- PROGRAM
- The name of the program can alternately be provided via the PROGRAM
parameter. This method generates constant data which will be used at
execution time to determine the Program Allocation Table (PAT)
displacement. This method has a longer path length than the one
described above.
- prog
- The name of the program that is to be activated with the created
ECB.
- (reg)
- A register (R0-R7) that contains the address of the program
name.
- PARM=sd|label|(reg)
- This parameter specifies the 4-byte action word to be passed to the called
program. The operand may be a self-defining term, a symbolic label, or
a register enclosed in parenthesis containing the address of the actual
parameter. The default is R15.
- TIMEINC=sd|label|(reg)
- This parameter specifies the number of minutes or seconds from the present
time a specified program is to be executed. This parameter is valid
only if STATE=1052 has been specified. The operand may be a
self-defining term, a symbolic label, or a register enclosed in
parenthesis. If not specified the value must be placed in the rightmost
3 bytes (right-justified) of R14.
- Note:
- When you specify the time increment in minutes, an ECB is created at a full
minute boundary, which can be less than the interval specified with the
TIMEINC parameter. For example, assume you specified an interval of 1
minute. If the current time is 10:35:55, the new ECB can be
created at 10:36:00.
- STATE=1052
- This optional parameter allows the program specified by prog or
the PROGRAM parameter to be activated at the time requested even when the
system is in 1052 state. The only allowed operand is
'1052'. If STATE is not specified, the program requested by
prog or PROGRAM parameters cannot be activated until the system is
cycled above 1052 state.
- LEVEL=datalevel
- This optional parameter allows you to specify a data level (D0...DF)
to be passed to the new ECB. The level should be coded as one of the
standard data level equates D0, D1, ... DF.
When the new ECB is dispatched, the block from the issuing ECB's data
level will be available to the new ECB on its data level 0.
When control is returned to the issuing ECB, the storage block previously
attached at the level is detached and is no longer available for use by the
issuing ECB.
- DECB=(reg)|label1
- The label or general register (R1-R7) containing the address of the
data event control block (DECB) that contains the block to be passed to the
created ECB.
When the new ECB is dispatched, the block from the DECB of the issuing ECB
will be available to the new ECB on data level 0.
When control is returned to the issuing ECB, the storage block previously
attached at the DECB is detached and is no longer available for use by the
issuing ECB.
- DSECT=NO|YES
- An optional keyword parameter to request the generation of a DSECT
describing the parameter list generated for the CRETC call. The use of
this parameter should be limited to the CRETC service routines. If YES
is coded, no CRETC expansion will be generated, instead only an expansion of
the parameter list is generated. The default is NO.
Entry Requirements
- R9 must contain the address of the ECB being processed.
- R14 must contain the time increment that indicates the time relative to
the present time when the specified program is to be executed. The time
increment must be specified in the rightmost 3 bytes of R14, unless STATE=1052
when the increment can be specified with the TIMEINC parameter. The
TIMEINC parameter can only be used when STATE=1052.
- R15 must contain a 4-byte action word that will be passed to the called
program. The action word may either be loaded into R15 prior to the
execution of this macro, or may be specified with the PARM parameter.
Return Conditions
- Control is returned to the next sequential instruction (NSI).
- There is an immediate return to the current program following execution of
this macro.
- The contents of R14 and R15 are unknown. The contents of the
remaining operational registers and the condition code are saved during
execution of this macro.
- If the LEVEL or DECB parameter is specified, the ECB data level or DECB
given will be empty on return to the caller and the attached block will no
longer be available for use by the current program.
Programming Considerations
- This macro can be run on any I-stream.
- The ECB reference register (R9) must contain the address of this Entry
Control Block being processed before using the macro.
- An ECB is provided when the new program is activated. The address
of this ECB is not available to the program executing the CRETC macro.
- ECBs created by the CRETC macro use the version of the program most
recently activated. If this program is incompatible with the program
that issued the CRETC call, an interface problem may occur.
- The Action Word specified by the PARM parameter (or, by default, the
contents of R15) will be stored in the first word of the Entry Control Block
(ECB) Work Area One. The address of a working storage block cannot be
passed.
- The program name referenced via prog or PROGRAM parameters must
have been allocated by the system allocator (reference TPF
System Installation Support Reference).
- If STATE=1052 is specified, the program requested will be activated in all
system states, including 1052 state. Otherwise, the request will be
honored only when the system has been cycled above 1052 state.
- The ECB issuing the CRETC macro with the STATE=1052 option may be forced
into an implied WAITC if there is insufficient storage available to buffer the
parameters. When adequate storage is available, the CRETC macro is
executed again and a return is made to the instruction after the macro
expansion.
- The use of the STATE=1052 option should be carefully monitored to prevent
a depletion of storage.
- Using the PROGRAM parameter sacrifices some performance.
Consequently its use should be monitored.
- In addition to the normal macro trace information the macro trace for this
macro contains the name of the program being activated.
- If you use this macro to create an ECB that will enter a dynamic load
module (DLM) with an entry point defined by the C language main
function, the TPF system assumes that any core block attached to data level 0
(D0) contains a command string that will be parsed into argc and
argv parameters for the main function. See TPF Application Programming for more information about
the main function.
- If the location of the data event control block specified by the DECB
parameter does not refer to a valid DECB, control is transferred to the system
error routine and the entry is exited.
Examples
None.