SEND TEXT
Send data without mapping. The keywords are separated into those supported by standard and full BMS. For further information about BMS, see Basic mapping support.
Conditions: IGREQCD, IGREQID, INVLDC, INVPARTN, INVREQ, LENGERR, RETPAGE, TSIOERR, WRBRK
Description
SEND TEXT sends text data without mapping. The text is split into lines of the same width as the terminal, such that words are not broken across line boundaries. If the text exceeds a page, it is split into pages that fit on the terminal with application-defined headers and trailers.
When using the SEND TEXT command with any of the ALARM, FREEKB, FRSET, HONEOM, L40, L64, L80, or PRINT options, see DFHMDI options, CTRL for a description of the option priority.
Options
- ACCUM
- specifies
that this command is one of a number of commands that are used to
build a logical message. The logical message is completed by a SEND
PAGE command, or deleted by a PURGE MESSAGE command.
HEADER, JUSFIRST, JUSLAST, JUSTIFY and TRAILER all imply ACCUM.
- ACTPARTN(name)
- specifies
the name (1–2 characters) of the partition to be activated.
Activating a partition moves the cursor into the specified partition,
and unlocks the keyboard for the specified partition.
This option is ignored if the target terminal does not support partitions, or if there is no application partition set.
- ALARM
- specifies that the 3270 audible alarm feature is to be activated. For logical units supporting FMHs (except interactive and batch logical units), ALARM instructs BMS to set the alarm flag in the FMH.
- ALTERNATE
- sets the terminal to use the ALTERNATE screen size.
- CURSOR(data-value)
- specifies
the location to which the 3270 or 3604 cursor is to be returned on
completion of a SEND TEXT command.
The data value must be a halfword binary value that specifies the cursor position relative to zero; the range of values that can be specified depends on the size of the screen being used.
This option overrides any IC option of the ATTRB operand of DFHMDF. If ACCUM is being used, the most recent value of CURSOR specified is used to position the cursor.
The value specified in the CURSOR option must be positive. A negative value leads to unpredictable results.
- DEFAULT
- sets the terminal to use the DEFAULT screen size.
- ERASE
- specifies
that the screen printer buffer or partition is to be erased and the
cursor returned to the upper left corner of the screen. (This option
applies only to the 3270, or 8775, and to the 3604 Keyboard Display.)
The first output operation in any transaction, or in a series of pseudoconversational transactions, should always specify ERASE. For transactions attached to 3270 screens or printers, unless explicitly overridden by the DEFAULT or ALTERNATE option, this also ensures that the correct screen size is selected, as defined for the transaction by the SCRNSIZE option in the RDO PROFILE definition.
- FMHPARM(name)
- specifies the name (1–8 characters) of the outboard map to be used. (This option applies only to 3650 logical units with outboard formatting.)
- FORMFEED
- specifies
that a new page is required. For 3270 printers and displays, the FORMFEED
character is positioned at the start of the buffer. The application
program must thus ensure that this buffer position is not overwritten
by map or text data. It is ignored if the target terminal does not
support FORMFEED (that is, the RDO TYPETERM option FORMFEED was not
used).
The FORMFEED option can appear on any SEND TEXT ACCUM command. You need only specify it once within a physical page because it always forces a FORMFEED at the start of the physical page. To force a FORMFEED at the start of a particular SEND TEXT ACCUM command, use the JUSFIRST option instead.
- FREEKB
- specifies
that the 3270 keyboard should be unlocked after the data is written.
If FREEKB is omitted, the keyboard remains locked.
When using the FREEKB option, see DFHMDI options, CTRL for a description of the option priority.
Note that the keyboard lock status is maintained separately for each partition on a terminal that supports partitions.
- FROM(data-area)
- specifies the data area containing the data to be sent.
- HEADER(data-area)
- specifies
the header data to be placed at the beginning of each page of text
data. The format of the header is:
- 2 bytes
- Binary length of the data (n).
- 1 byte
- Page numbering required or not (blank).
- 1 byte
- Reserved field.
- n bytes
- Data.
See Header and trailer format for more information.
- HONEOM
- specifies
that the default printer line length is to be used. This length should
be the same as that specified using the RDO TYPETERM options PAGESIZE
or ALTPAGE, and the same as the printer platen width; otherwise the
data may not format correctly.
When using the HONEOM option, see DFHMDI options, CTRL for a description of the option priority.
- JUSFIRST
- specifies that the text data is to be placed at the top of the page. Any partially formatted page from previous requests is considered to be complete. If the HEADER option is specified, the header precedes the data. See also the description of the JUSTIFY option.
- JUSLAST
- specifies that the text data is to be positioned at the bottom of the page. The page is considered to be complete after the request has been processed. If the TRAILER option is specified, the trailer follows the data. See also the description of the JUSTIFY option.
- JUSTIFY(data-value)
- specifies the line of the page at which the text data is to be positioned. The data value must be a halfword binary value in the range 1 through 240. Although they may not be specified as constants, the special values -1 and -2 can be supplied dynamically to signify JUSFIRST or JUSLAST, respectively.
- LAST
- specifies that this is the last output operation for a transaction and, therefore, the end of a bracket. This option applies to logical units only.
- LDC(name)
- specifies
a 2-character mnemonic to be used to determine the logical device
code (LDC) to be transmitted in the FMH to the logical unit. The mnemonic
identifies an LDC entry defined by a DFHTCT TYPE=LDC macro.
When an LDC is specified, BMS uses the device type, the page size, and the page status associated with the LDC mnemonic to format the message. These values are taken from the extended local LDC table for the logical unit, if it has one. If the logical unit has only a local (unextended) LDC table, the values are taken from the system LDC table. The numeric value of the LDC is obtained from the local LDC table, unless this is an unextended table and the value is not specified, in which case it is taken from the system table.
- LENGTH(data-value)
- specifies the length of the data to be sent as a halfword binary value. For a description of a safe upper limit, see LENGTH options in CICS commands.
- L40, L64, or L80
- specifies
the line length for a 3270 printer; a carrier return and line feed
are forced after 40, 64, or 80 characters have been printed on a line.
Unacceptable results are likely if this differs from the page width
specified by the RDO TYPETERM options PAGESIZE or ALTPAGE.
When using the options, see DFHMDI options, CTRL for a description of the option priority.
- MSR(data-value)
- specifies the 4-byte data value that controls the 10/63 magnetic stripe reader attached to an 8775 or 3643 terminal. A set of constants is provided in DFHMSRCA to assist in setting this 4-byte area. See Magnetic slot reader (MSR) control value constants, DFHMSRCA for a complete list. This option is ignored if the RDO TYPETERM option MSRCONTROL was not used.
- NLEOM
- specifies
that data for a 3270 printer or a 3275 display with the printer adapter
feature should be built with blanks and new-line (NL) characters,
and that an end-of-message (EM) character should be placed at the
end of the data. As the data is printed, each NL character causes
printing to continue on the next line, and the EM character terminates
printing.
This option must be specified in the first SEND TEXT command used to build a logical message. The option is ignored if the device receiving the message (direct or routed) is not one of those mentioned above.
If this option is used, buffer updating and attribute modification of fields previously written into the buffer are not allowed. CICS includes the ERASE option with every write to the terminal.
The NL character occupies a buffer position. A number of buffer positions, equivalent to the value of the RDO TYPETERM options PAGESIZE or ALTPAGE for that terminal, is unavailable for data. This may cause data to wrap around in the buffer; if this occurs, the PGESIZE value must be reduced.
The NLEOM option overrides the ALARM option if the latter is present.
- OUTPARTN(name)
- specifies the name (1–2 characters) of the partition to which data is to be sent. This option is ignored if the terminal does not support partitions, or if there is no application partition set associated with the terminal. If there is an application partition set, and the OUTPARTN option is omitted, data is sent to the partition named by the PARTN operand of the DFHMSD or DFHMDI map definition. If maps are not used, or if there is no PARTN operand, the output is sent to the first partition in the partition set.
- PAGING
- specifies
that the output data is not to be sent immediately to the terminal,
but is to be placed in temporary storage and displayed in response
to paging commands entered by the terminal operator.
If PAGING is specified with a REQID prefix that is used for temporary storage queues that are defined as recoverable, CICS provides message recovery for logical messages if the task has reached a syncpoint.
- specifies
that a print operation is to be started at a 3270 printer or at a
3275 with the printer adapter feature, or that data on an LUTYPE2
(3274/76 or 3790) is to be printed on a printer allocated by the controller.
If this option is omitted, the data is sent to the printer buffer
but is not printed.
When using the PRINT option, see DFHMDI options, CTRL for a description of the option priority.
- REQID(name)
- specifies
a 2-character prefix to be used as part of a temporary storage identifier
for CICS message recovery.
Only one prefix can be specified for each logical message. The default
prefix is **.
BMS message recovery is provided for a logical message only if the PAGING option is specified in the BMS SEND commands and if the syncpoint has been reached.
- SET(ptr-ref)
- specifies
the pointer to be set to the address of the data. It specifies that
completed pages are to be returned to the application program. The
pointer is set to the address of a list of completed pages.
The application program regains control either immediately following the BMS SEND command (if the current page is not yet completed), or at the label specified in a HANDLE CONDITION RETPAGE command if the page has been completed.
If TIOAPFX=YES is specified in the map definition, the pointer returned contains the address of the TIOA prefix. The user data starts at offset X'0C' from the start of the TIOA prefix.
- TERMINAL
- specifies that data is to be sent to the terminal that originated the transaction.
- TRAILER(data-area)
- specifies
the text data area that contains trailer data to be placed at the
bottom of each output page. The format of the trailer is:
- 2 bytes
- Binary length of the data (n)
- 1 byte
- Page numbering required or not (blank)
- 1 byte
- Reserved field
- n bytes
- Data
See the Header and trailer format for more information.
- WAIT
- specifies
that control should not be returned to the application program until
the output operation has been completed.
If WAIT is not specified, control returns to the application program when the output operation has started. A subsequent input or output command (terminal control, BMS, or batch data interchange) causes the application program to wait until the previous command has been completed.
Conditions
- 57 IGREQCD
- occurs
when an attempt is made to execute a SEND TEXT command after a SIGNAL
data-flow control command with a request change direction (RCD) code
has been received from an LUTYPE4 logical unit.
Default action: terminate the task abnormally.
- 39 IGREQID
- occurs
if the prefix specified in the REQID option on a BMS SEND command
is different from that established by a previous REQID option, or
by default for this logical message—REQID (**).
Default action: terminate the task abnormally.
- 41 INVLDC
- occurs
if the specified LDC mnemonic is not included in the LDC list for
the logical unit.
Default action: terminate the task abnormally.
- 65 INVPARTN
- occurs
if the specified partition is not defined in the partition set associated
with the application program.
Default action: terminate the task abnormally.
- 16 INVREQ
- RESP2
values:
- 200
- Command not allowed for a distributed program link server program.
also occurs (RESP2 not set) in any of the following situations:- Text data is output to the same partition or LDC as mapped data while a BMS logical message is active. If neither partitions nor LDCs are in use, text data is output to the same logical message as mapped data.
- During overflow processing, data is sent to a different LDC from the LDC that caused page overflow.
- The length of a header on a SEND TEXT command is negative.
- The length of a trailer on a SEND TEXT command is negative.
Default action: terminate the task abnormally.
- 22 LENGERR
- occurs
if an out-of-range value is supplied in the LENGTH option.
Default action: terminate the task abnormally.
- 32 RETPAGE
- occurs
if the SET option is specified and a completed page is ready for return
to the application program.
Default action: return control to the application program at the point immediately following the BMS SEND TEXT command.
- 35 TSIOERR
- occurs
if there is an irrecoverable temporary storage input/output error.
Default action: terminate the task abnormally.
- 03 WRBRK
- occurs
if a SEND command is interrupted by the terminal operator pressing
the ATTN key. It applies only to the 2741 Communication Terminal,
and only if write break is supported for CICS.
Default action: ignore the condition.