snalu62_send_data(3) — Subroutines

NAME

snalu62_send_data − Sends data to the remote transaction program.

LIBRARY

/usr/shlib/libsnatprm.so

SYNOPSIS

#include <sna/snatprmdf.h>

STATUS_RTN snalu62_send_data(
       RES_ID resource,
       STATUS_VEC status_vec,
       unsigned char ∗data,
       UINT32 length,
       char ∗map_name,
       UINT8 user_control_data,
       UINT8 ps_control_data,
       UINT8 encrypt,
       UINT8 ∗rts_recv,
       UINT8 ∗exp_data_recv,
       ASYNC_INFO ∗wait_object
       );

Valid Conversation States

HDX: Send

FDX: Send-Receive and Send-Only

SUPPLIED PARAMETERS

resource

A RES_ID structure specifying the resource ID assigned to the conversation by the interface. This ID is returned by the snalu62_allocate, snalu62_attach_listen, or snalu62_receive_allocate verb.

data

A pointer to an unsigned char buffer containing the data that the interface should send. In mapped conversations, the buffer contains only the data to be sent. In basic conversations, the buffer contains zero or more logical records. Each logical record consists of a 2-byte length field followed by a data field. The high-order bit of this length field indicates whether the logical record is complete or if more of the record follows in the next message. The remaining 15 bits contain the length of the record (including the 2-byte length field). Therefore, the maximum length of the data field is 32,765 bytes and logical-record length values of 0 and 1 are invalid. The data field is optional, that is, the data field can consist of zero bytes.

length

A UINT32 value specifying the length of the data, specified in the data parameter, that the interface should transmit.

map_name

This parameter is a place holder. The functionality represented by this parameter is not implemented.

user_control_data

For mapped conversations only, a UINT8 value specifying whether the data record contains user control data. A value of TRUE (1) indicates that the data record contains user control data. A value of FALSE (0), the default, indicates that the data record does not contain user control data.

ps_control_data

A UINT8 value specifying whether the data parameter contains Presentation Services (PS) control data. A value of TRUE (1) indicates that the data should be prefaced with a PS header and that the data is complete. A value of FALSE (0), the default, indicates that the data is not PS control data. Only a process having superuser privileges or a user listed in the system group in the etc/group file can set this parameter to TRUE.

PS headers are sent between sync-point managers. These headers contain sync-point information such as prepare, commit, committed, forget, and backout requests. Although the interface supports conversation with a sync-level of sync-point, the interface does not generate the sync-point data. Therefore, if you wish to use sync-point level conversations, you must create your own sync-point data and use this parameter to indicate that you are sending sync-point data to the partner transaction program.

encrypt

A UINT8 value specifying whether the interface should use encryption when the mode allows selective encryption.

Always specify a value of FALSE (0) to indicate that the interface should not encrypt the data.

wait_object

A pointer to an ASYNC_INFO structure specifying whether the interface should process this verb in a blocking or non-blocking manner.

RETURNED PARAMETERS

status_vec

A pointer to a STATUS_VEC array to receive the completion status information.

rts_recv

A pointer to a UINT8 location to receive a boolean value indicating whether the remote transaction program has requested permission to send data. A value of TRUE (1) indicates the remote program is requesting to send data. A value of FALSE (0) indicates the remote program has not requested to send data. For full-duplex conversation, the interface always returns a value of FALSE for this parameter.

exp_data_recv

A pointer to a UINT8 location to receive a boolean value indicating whether an expedited data notification has been received. A value of TRUE (1) indicates an expedited data notification has been received. A value of FALSE (0) indicates no expedited data notification has been received.

DESCRIPTION

In a basic conversation, the data format consists of logical records. However, the length parameter does not directly control how many logical records the program can send. That is, the data can consist of the following combinations:

•The beginning of a record.

•The middle of the record.

•The end of the record.

•One or more complete records.

•One or more complete records, followed by the beginning of a record.

•The end of a record, followed by one or more complete records.

•The end of a record, followed by one or more complete records, followed by the beginning of a record.

•The end of a record, followed by the beginning of a record.

The local transaction program must finish sending a logical record before it can issue the following verbs:

•snalu62_confirm

•snalu62_deallocate with type = SNALU62_C_FLUSH, SNALU62_C_CONFIRM, or SNALU62_C_SYNC_LEVEL)

•snalu62_prepare_to_receive

•snalu62_receive_and_wait

A program completes a logical record by sending all the data in the record. A program can also complete a logical record by truncating the data. The program truncates the data by using the snalu62_send_error verb or by using the snalu62_deallocate verb with the type parameter set to one of the ABEND options.

In a mapped conversation, the data always consists of a single record. Therefore, a program cannot truncate a data record.

In both types of conversations, the interface buffers the send data until the data size equals an amount agreed upon by the local and remote LUs during session activation. To force the immediate sending of data, the program must use the snalu62_flush verb.

RESTRICTIONS

None

RETURN VALUES

SNALU62_S_OKnormal successful completion

SNALU62_S_ALLERR
conversation could not be allocated

SNALU62_S_BACKOUT
backed out

SNALU62_S_CONVCANC
conversation canceled

SNALU62_S_DEABPR
deallocate ABEND program

SNALU62_S_DEABSVC
deallocate ABEND services

SNALU62_S_DEABTIM
deallocate ABEND timer

SNALU62_S_ENCRNSUP
encryption not supported

SNALU62_S_ERRIND
error indication

SNALU62_S_FMHNOT
user control data (FMH) not supported

SNALU62_S_MAPEFAI
map execution failure

SNALU62_S_MAPNFOU
map name not found

SNALU62_S_MAPNSUP
mapping not supported

SNALU62_S_OPINCOMP
non-blocking operation not completed

SNALU62_S_OPNOTACC
non-blocking operation not accepted

SNALU62_S_PARERR
parameter error, function-name

SNALU62_S_PRERPU
program error purging

SNALU62_S_PRGPARCHK
program parameter check

SNALU62_S_RESFNO
resource failure no retry

SNALU62_S_RESFRET
resource failure retry

SNALU62_S_STAERR
LU6.2 verb function-name invalid with conversation in current state

SNALU62_S_SVCERPU
service error purging

SNALU62_S_UNSUC
verb did not execute successfully

ERRORS