Default action: Terminate the task abnormally.
SYSIDERR
occurs if the SYSID option specifies either a name that is not defined in the terminal control system table (TCS), or a system to which the link is closed.
Default action: Terminate the task abnormally.
Examples
The following example shows how to write a record to a temporary storage queue in auxiliary storage:
EXEC CICS WRITEQ TS
QUEUE(UNIQNAME)
FROM(MESSAGE)
LENGTH(LENGTH)
The following example shows how to update a record in a temporary storage queue in main storage:
EXEC CICS WRITEQ TS
QUEUE(’TEMPQ1’)
FROM(DATAFLD)
LENGTH(40)
ITEM(ITEMFLD)
REWRITE
XCTL
(
Transfer control from one application program to another.
name
)
COMMAREA (
data-area
)
LENGTH (
data-value
)
INPUTMSG (
data-area
)
INPUTMSGLEN (
data-value
)
Conditions:
INVREQ, LENGERR, NOTAUTH, PGMIDERR
Description
XCTL transfers control from one application program to another at the same logical level.
See Chapter 20, “Program control,” on page 199 for more information.
Options
COMMAREA(
data-area
)
specifies a communication area that is to be made available to the invoked
474
CICS for iSeries Application Programming Guide V5
program. In this option, a pointer to the data area is passed. In an invoked
COBOL program, you must give this data area the name DFHCOMMAREA.
(See “COMMAREA in EXEC CICS LINK and EXEC CICS XCTL commands”
on page 70 and “Passing data to other programs” on page 201.) In a C
receiving program, this data area must be referenced by an EXEC CICS
ADDRESS COMMAREA command.
INPUTMSG(
data-area
)
specifies data to be passed to the invoked program when it first issues an
EXEC CICS RECEIVE command.
This data remains available until the execution of an EXEC CICS RECEIVE or
EXEC CICS RETURN command. An invoked program can invoke a further program and so on, creating a chain of linked programs. If a linked-to chain exists, CICS supplies the INPUTMSG data to the first EXEC CICS RECEIVE command executed in the chain.
See Chapter 20, “Program control,” on page 199 for more information about
using the INPUTMSG option.
INPUTMSGLEN(
data-value
)
specifies as a halfword binary value the length of the INPUTMSG data. If the value is negative, zero is assumed.
LENGTH(
data-value
)
specifies as a halfword binary value the length in bytes of the communication area. If a negative value is supplied, zero is assumed. For a description of a
safe upper limit, see “LENGTH options” on page 312.
PROGRAM(
name
)
specifies the identifier of the program to which control is to be passed unconditionally. The name must be alphanumeric, up to 8 characters long, and must have been defined in the processing program table (PPT) as a local program.
Exception Conditions
INVREQ
RESP2 values:
8
The INPUTMSG option is supplied for a program that is not associated with a terminal, or that is associated with an APPC logical unit.
200
v
The INPUTMSG option is supplied in a program invoked by DPL.
The INPUTMSG option is supplied with a null address.
Default action: Terminate the task abnormally.
LENGERR
RESP2 values: v v
11
The length specified in the LENGTH option is greater than the length of the data area specified in the COMMAREA option, and while that data was being copied a destructive overlap occurred because of the incorrect length.
The INPUTMSGLEN value is outside the range 1 through 32 767.
A negative LENGTH value is supplied.
Default action: Terminate the task abnormally.
Chapter 32. Application programming commands - reference
475
NOTAUTH
occurs if a resource security check has failed on PROGRAM(name).
Default action: Terminate the task abnormally.
PGMIDERR
RESP2 values:
1
2
A program does not have an installed resource definition.
The program is disabled.
3
9
The program cannot be loaded.
The program is defined as remote.
Default action: Terminate the task abnormally.
Examples
The following example shows how to request a transfer of control to an application program called PROG2:
476
CICS for iSeries Application Programming Guide V5
