FEPI CONVERSE FORMATTED

Function

The command is for SLU2 mode only.

FEPI CONVERSE FORMATTED sends application data to and receives a reply from a target. The data supplied by the application must be formatted data, as key strokes (with a final attention character) or a screen image; the data received into the application’s data area is a screen image. Full details about the data are given in Data formats.

The conversation with the target can be one of two types:

Previously allocated
The conversation is specified by the CONVID option; it must be one that uses formatted data. The command completes when ‘last in chain’, ‘end bracket’, or ‘change direction’ is received.
Temporary
The conversation is allocated from the pool specified by the POOL option and exists only for the duration of the command. The pool must be one that uses formatted data. In addition, the data must be sent in key stroke format.

The command first waits for a suitable session to become available (if there is not already one); it does not complete until ‘end bracket’ or ‘change direction’ is indicated.

A time limit can be set for this command. For more details of ending conditions, see Ending status.

Syntax

The syntax for each type of conversation is shown separately.

Previously allocated conversation

Read syntax diagramSkip visual syntax diagramFEPI CONVERSE FORMATTED
 
>>-FEPI CONVERSE FORMATTED--CONVID(data-value)------------------>
 
>--FROM(data-value)--+-------------------------+---------------->
                     '-FROMFLENGTH(data-value)-'
 
>--+-AID(data-value)--+------------------------+-+-------------->
   |                  '-FROMCURSOR(data-value)-' |
   '-KEYSTROKES--+--------------------+----------'
                 '-ESCAPE(data-value)-'
 
>--+----------------------------------+------------------------->
   '-INTO(data-area)-| INTO options |-'
 
>--+-------------------+--+--------------------+---------------->
   '-ALARMSTATUS(cvda)-'  '-COLUMNS(data-area)-'
 
>--+-----------------+--+-------------------+------------------->
   '-ENDSTATUS(cvda)-'  '-FIELDS(data-area)-'
 
>--+------------------+--+------------------+------------------->
   '-LINES(data-area)-'  '-RESPSTATUS(cvda)-'
 
>--+---------------------+--+---------------------+------------><
   '-TIMEOUT(data-value)-'  '-TOCURSOR(data-area)-'
 
INTO options:
 
|--+------------------------+--+----------------------+---------|
   '-MAXFLENGTH(data-value)-'  '-TOFLENGTH(data-area)-'
 

Temporary conversation

Read syntax diagramSkip visual syntax diagramFEPI CONVERSE FORMATTED
 
>>-FEPI CONVERSE FORMATTED--POOL(data-value)-------------------->
 
>--+--------------------+--FROM(data-value)--------------------->
   '-TARGET(data-value)-'
 
>--+-------------------------+--KEYSTROKES---------------------->
   '-FROMFLENGTH(data-value)-'
 
>--+--------------------+--------------------------------------->
   '-ESCAPE(data-value)-'
 
>--+----------------------------------+------------------------->
   '-INTO(data-area)-| INTO options |-'
 
>--+-------------------+--+--------------------+---------------->
   '-ALARMSTATUS(cvda)-'  '-COLUMNS(data-area)-'
 
>--+-----------------+--+-------------------+------------------->
   '-ENDSTATUS(cvda)-'  '-FIELDS(data-area)-'
 
>--+------------------+--+------------------+------------------->
   '-LINES(data-area)-'  '-RESPSTATUS(cvda)-'
 
>--+---------------------+--+---------------------+------------><
   '-TIMEOUT(data-value)-'  '-TOCURSOR(data-area)-'
 
INTO options:
 
|--+------------------------+--+----------------------+---------|
   '-MAXFLENGTH(data-value)-'  '-TOFLENGTH(data-area)-'
 

Options

AID(1-character data-value)
specifies the attention identifier value to send with the data. Specifying AID also indicates that the data to send is in screen-image format, as described in Data formats. The value must not be null (X'00'). AID, and therefore screen-image format data, is not allowed if POOL is specified.

Symbolic names for the AID values are available for the supported languages in the language-specific DFHAID copybooks.

ALARMSTATUS(cvda)
returns a value that indicates whether the received data sounded the alarm. The relevant CVDA values are:
  • ALARM
  • NOALARM
COLUMNS(fullword binary data-area)
returns the number of columns in the screen image.
CONVID(8-character data-value)
specifies the ID of the conversation to use. The conversation must be owned by the task issuing the command.
ENDSTATUS(cvda)
returns a value that indicates the ending status for the received data. The relevant CVDA values are:
Value
Meaning
CD
‘Change direction’ received.
EB
‘End bracket’ received.
LIC
‘Last in chain’ received.
For more details of ending status and how additional data is handled, see Ending status.
ESCAPE(1-character data-value)
for send data in key stroke format, specifies the escape character used to indicate character combinations representing special keys. You can use any value in the range X'40' through X'FE'. The default escape character is & (X'50').
FIELDS(fullword binary data-area)
returns the number of fields in the screen image.
FROM(data-value)
specifies the data to send to the back-end application. Its length is specified by the FROMFLENGTH option. For send data in screen-image format, if the length is more than the screen image, the additional data is ignored; if it is less, the data is the first part of the screen image, and the last part of the screen image is not changed.
FROMCURSOR(fullword binary data-value)
for send data in screen-image format, specifies the position of the cursor, expressed as an offset from the start of the screen image; offset zero is the top left-hand corner of the screen. If FROMCURSOR is not specified, the cursor remains where it was positioned by the last inbound data.
FROMFLENGTH(fullword binary data-value)
specifies the length of the data to send; that is, the length of the data area identified by the FROM option. It must not be zero or more than the maximum length allowed for the pool.
INTO(data-area)
specifies the data area in which the received data is to be returned. The length of the area is specified by the MAXFLENGTH option, and the actual length of data written into the area is returned by the TOFLENGTH option.
KEYSTROKES
specifies that the data to send is a sequence of key strokes (see Data formats).
LINES(fullword binary data-area)
returns the number of lines in the screen image.
MAXFLENGTH(fullword binary data-value)
specifies the maximum amount of data that can be returned; that is, the length of the data area identified by the INTO option. It must not be more than the maximum length allowed for the pool.
POOL(8-character data-value)
specifies the name of the pool containing the target for the conversation. Specifying POOL means that the conversation is a temporary one, that exists only for the duration of the FEPI CONVERSE. You must also specify the KEYSTROKES option. If the length of the data area identified by the INTO option is less than the size of the screen image, the additional data is discarded.
RESPSTATUS(cvda)
returns a value that indicates the type of response that is required at the back-end system. The relevant CVDA values are:
Value
Meaning
DEFRESP1
Definite response 1 required.
DEFRESP2
Definite response 2 required.
DEFRESP3
Definite response 1 and definite response 2 required.
NONE
No response required.
TARGET(8-character data-value)
specifies the name of the target. TARGET can be omitted if there is only one target in the pool or if all targets are suitable for the desired conversation.
TIMEOUT(fullword binary data-value)
specifies the maximum time in seconds that the command is to wait for the requested data to begin to arrive. If TIMEOUT is not specified or the specified time is zero, the command is not timed out.
TOCURSOR(fullword binary data-area)
returns the position of the cursor in the received screen image, expressed as an offset from the start of the screen image; offset zero is the top left-hand corner of the screen.
TOFLENGTH(fullword binary data-area)
returns the actual length of data received in the data area identified by the INTO option.
Note:
On a FEPI CONVERSE FORMATTED command, if MAXFLENGTH is less than the presentation space size, TOFLENGTH returns the value defined in MAXFLENGTH. If MAXFLENGTH is greater than the presentation space size, TOFLENGTH returns the presentation space size.

Conditions

The INVREQ condition can have the following RESP2 values:

RESP2
Meaning
30
Pool name unknown.
31
Pool name out of service.
32
TARGET name unknown.
33
TARGET name out of service.
34
TARGET name required but not specified.
35
POOL name is unsuitable for temporary conversations. It has CONTENTION(LOSE) or it has INITIALDATA(INBOUND) and no begin-session handler.
36
No suitable session available and in service.
40
FROMLENGTH value negative, zero, or more than the maximum allowed for the current pool.
41
ESCAPE value not valid.
50
Inbound data with ‘begin bracket’ to be received.
51
AID value not valid.
52
Cursor position not valid.
53
Character values in send data not valid.
54
Attribute positions or values in send data not valid.
55
Key stroke escape sequence in send data is not valid.
56
Field validation (mandatory fill, mandatory enter, trigger) failed.
57
Input inhibited.
58
VTAM SEND failed.
59
DBCS data rules violated.
60
MAXFLENGTH value negative, zero, or more than the maximum allowed for the current pool.
71
VTAM RECEIVE failed.
72
RECEIVE FORMATTED processing found invalid, or unexpected data while interpreting the 3270 data stream for a WRITE, ERASE/WRITE ALTERNATE, or WRITE STRUCTURED FIELD command code.
210
Command not allowed for SLU P mode.
212
Conversation has wrong data format.
213
Command timed out.
215
Session lost.
216
Error occurred on previous FEPI SEND.
220
FEPI CONVERSE not allowed at this point in the conversation.
221
Data cannot be received because no AID or final attention key stroke specified.
224
Only FEPI ISSUE or FEPI FREE commands allowed at this point in the conversation.
230
SNA CLEAR command received.2
231
SNA CANCEL command received.2
232
SNA CHASE command received.2
233
Exception response received.
234
Exception request received.
240
Conversation ID not owned by this task.
241
TIMEOUT value negative or not valid.
[[ Contents Previous Page | Next Page Index ]]