creec, __CREEC: Create a new ECB with an attached block

This macro creates an independent ECB for immediate or deferred processing.

The ECB is created in the same subsystem and for the same subsystem user as the creating ECB. Additionally, the ECB is created on the same I-stream as the creating ECB.

A core block is placed on data level zero of the newly created ECB and a variable number of bytes is passed to the created ECB work area starting at EBW000. The core block to be passed is the one specified by the level or decb parameter. The z/TPF system moves the parameters from the area specified by the parm parameter into an interim block of storage. If the priority parameter is CREEC_IMMEDIATE, the block is placed on the ready list. If the priority parameter is CREEC_DEFERRED, the block is placed on the deferred list. Operational program zero (OPZERO) initializes an ECB with the parameters in the work area, releases the interim block, places the passed block (if any) on data level zero, and activates the specified program.

Last updated

  • Changed for PUT14 (information only; no code change).
  • Changed for PUT06.
  • Changed for PUT00.

Format

#include   <tpf/tpfapi.h>
void creec(int length, const void *parm, void (*segname)(),
           enum t_lvl level, int priority);
void __CREEC(int length, const void *parm, const char *segname,
             enum t_lvl level, int priority);

or

#include   <tpf/tpfapi.h>
void creec(int length, const void *parm, void (*segname)(),
           TPF_DECB *decb, int priority);
void __CREEC(int length, const void *parm, const char *segname,
             TPF_DECB *decb, int priority);
length
An integer containing the number of bytes to be passed to the created ECB. A value of zero indicates that no parameters will be passed. A maximum of 104 bytes may be passed.
parm
A pointer of type void to the parameters to be passed.
segname
For creec, a pointer to the external function to be called. For __CREEC, a pointer to the name of the segment to be called. segname must map to an assembler segment name or a C shared object (CSO) name.
Note: C language migration consideration

The creec function only handles #pragma mapped names if the first 4 characters are the same as the program name.

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 CBRW level is the block to be passed to the newly created ECB.
decb
A pointer to a data event control block (DECB). The working storage block on this DECB is the block to be passed to the newly created ECB.
priority
Use defined terms CREEC_DEFERRED to indicate placement on the deferred list and CREEC_IMMEDIATE to indicate placement on the ready list.

Normal return

Void.

Error return

Not applicable.

Programming considerations

  • On return, the working storage block on the referenced ECB data level or DECB is no longer available to the calling program.
  • No linkage is provided between the created ECB and the active ECB calling this macro.
  • The ECB calling creec may be forced into a wait state if there is insufficient storage available to buffer the parameters. When adequate working storage becomes available, the macro is executed and control is returned.
  • The created ECB begins processing on the same I-stream where the create function was called.
  • The use of this macro should be limited to prevent a depletion of storage.
  • A system error with exit occurs if no block is held on the specified ECB data level or DECB, or if more than 104 bytes are passed.
  • If you use this macro to create an ECB that will enter a C shared object (CSO) with an entry point defined by the main function, the z/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 z/TPF Application Programming for more information about the main function.
  • Applications that call this function using DECBs instead of ECB data levels must be compiled with the C++ compiler because this function has been overloaded.
  • This function is implemented in the CTAD library.

Examples

The following example creates an ECB for program OMA0, passing string 755/15AUG and the working storage block on level D0 as input to the program. 
#include <tpf/tpfapi.h>
void OMA0();
char   *parmstring = "755/15AUG";
 :
creec(strlen(parmstring),parmstring,OMA0,D0,CREEC_IMMEDIATE);
The following example creates an ECB for program OMA0, passing string 755/15AUG and the working storage block on the DECB pointed to by decb_ptr as input to the program. 
#include <tpf/tpfapi.h>
void OMA0();
char   *parmstring = "755/15AUG";
TPF_DECB *decb_ptr;
DECBC_RC rc;

decb_ptr = tpf_decb_create( NULL, &rc );
 :
creec(strlen(parmstring),parmstring,OMA0,decb_ptr,CREEC_IMMEDIATE);