SEND TEXT


SEND TEXT used to send data to the terminal without any predefined BMS maps. SEND TEXT can do the below things -

  • If the text exceeds a line, SEND TEXT can split it up into multiple lines without splitting words.
  • If the text exceeds a page, SEND TEXT can split into multiple pages that can be according to the terminal size.

SEND TEXT sends text data without mapping. The very first byte of the screen is reserved .The first byte used to place a blank or new line character. The data text starts placing from first row and second column on the screen.

If the data is exceeding a page, then ERASE option needs to be coded along with SEND TEXT to clear the screen before next SEND TEXT. Otherwise, the screen not cleared and the data will be overwritten on the screen which produces unpredictable results.

Single SEND TEXT command can send with up to 4096 bytes data stream in a single execution. If the data stream is greater than 4096 bytes, then multiple SEND TEXT commands required to be coded to pass the data.

Syntax -


SEND TEXT Syntax

Parameters -


FROM(data-area) -

Specifies the data area that is to be send to the screen. FROM needs to be coded always along with SEND TEXT command. Otherwise, EMPTY screen will be displayed.

LENGTH(data-value) -

Specifies the length of the data to be sent to the screen. It should not exceed the length of the FROM data area. The data-value is a halfword binary value (16-bit binary).

CURSOR(data-value) -

Specifies the cursor position on the screen. This is an optional entry in SEND TEXT. data-value must be a halfword binary(16-bit binary) value that specifies the cursor position relative to zero.

data-value values range is depending on the size of the screen used. CURSOR option overrides any IC option of the ATTRB operand of DFHMDF. If ACCUM is being used, the most recent value of CURSOR is used to position the cursor.

The value specified in the CURSOR option must be positive. If a negative value used that leads to unpredictable results.

FORMFEED -

Specifies about the need of the new page while sending the text to screen. This is an optional entry in SEND TEXT. FORMFEED character is positioned at the start of the buffer.

Application program is responsible to ensure this buffer position is not overwritten by text data. FORMFEED is ignored if the target terminal does not support it. The text area can override the FORMFEED indicator.

ERASE -

This is an optional entry in SEND TEXT. Erase option responsible for the below three tasks –

  • Erases the screen buffer or partition before sending the text to the screen.
  • Erases the screen print buffer before sending the text to the screen.
  • Places the cursor to the upper left corner of the screen before sending the text to screen.

The first output operation in any transaction should always have the ERASE option to clear the screen before the text is displayed on the screen.

Otherwise, the new text will be overwritten on the existing screen without clearing it.

In a similar way, first output operation in series of pseudo conversations should have ERASE option coded to clear the screen before output operation performed.

PRINT -

PRINT Specifies the text printing needs to be started at printer. This is an optional entry in SEND TEXT. If the PRINT option is not specified, the data sent to print buffer but not printed.

FREEKB -

Specifies that the keyboard should be unlocked after the data written. This is an optional entry in SEND TEXT. If the FREEKB option not specified, the keyboard remains locked.

ALARM -

Specifies that the 3270 audible alarm feature is to be activated. This is an optional entry in SEND TEXT. ALARM instructs BMS to set the alarm flag in the FMH (Function Management Headers).

DEFAULT -

Sets the terminal to use the DEFAULT screen size.

ALTERNATE -

Sets the terminal to use the ALTERNATE screen size.

NLEOM -

Specifies data for the printer should be built with blanks, new-line characters (NL) and an end-of-message character (EOM) should be placed at the end of the data.

Each NL character causes printing to continue on the next line and the EM character terminates printing. NLEOM 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 is not with blank, new-line character or end-of-message. The NL character occupies a buffer position. The NLEOM option overrides the ALARM option if the latter is present.

SET(ptr-ref) -

Specifies the pointer to be set to the address of the input or output data. The SET option specifies that completed pages are to be returned to the application program.

The pointer is set to the address of completed pages list. The application program regains control immediately after the SEND TEXT command.

If TIOAPFX=YES is specified in map definition, the pointer contains the address of the TIOA prefix and user data starts at offset X'0C' from the start of the TIOA prefix.

REQID(name) -

Specifies a 2-character prefix to be 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 **.

PAGING -

Specifies the output data is not to be sent immediately to the terminal. The output data 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 recoverable temporary storage queues.

TERMINAL -

Specifies the output data is to be sent to the terminal that originated the transaction.

WAIT -

Specifies the 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 causes the application program to wait until the previous command has been completed.

LAST -

Specifies this is the last output operation for a transaction. This option applies to logical units only.

HEADER(data-area) -

Specifies the header data to be placed at the beginning of each page of text data.

TRAILER(data-area) -

Specifies the text data area that contains trailer data to be placed at the bottom of each output page.

ACCUM -

Used to build a logical message. The logical message is completed by a SEND PAGE command or deleted by a PURGE MESSAGE command.

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.

Error Conditions -


Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.

Error ConditionRESP2, Description & SolutionSystem Action
39 IGREQID
Occurs if the prefix specified in the REQID option is different from that established by a previous REQID option.
Solution -Debug the application program and find the previous REQID. Make sure the REQID should be same as previous REQID.
Task abnormally terminated
16 INVREQ
RESP2 not set
  • The length of a header on a SEND TEXT command is negative.
    Solution -Modify the application program to make sure the length of header having a positive value that is greater than zero.
  • The length of a trailer on a SEND TEXT command is negative.
    Solution -Modify the application program to make sure the length of trailer having a positive value that is greater than zero.
Task abnormally terminated
22 LENGERR
Occurs if an out-of-range value is supplied in the LENGTH option.
Solution -Modify the application program to make sure the length value within the bounds.
Task abnormally terminated
32 RETPAGE
Occurs if the SET option is specified and a completed page is ready for return to the application program.
Solution -Modify the application program not to complete the page before SEND TEXT when SET option is specified.
Return control to the application program at the point immediately after the BMS SEND TEXT command.
35 TSIOERR
Occurs if there is an irrecoverable temporary storage input/output error.
Solution -Nothing required from application programmer end. Inform the error to storage support team and try after some time.
Task abnormally terminated