Retrieve values from APPC conversation attach header.

EXTRACT PROCESS (APPC)
>>-EXTRACT PROCESS---------------------------------------------->
>--+------------------------------------------------------------------------+-->
'-PROCNAME(data-area)--PROCLENGTH(data-area)--+------------------------+-'
'-MAXPROCLEN(data-value)-'
>--+--------------+--+----------------------+------------------->
'-CONVID(name)-' '-SYNCLEVEL(data-area)-'
>--+----------------------------------------+------------------><
'-PIPLIST(ptr-ref)--PIPLENGTH(data-area)-'
Conditions: INVREQ, LENGERR, NOTALLOC
Description
EXTRACT PROCESS lets an application
program access conversation-related data, specified to CICS® when the program
is attached. The attach receiver does not have to execute an EXTRACT PROCESS
command unless it requires this information.
The EXTRACT PROCESS command
is valid only on an APPC conversation that is the principal facility for the
task.
Options
- CONVID(name)
- identifies
the conversation to which the command relates. The 4-character name identifies
the token representing the principal session (EIBTRMID).
For compatibility
with earlier releases, SESSION is accepted as a synonym for CONVID. New programs
should use CONVID.
If CONVID and SESSION are both omitted, the principal
facility for the task is used by default.
- MAXPROCLEN(data-value)
- specifies
the buffer length of PROCNAME. If MAXPROCLEN is not specified, the buffer
is assumed to have 32 bytes.
- PIPLENGTH(data-area)
- specifies
a halfword binary data area in which the total length of the process initialization
parameter (PIP) list is returned.
- PIPLIST(ptr-ref)
- specifies
a pointer reference that is set to the address of a CICS-provided data area
containing a PIP list. This list contains variable-length records in the same
format as the list in the CONNECT PROCESS command. A returned value of zero
means that no PIP data has been received by CICS.
- PROCLENGTH(data-area)
- specifies
a halfword data area that is set by CICS to the length of the process name.
If PROCNAME is specified, this option must be specified.
- PROCNAME(data-area)
- specifies
the data area to receive the process name specified by the remote system that
caused the task to start. The data area can be 1–64 bytes long. The process
name is padded on the right with blanks if it is too short. The PROCNAME data
area should not be shorter than the MAXPROCLEN value.
- SYNCLEVEL(data-area)
- specifies
a halfword data area that is set by CICS to the SYNCLEVEL value. For further
information about synchronization levels, see the CICS Intercommunication Guide.
Conditions
- INVREQ
- RESP2
values:
- 200
- A distributed program link server application specified the function-shipping
session (its principal facility) on the CONVID option.
also occurs (RESP2 not set) in any of the following situations:
- EXTRACT PROCESS has been used on a conversation other than APPC mapped
(for example, LUTYPE6.1, APPC basic, or CPI Communications).
- EXTRACT PROCESS has been used on a conversation that was not started by
input from the network, and whose session is not a principal facility.
- The command is issued against a CPI-Communications conversation.
Default action: terminate the task abnormally.
- LENGERR
- occurs
if the actual length of PROCNAME is greater than MAXPROCLEN, or greater than
32 bytes if MAXPROCLEN is not specified.
Default action: terminate the
task abnormally.
- NOTALLOC
- occurs
if the specified CONVID value specified does not relate to a conversation
owned by the application.
Default action: terminate the task abnormally.