This general macro creates an entry control block (ECB) for
immediate processing by the requested program. The ECB is created in
the same subsystem and subsystem user (SSU) as the parent ECB. When
exiting, the child ECB will notify the parent ECB by posting an event on which
the parent is waiting for completion. Posting the event gives the child
ECB the ability to pass the return code value back to the parent
ECB.
Use the CRESC macro to have the parent create and then wait for
multiple child ECBs to end or time out by coding it multiple times and coding
the WAIT=YES parameter on the last entry. This will result in the
creation of the child ECBs and will place the parent ECB in a wait state until
all child ECBs have been completed or until they time out.
Format
- label
- A symbolic name can be assigned to the macro statement.
- prog
- The name of the program that will be activated with the created
ECB. This is the preferred method for specifying the program
name.
- PROGRAM
- You can also specify the program name with the PROGRAM parameter.
This method has a longer path length than the one described previously.
- prog
- The name of the program that will be activated with the created
ECB.
- preg
- A register (R0-R7) that contains the address of the program
name.
- DATA
- Specify one of the following:
- NONE
- No data will be passed to the new ECB.
- dreg1,dreg2
- A number of bytes of data contained in the register specified with
dreg2 will be copied from the address contained in the register
specified by dreg1 and passed to the child ECB and attached to data
level 0 (D0). A maximum of 4095 bytes of data can be passed.
- IS
- Specifies the I-stream in which the child ECB will run, where:
- MAIN
- The main I-stream.
- MPIF
- The Multi-Processor Interconnect Facility (MPIF) I-stream.
- SAME
- The same I-stream in which the parent is running.
- ireg
- A register (R0-R7) that contains the target I-stream number.
At run time, the register must contain the I-stream number on which the ECB is
to be created. If the register contains zero, load balancing is used
and the ECB is created on the least busy I-stream.
- WAIT
- Specifies one of the following:
- YES
- Create and dispatch the child ECBs and wait for them to be
completed.
- NO
- Do not create the child ECBs; just initialize the ECB create
information for the child ECBs.
- TIMEOUT=treg
- Specifies the value that determines how many seconds the parent ECB waits
for the child ECBs to be completed, where treg is a register that
contains a value from 0-32 767.
This is similar to the timeout value on the EVNTC macro. If you
specify a value of 0, the parent ECB will wait indefinitely until the child
ECBs exit. This value will be in effect in 1052 state.
- RTNLST=lreg
- Specifies a register that will contain the address of an event block
that contains a list of all child ECB return codes on return from the macro,
where lreg is a register from R0-R7. Field EVNBKL1 will
contain the start of the list of all child ECB return codes. The
application must set up the child ECB return codes that are used. See
the EV0BK DSECT for more information about the event block.
Entry Requirements
- R9 must contain the address of the ECB being processed.
- The ECB must be in 31-bit mode.
Return Conditions
- Control is returned to the instruction following the macro
expansion.
- The contents of registers 14 and 15 are unknown. The contents of
all other registers are preserved across this macro call.
Programming Considerations
- This macro can be executed on any I-stream.
- Limit the use of this macro to prevent depletion of storage.
- The application can request that a maximum of 50 child ECBs are created
with this macro. If more than 50 children are requested, a system error
will occur.
- When activated, the specified program receives control in its allocated
addressing mode and any data passed will be contained in data level 0
(D0). The condition code and the contents of registers R0-R7,
R14, and R15 cannot be predicted.
- In addition to the normal macro trace information, the macro trace for
this macro contains the name of the program that will be entered by the new
ECB.
- 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.
Examples
* PARENT PROGRAM
* PARENT INITIALIZES THE ECB CREATE INFORMATION FOR 2 CHILD ECBS.
LA R4,DATA1 FIRST DATA PARM
LA R5,4 INDICATE LENGTH
CRESC QXSA,DATA=(R4,R5),IS=MAIN,WAIT=NO
*
* INDICATE THAT PARENT WILL WAIT 100 SECONDS FOR CHILDREN TO
* COMPLETE AND R3 WILL BE USED AS THE RETURN REGISTER.
* R3 SILL POINT TO THE EV0BK BLOCK UPON RETURN.
*
LA R6,100
CRESC QXSA,DATA=(R4,R5),IS=MAIN,RTNLST=(R3),WAIT=YES,
TIMEOUT=(R6)
*
* CHECK RETURN VALUES
*
EV0BK
USING EV0BK,R3
SR R4,R4 INDEX REG
LA R6,EVNBKLI GET ADDRESS OF FIRST ENTRY
MH R4,EVNBKLS GET SIZE OF ENTRY
AR R6,R4 POINT TO ADDRESS
USING EVNBKLIF,R6
CLI EVNBKLIF,EVNBK_POST POSTED, WITHOUT ERROR?
BNE ERROR NO, ERROR
CLC EVNBKVLS,=F'4' CHECK RETURN VALUE
BNZ ERROR ERROR IF NOT 4
DROP R6
LA R4,1 2ND CHILD
*
* CHECK ERROR BIT IN ENTRY, THEN RETURN VALUE
*
LA R6,EVNBKLI GET ADDRESS OF FIRST ENTRY
MH R4,EVNBKLS GET SIZE OF ENTRY
AR R6,R4 POINT TO ADDRESS
USING EVNBKLIF,R6
CLI EVNBKLIF,EVNBK_POST POSTED WITHOUT ERROR?
BNE ERROR NO, ERROR
CLC EVNBKVLS,=F'4' CHECK RETURN VALUE
BNZ ERROR ERROR IF NOT 4
DROP R6
:
:
* CHILD PROGRAM
* THIS IS HOW THE CHILD ECB EXITS AND RETURNS A VALUE
* TO THE PARENT.
·
·
·
LA R1,4
EXITC RC=R1