gtpc2m17C/C++ Language Support User's Guide

cretc_level, __CRETCL-Create a Time-Initiated Entry

This macro creates an independent entry control block (ECB) after a specified amount of time has elapsed. A 4-byte parameter is placed in EBW000-EBW003 of the newly created ECB. A working storage block from an ECB data level or data event control block (DECB) is passed to the created ECB.

Format

#include   <tpfapi.h>
void       cretc_level(int flags, void (*segname)(), int units,
                       const void *action, enum t_lvl level);
void       __CRETCL(int flags, const char *segname, int units,
                    const void *action, enum t_lvl level);

or

 #include   <tpfapi.h>
 void       cretc_level(int flags, void (*segname)(), int units,
                        const void *action, TPF_DECB *decb);
 void       __CRETCL(int flags, const char *segname, int units,
                     const void *action, TPF_DECB *decb);         

flags
Logical or (|) of the following bit flags that are defined in tpfapi.h:

CRETC_SECONDS or CRETC_MINUTES
Use CRETC_SECONDS or CRETC_MINUTES to indicate whether the units parameter is expressed in seconds or minutes. Code only one of these options.

CRETC_1052
This optional parameter permits the program specified by seg_name to be activated at the time requested, even when the system is in 1052 state. If CRETC_1052 is not specified, the program cannot be activated until the system is cycled above 1052 state.

segname
For cretc_level, a pointer to the external function to be called. For __CRETCL, a pointer to the name of the segment to be called. segname must map to an assembler segment name, a TARGET(TPF) segment name (or transfer vector), or a TPF ISO-C dynamic link module (DLM) name.
Migration to ISO-C consideration

The TARGET(TPF) cretc_level function can handle segment names that are #pragma mapped. The ISO-C cretc_level function only handles #pragma mapped names if the first 4 characters are the same as the program name.

TARGET(TPF) restriction

Only calls to certain TPF API functions permit the use of function pointers. Pointers to functions are not supported in TARGET(TPF); their use normally results in a compiler error.

units
An integer value defining the time increment in minutes or seconds that will elapse before activating the ECB.
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 units 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.

action
Treated as a pointer to type void, the first 4 bytes of which are passed to the created ECB as an action word in EBW000-003.

level
One of 16 possible values representing a valid data level from the enumeration type t_lvl, expressed as Dx, where x represents the hexadecimal number of the level (0-F). The working storage block on this core block reference word (CBRW) level is the block to be passed to the newly created ECB on data level 0.

decb
A pointer to a DECB. The working storage block on this DECB is the block to be passed to the newly created ECB on data level 0.

Normal Return

Void.

Error Return

Not applicable.

Programming Considerations

Examples

The following example creates a new ECB for program QZZ0 after 5 seconds have elapsed. The 4-byte character string, INIT, is placed in EBW000-003 of the new ECB, and data level D2 refers to a core block to be passed to the ECB when it is dispatched.

#include <tpfapi.h>
void QZZ0();

  ·
  ·
  ·
cretc_level(CRETC_SECONDS,QZZ0,5,"INIT", D2);

The following example creates a new ECB for program QZZ0 after 5 seconds have elapsed. The 4-byte character string, INIT, is placed in EBW000-003 of the new ECB, and the core block on the DECB pointed to by decb_ptr is passed to the ECB when it is dispatched.

#include <tpfapi.h>
void QZZ0();
 
TPF_DECB *decb_ptr;
DECBC_RC rc;
 
decb_ptr = tpf_decb_create( NULL, &rc );

  ·
  ·
  ·
cretc_level(CRETC_SECONDS,QZZ0,5,"INIT",decb_ptr);

Related Information

For more information about DECBs, see TPF Application Programming.