CONVERSE (3270 display)

Communicate on a 3270 information display system.

Read syntax diagramSkip visual syntax diagram
CONVERSE (3270 display)

>>-CONVERSE--FROM(data-area)--+-FROMLENGTH(data-value)--+------->
                              '-FROMFLENGTH(data-value)-'   

>--+-INTO(data-area)-+--+-TOLENGTH(data-area)--+---------------->
   '-SET(ptr-ref)----'  '-TOFLENGTH(data-area)-'   

>--+------------------------+--+------------+------------------->
   +-MAXLENGTH(data-value)--+  '-NOTRUNCATE-'   
   '-MAXFLENGTH(data-value)-'                   

>--+-+----------------------+--+---------------------+-+-------->
   | '-ERASE--+-----------+-'  '-CTLCHAR(data-value)-' |   
   |          +-DEFAULT---+                            |   
   |          '-ALTERNATE-'                            |   
   '-+----------+--------------------------------------'   
     '-STRFIELD-'                                          

>--+------------+--+------+------------------------------------><
   '-DEST(name)-'  '-ASIS-'   

Condition: LENGERR

 

Description

CONVERSE communicates on a 3270 information display system.

Options

ASIS
indicates that output is to be sent in transparent mode (with no recognition of control characters and accepting any of the 256 possible combinations of eight bits as valid transmittable data).
Note: If you are using a katakana terminal, you might see some messages containing mixed English and katakana characters. That is because katakana terminals cannot display mixed-case output. Uppercase characters in the data stream appear as uppercase English characters, but lowercase characters appear as katakana characters. If this happens, ask your system programmer to specify MSGCASE=UPPER in the system initialization parameters so that messages contain uppercase characters only.
CTLCHAR(data-value)
specifies a 1-byte write control character (WCC) that controls the CONVERSE command. (The WCC is documented in the IBM 3270 Data Stream Programmer's Reference manual.) A COBOL user must specify a data area containing this character. If the option is omitted, all modified data tags are reset to zero and the keyboard is restored.
DEST(name)
specifies the 4-byte symbolic name of the TCAM destination to which the message is to be sent. This option is meaningful only for terminals defined using DFHTCT TYPE=SDSCI with DEVICE=TCAM.
Note: Start of changeIn CICS® TS 3.1, local TCAM terminals are not supported. The only TCAM terminals supported are remote terminals connected to a pre-CICS TS 3.1 terminal-owning region by the DCB (not ACB) interface of TCAM. End of change

If you use the DEST option, you must be aware of any restrictions placed on device-dependent data streams by the message control facility in use.

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.

FROM(data-area)
specifies the data to be written to the terminal or logical unit, or sent to the partner transaction. This option may, when relevant, be omitted if ATTACHID is specified.
FROMFLENGTH(data-value)
is a fullword alternative to FROMLENGTH.
FROMLENGTH(data-value)
specifies the length, as a halfword binary value, of the data to be written. If you use this option, you must also specify FROM. For a description of a safe upper limit, see LENGTH options in CICS commands.
INTO(data-area)
specifies the receiving field for the data read from the logical unit or terminal.
MAXFLENGTH(data-value)
is a fullword alternative to MAXLENGTH.
MAXLENGTH(data-value)
specifies the maximum amount (halfword binary value) of data that CICS is to recover in response to a CONVERSE command. If INTO is specified, MAXLENGTH overrides the use of TOLENGTH as an input to CICS. If SET is specified, MAXLENGTH provides a way for the program to limit the amount of data it receives at one time.

If the value specified is less than zero, zero is assumed.

If the length of data exceeds the value specified and the NOTRUNCATE option is not present, the data is truncated to that value and the LENGERR condition occurs. The data area specified in the TOLENGTH option is set to the original length of data.

If the length of data exceeds the value specified and the NOTRUNCATE option is present, CICS retains the remaining data and uses it to satisfy subsequent RECEIVE commands. The data area specified in the TOLENGTH option is set to the length of data returned.

If no argument is coded for MAXLENGTH, CICS defaults to TOLENGTH.

NOTRUNCATE
specifies that, when the data available exceeds the length requested, the remaining data is not to be discarded but retained for retrieval by subsequent RECEIVE commands.
SET(ptr-ref)
specifies a pointer reference to be set to the address of data received from the conversation partner in an MRO conversation. The pointer reference, unless changed by other commands or statements, is valid until the next CONVERSE (MRO) command or the end of task.

If DATALOCATION(ANY) is associated with the application program, the address of the data can be above or below the 16MB line.

If DATALOCATION(BELOW) is associated with the application program, and the data resides above the 16MB line, the data is copied below the 16MB line, and the address of this copy is returned.

If TASKDATAKEY(USER) is specified for the running task, and storage protection is active, the data returned is in a user-key. If TASKDATAKEY(CICS) is specified and storage protection is active, the data returned is in a CICS-key.

STRFIELD
specifies that the data area specified in the FROM option contains structured fields. If this option is specified, the contents of all structured fields must be handled by the application program. The CONVERSE command, rather than a SEND command, must be used if the data area contains a read partition structured field. (Structured fields are described in the CICS 3270 Data Stream Device Guide.)

CTLCHAR and ERASE are mutually exclusive with STRFIELD, and their use with STRFIELD generates an error message.

TOFLENGTH(data-area)
is a fullword alternative to TOLENGTH.
TOLENGTH(data-area)
specifies the length, as a halfword binary value, of the data to be received. If you specify INTO, but omit MAXLENGTH, “data-area” specifies the maximum length that the program accepts. If the value is less than zero, zero is assumed.

If the length of the data exceeds the value specified, but NOTRUNCATE is omitted, the data is truncated to that value, and the LENGERR condition occurs. When the data is received, the data area is set to the length of the data.

For a description of a safe upper limit, see LENGTH options in CICS commands.

Conditions

LENGERR
occurs in any of the following situations:
  • Data is discarded by CICS because its length exceeds the maximum that the program accepts and the NOTRUNCATE option is not specified.
  • An out-of-range value is supplied in the FROMLENGTH option.

Default action: terminate the task abnormally.