gtpc2mai | C/C++ Language Support User's Guide |
This function sends data to the remote transaction program. The data
sent consists of logical records.
Format
#include <tppc.h>
void tppc_send_data(unsigned int *resid,
struct tppc_return_codes *rcode,
enum t_rtsrcvd *rtsrcvd,
unsigned char *data,
unsigned short int *length);
- resid
- This is a pointer to a 4-byte field that contains the resource ID.
This resource ID must be the ID assigned on the initial ALLOCATE for this
conversation or one that was assigned by an incoming ATTACH.
- rcode
- This is a pointer to the structure tppc_return_codes, defined
in tppc.h, where the return code is to be placed.
- rtsrcvd
- This is a pointer to a 1-byte field that contains the enumeration type
t_rtsrcvd, where the REQUEST_TO_SEND_RECEIVED indication is
placed. The REQUEST_TO_SEND_RECEIVED indication is:
- RTSRCVD_YES
- This value indicates that a REQUEST_TO_SEND indication was received from
the remote transaction program. The remote program called
tppc_request_to_send, requesting the local TPF transaction program
to enter receive state and placing the remote transaction program
in send state.
Any other value indicates that a REQUEST_TO_SEND notification was not
received.
- data
- This is a pointer to the location in memory that contains the data to be
sent.5
- length
- This is a pointer to a 2-byte field that contains the length of data to be
sent. The value can be from 0-32 767. The value
can also be a NULL pointer, but only if data is also NULL.5
The data length is not related in any way to the length of the logical
record. It is used only to determine the length of the data located at
the address specified by the data parameter.
- Note:
- If data and length are NULL, the data is assumed to be on
the data level 0 in AM0SG format. See the programming considerations
for an explanation of the record format.
Return Codes
The following table contains a list of the primary and secondary return
codes that can be returned to the program that called the
tppc_send_data function. A complete list of the return codes
and their definitions can be found in Table 37 and Table 38.
Symbolic Name
| Primary Code
| Secondary Code
|
LU62RC_OK
| 0000
|
|
LU62RC_PARAMETER_CHECK
| 0001
|
|
LU62RC_PK_BAD_TCBID
| ....
| 00000001
|
LU62RC_PK_BAD_CONVID
| ....
| 00000002
|
LU62RC_INVALID_LENGTH
| ....
| 00000006
|
LU62RC_PKSENDD_BADLL
| ....
| 000000F1
|
LU62RC_STATE_CHECK
| 0002
|
|
LU62RC_SKSENDD_BADSTATE
| ....
| 000000F2
|
LU62RC_ALLOC_ERROR
| 0003
|
|
LU62RC_SECURITY_NOT_VALID
| ....
| 080F6051
|
LU62RC_TP_NOT_AVAIL_RETRY
| ....
| 084B6031
|
LU62RC_TP_NOT_AVAIL_NO_RETRY
| ....
| 084C0000
|
LU62RC_TPN_NOT_RECOGNIZED
| ....
| 10086021
|
LU62RC_PIP_NOT_SPECIFIED_CORRECTLY
| ....
| 10086032
|
LU62RC_CONV_TYPE_MISMATCH
| ....
| 10086034
|
LU62RC_SYNLVL_NOTSUPORT
| ....
| 10086041
|
LU62RC_DLLOC_ABEND_PGM
| 0006
|
|
LU62RC_DLLOC_ABEND_SVC
| 0007
|
|
LU62RC_DLLOC_ABEND_TMR
| 0008
|
|
LU62RC_PGMERR_PURGING
| 000E
|
|
LU62RC_CONVFAIL_RETRY
| 000F
|
|
LU62RC_CONVFAIL_NORETRY
| 0010
|
|
LU62RC_SVCERR_PURGING
| 0013
|
|
LU62RC_TPF_ABEND
| FFFF
|
|
Programming Considerations
- The conversation must be in send state.
- The value supplied in resid must be the resource ID returned by
the tppc_allocate function or one that was assigned by an incoming
ATTACH.
- The following considerations apply if data and length
are NULL:
- The data to be sent must be in the main storage block attached to data
level 0 (D0) in AMSG format. The block can be a small (381), large
(1055), or 4KB storage block. The data must be in logical record
format; that is, the first 2 bytes contain the length of the logical
record followed by the data. The storage block can contain 1 or more
full logical records or it can contain a partial logical record. The
number of bytes in the block to be sent is always in the AMSG length field
(AM0CCT) regardless of the logical record boundary. It is the
transaction program's responsibility to insure the accuracy of both the
logical record length field (LL preceding the text) and the storage block
length field (AM0CCT).6
- If the complete logical record does not fit into 1 block, the message can
be forward chained. The number of bytes of text for each of the chained
segments is placed in the AMSG length field (AM0CCT), and the file address of
the next segment is placed in the standard TPF forward chain field
(AM0FWD). A forward chain field containing zeros indicates the last
segment of a chained logical record. The logical record length in the
first 2 bytes of the first segment contains the length of the entire logical
record, and the AM0CCT field of each segment contains the physical number of
bytes of text in each segment.
- The transaction program can also send logical records by issuing multiple
tppc_send_data functions for segments of the logical record.
In this case, the first segment must contain the logical record length (LL)
preceding the first byte of the text, and the AMSG length field (AM0CCT) must
contain the number of bytes in each storage block.
- If the return code is not LU62RC_OK, the data remains on D0
unchanged.
- The following considerations apply if data and length
are not NULL:
- The data must be in logical record format; that is, the first 2 bytes
of the logical record contain the length of the record followed by the
data.
- The number of bytes to be sent is always the value pointed to by the
length parameter regardless of the logical record boundary.
- It is the transaction program's responsibility to insure the accuracy
of both the logical record length field (LL preceding the text) and the
length parameter.
- The entire storage area referred to by the data and
length parameters must be addressable by the TPF/APPC support
code.
- The maximum size of a logical record is 32 767.
- When the rtsrcvd parameter is RTSRCVD_YES, the remote
program is requesting the local TPF transaction program to enter
receive state and thereby place the remote program in
send state. The local TPF transaction program enters
receive state by issuing tppc_receive or
tppc_prepare_to_receive. The remote partner program enters
the corresponding send state when it calls tppc_receive
and receives the SEND indicator on the whatrcv parameter.
- See to Programming Considerations for Basic Conversation Functions for programming considerations relating to the TPF/APPC
basic conversation functions.
Examples
The following example sends data to the remote transaction program.
#include <tppc.h>
unsigned int resource_id;
struct tppc_return_codes return_code;
enum t_rtsrcvd request_received;
unsigned short int length;
unsigned char *data;
·
·
·
/* set up resource_id with the value returned from the allocate verb */
·
·
·
tppc_send_data(&resource_id,&return_code,&request_received, \
data,&length);
/* normal processing path */
·
·
·
Related Information
Footnotes:
- 5
-
If either data or length is NULL while the other parameter
is not NULL, a parameter check is issued.
- 6
-
The AM0CCT field is equal to the actual text count in this block plus 5, which
is the length of the AM0SG filler. Thus the physical length of data in
a block is (AM0CCT - 5).