|
|
|
|
This chapter contains a description of each APPC conversation verb. The following information is provided for each verb:
Definition of the verb.
Structure defining the verb control block (VCB) used by the verb. The structure is defined in the APPC header file /usr/include/sna/appc_c.h(Solaris) or sdk/winappc.h (Windows). Parameters beginning with reserv are reserved.
Parameters (VCB fields) supplied to and returned by APPC. For each parameter, the following information is provided:
Description
Possible values
Additional information
Conversation state or states in which the verb can be issued.
State or states to which the conversation can change upon return from the verb. Conditions that do not cause a state change are not noted. For example, parameter checks and state checks do not cause a state change.
Additional information describing the use of the verb.
Most parameters supplied to and returned by APPC are hexadecimal values.
To simplify coding, these values are represented by meaningful symbolic constants
defined in the header file values_c.h, which is included
by the APPC header file appc_c.h. For example, the
opcode parameter of the MC_SEND_DATA verb is the hexadecimal value
represented by the symbolic constant
It is important that you use the symbolic constant and not the hexadecimal value when setting values for supplied parameters, or when testing values of returned parameters. This is because different Solaris systems store these values differently in memory, so the value shown may not be in the format recognized by your system.
For Windows, the constants for supplied and returned parameter values are defined in the Windows APPC header file winappc.h.
The notation [MC_]verb
refers to both the mapped and
basic form of an APPC verb. For example, [MC_]SEND_DATA refers to the MC_SEND_DATA
and SEND_DATA verbs.
The APPC VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The conversation verbs are described in the following order:
GET_TYPE
[MC_]ALLOCATE
[MC_]CONFIRM
[MC_]CONFIRMED
[MC_]DEALLOCATE
[MC_]FLUSH
[MC_]GET_ATTRIBUTES
[MC_]PREPARE_TO_RECEIVE
[MC_]RECEIVE_AND_POST
[MC_]RECEIVE_AND_WAIT
[MC_]RECEIVE_IMMEDIATE
[MC_]REQUEST_TO_SEND
[MC_]SEND_CONVERSATION
[MC_]SEND_DATA
[MC_]SEND_ERROR
[MC_]TEST_RTS
[MC_]TEST_RTS_AND_POST
The GET_TYPE verb returns the conversation type (basic or mapped) of a particular conversation.
With this information, the TP can decide whether to issue basic-conversation or mapped-conversation verbs.
The definition of the VCB structure for the GET_TYPE verb is as follows:
typedef struct get_type
{
AP_UINT16 opcode;
unsigned char opext; /* Reserved */
unsigned char format; /* Reserved */
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
unsigned char tp_id[8];
AP_UINT32 conv_id;
unsigned char conv_type;
} GET_TYPE;
The definition of the VCB structure for the GET_TYPE verb is as follows:
typedef struct get_type
{
unsigned short opcode;
unsigned char opext;
unsigned char reserv2;
unsigned short primary_rc;
unsigned long secondary_rc;
unsigned char tp_id[8];
unsigned long conv_id;
unsigned char conv_type;
} GET_TYPE;
The TP supplies the following parameters to APPC:
Identifier for the local TP.
The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Identifier for the conversation this TP is inquiring about.
The value of this parameter was returned by the [MC_]ALLOCATE verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful.
If the verb executes successfully, APPC returns the following parameters:
AP_OK
Conversation type of the conversation identified by conv_id .
Possible values are:
If the verb does not execute successfully, APPC returns a primary return code parameter to indicate the type of error and a secondary return code parameter to provide specific details about the reason for unsuccessful execution.
If the verb does not execute because of a parameter error, APPC returns the following parameters:
AP_PARAMETER_CHECK
Possible values are:
The value of conv_id did not match a conversation identifier assigned by APPC.
The value of tp_id did not match a TP identifier assigned by APPC.
The reserved field format was set to a nonzero value.
The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point.
No state check errors occur for this verb.
If the verb does not execute because other conditions exist, APPC returns primary return codes (and, if applicable, secondary return codes). For information about these return codes, see Common Return Codes.
Possible return codes are:
APPC does not return secondary return codes with these primary return codes.
The conversation can be in any state except Reset when the TP issues this verb.
The conversation state does not change for this verb.
|
|
|
 |
|