snalu62_receive_and_wait(3) — Subroutines

NAME

snalu62_receive_and_wait − Waits for information to arrive from the remote transaction program and receives it. The information may be data, conversation status, or a request for confirmation.

LIBRARY

/usr/shlib/libsnatprm.so

SYNOPSIS

#include <sna/snatprmdf.h>

STATUS_RTN snalu62_receive_and_wait(
       RES_ID resource,
       STATUS_VEC status_vec,
       UINT32 fill,
       UINT32 ∗length,
       UINT8 ∗rts_recv,
       UINT8 ∗exp_data_recv,
       unsigned char ∗data,
       UINT32 ∗data_recv,
       UINT32 ∗status_recv,
       char ∗map_name,
       ASYNC_INFO ∗wait_object
       );

Valid Conversation States

HDX: Send and Receive

FDX: Send-Receive and Receive-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.

fill

A UINT32 value specifying whether the data is received in logical-record format or independent of logical-record format. Specify one of the following values:

•SNALU62_C_BUFFER

Specifies that the interface should supply data to the program independent of the logical-record format of the data. The interface continues to return full buffers on subsequent receive calls until all data is returned. The last buffer returned may be a partially-filled buffer.

•SNALU62_C_LL (the default for basic conversations)

Specifies that the interface should supply data to the program one logical record at a time. If the logical record cannot fit into the supplied data buffer, the interface truncates the data. If the logical record is shorter than the supplied data buffer, the interface returns only one logical record.

This parameter is only valid for basic conversations. The interface ignores it for mapped conversations.

wait_object

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

SUPPLIED AND RETURNED PARAMETER

length

A pointer to a UINT32 location specifying the maximum length of data that this program can receive. The program can specify a length of zero. In this case, the interface supplies an indication, through the data_recv parameter, of whether data is available but returns no data in the data parameter.

This location also receives a value indicating the actual size of the data returned in the buffer referenced by the data parameter. For basic conversations, the interface includes the 2-byte LL field in the returned length value.

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 conversations, 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.

data

A pointer to an unsigned char buffer to receive the data sent by the remote transaction program.

data_recv

A pointer to a UINT32 location to receive a value indicating what was stored into the buffer supplied by the data parameter. It can be one of the following values:

•SNALU62_C_NO_DATA

For basic and mapped conversations: Specifies that the interface returned no data in the data buffer.

•SNALU62_C_DATA

For basic conversations: Used when the program specifies SNALU62_C_BUFFER for fill. Indicates that the interface returned data to the program.

•SNALU62_C_DATA_COMPLETE

For basic and mapped conversations: Indicates that the interface returned a complete data record or the final portion of a data record. For basic conversations the interface uses this code when the program specifies SNALU62_C_LL for fill.

•SNALU62_C_DATA_INCOMPLETE

For basic and mapped conversations: Specifies that the interface returned less then a complete data record. The program may receive the remainder of the data by using more receive calls. For basic conversations, the interface uses this code when the program specifies SNALU62_C_LL for fill.

•SNALU62_C_DATA_TRUNCATED

For mapped conversations: Specifies that the interface returned an incomplete data record. The interface discarded the remainder of the data.

•SNALU62_C_LL_TRUNCATED

For basic conversations: Specifies that the interface returned an incomplete data record. The interface discarded the remainder of the data. The interface uses this code when the program specifies SNALU62_C_LL for fill.

•SNALU62_C_USER_CTRL_COMPLETE

For mapped conversations: Indicates that the interface returned a complete data record or the final portion of a data record and the data contained user control data.

•SNALU62_C_USER_CTRL_INCOMPLETE

For mapped conversations: Specifies that the interface returned less then a complete data record containing user control data. The program may receive the remainder of the data by using more receive calls.

•SNALU62_C_USER_CTRL_TRUNCATED

For mapped conversations: Specifies that the interface returned an incomplete data record containing user control data. The interface discarded the remainder of the data.

•SNALU62_C_PS_HEADER_COMPLETE

For basic and mapped conversations: Specifies that the interface received a complete Presentation Services (PS) header. This value indicates that the interface has received a complete Sync-Point Services PS header. For basic conversations, the data includes the leading 0x0001, indicating that the data is a PS header. These 2 bytes are included in the value returned in the length parameter.

•SNALU62_C_PS_HEADER_INCOMPLETE

For basic and mapped conversations: Specifies that the interface received an incomplete Presentation Services header. This value indicates that the interface has received an incomplete Sync Point Services Presentation Services header. For basic conversations, the data includes the leading 0x0001, indicating that the data is a PS header. These 2 bytes are included in the value returned in the length parameter.

The Compaq SNA APPC/LU6.2 Programming Interface for Tru64 UNIX product splits the WHAT_RECEIVED parameter described in the Systems Network Architecture Transaction Programmer’s Reference Manual for LU Type 6.2 into two parameters: data_recv and status_recv.

status_recv

A pointer to a UINT32 location to receive a value indicating the new status of the conversation. It can be one of the following values:

•SNALU62_C_SEND_RECV

The remote program has entered the Receive state. The local program enters the Send state and may now send data.

•SNALU62_C_CONFIRM_RECV

The remote program called the confirm verb. This action requests the local program to call the snalu62_confirmed verb. The local program enters the Confirm state.

•SNALU62_C_CONFIRM_SEND_RECV

The remote program called the PREPARE_TO_RECEIVE verb. The remote program requested that the prepare-to-receive function be preceded by the function of the confirm verb. See snalu62_prepare_to_receive for more information. The local program enters the Confirm-Send state.

•SNALU62_C_CONFIRM_DEALLOC_RECV

The remote program called the deallocate verb. The remote program requested that the deallocate function be preceded by the function of the confirm verb. See snalu62_deallocate for more information. The local program enters the Confirm-Deallocate state.

•SNALU62_C_NO_STATUS_RECV

No state change information is available.

•SNALU62_C_PS_HEADER_NEXT

A Presentation Services header follows the data being received by this call. That is, the next receive call returns with the data_recv parameter set to SNALU62_C_PS_HEADER_COMPLETE or SNALU62_C_PS_HEADER_INCOMPLETE.

map_name

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

DESCRIPTION

If this verb is successful, it returns either data or status but not both. That is, when this verb returns SNALU62_S_OK, either the data_recv parameter is SNALU62_C_NO_DATA or the status_recv parameter is SNALU62_C_NO_STATUS_RECV. However, in conversations with a synchronization level of SNALU62_C_SL_SYNCPT, the status_recv parameter can return SNALU62_C_PS_HEADER_NEXT even when data is returned. If the verb returns a code other than SNALU62_S_OK, neither return parameter is meaningful.

This verb cancels or resets posting, then enables posting using the information supplied with the verb. The interface resets posting when this verb completes. For more information, see the description of the snalu62_post_on_receipt verb.

Half-Duplex Processing

The program can call this verb when the conversation is in the Send state. In this case, the LU flushes its send buffer, sending all buffered information and the SEND indication to the remote program. This changes the conversation to Receive state. The program then waits for information to arrive. The remote program can send data to the local program after it receives the SEND indication.

Full-Duplex Processing

Generally, a call to this verb does not flush the send buffer. However, if the send buffer contains the allocation request, the interface flushes the send buffer. If needed, the program should use the snalu62_flush verb to flush the send buffer.

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_DEALNOR
deallocate normal

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_PRERNTR
program error no truncate

SNALU62_S_PRERPU
program error purging

SNALU62_S_PRERTR
program error truncate

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_SVCENTR
service error no truncate

SNALU62_S_SVCERPU
service error purging

SNALU62_S_SVCERTR
service error truncate

SNALU62_S_UNSUC
verb did not execute successfully

ERRORS