Editar

Partilhar via

RECEIVE_ALLOCATE

  • Artigo

The RECEIVE_ALLOCATE verb is issued by the invoked transaction program (TP) to confirm that the invoked TP is ready to begin a conversation with the invoking TP that issued ALLOCATE or MC_ALLOCATE.

The following structure describes the verb control block (VCB) used by the RECEIVE_ALLOCATE verb.

Syntax

  
struct receive_allocate {  
    unsigned short   opcode;  
    unsigned char    opext;  
    unsigned char    reserv2;  
    unsigned short   primary_rc;  
    unsigned long    secondary_rc;  
    unsigned char    tp_name[64];  
    unsigned char    tp_id[8];  
    unsigned long    conv_id;  
    unsigned char    sync_level;  
    unsigned char    conv_type;  
    unsigned char    user_id[10];  
    unsigned char    lu_alias[8];  
    unsigned char    plu_alias[8];  
    unsigned char    mode_name[8];  
    unsigned char    reserv3[2];  
    unsigned long    conv_group_id;  
    unsigned char    fqplu_name[17];  
    unsigned char    pip_incoming;  
    unsigned char    syncpoint_rqd;  
    unsigned char    reserv4[3];  
};

Members

opcode
Supplied parameter. Specifies the verb operation code, AP_RECEIVE_ALLOCATE.

opext
Supplied parameter. Specifies the verb operation extension, AP_BASIC_CONVERSATION.

reserv2
A reserved field.

primary_rc
Returned parameter. Specifies the primary return code set by APPC at the completion of the verb. The valid return codes vary depending on the APPC verb issued. See Return Codes for valid error codes for this verb.

secondary_rc
Returned parameter. Specifies the secondary return code set by APPC at the completion of the verb. The valid return codes vary depending on the APPC verb issued. See Return Codes for valid error codes for this verb.

tp_name
Supplied parameter. Provides the name of the local TP. The value of tp_name must match the TP name configured through registry or environment variables. APPC matches the RECEIVE_ALLOCATE verb's tp_name parameter with the TP name specified by the incoming allocate, which is generated by MC_ALLOCATE or ALLOCATE in the invoking TP.

This parameter is a 64-byte EBCDIC character string and is case-sensitive. The tp_name parameter can consist of characters from the type AE EBCDIC character set:

  • Uppercase and lowercase letters

  • Numerals 0 through 9

  • Special characters $, #, and period (.)

    If tp_name is fewer than 64 bytes, use EBCDIC spaces (0x40) to pad it on the right.

    The SNA convention is that a service TP name can have up to four characters. The first character is a hexadecimal byte between 0x00 and 0x3F. The other characters are from the type AE EBCDIC character set.

    tp_id
    Returned parameter. Identifies the local TP.

    conv_id
    Returned parameter. Provides the conversation identifier. It identifies the conversation APPC has established between the two partner TPs.

    sync_level
    Returned parameter. Specifies the synchronization level of the conversation. It determines whether the TPs can request confirmation of receipt of data and confirm receipt of data.

  • AP_NONE specifies that confirmation processing will not be used in this conversation.

  • AP_CONFIRM_SYNC_LEVEL specifies that the TPs can use confirmation processing in this conversation.

  • AP_SYNCPT specifies that TPs can use Sync Point Level 2 confirmation processing in this conversation.

    conv_type
    Returned parameter. Specifies the type of conversation chosen by the partner TP, using MC_ALLOCATE or ALLOCATE. The following are possible values:

    AP_BASIC_CONVERSATION

    AP_MAPPED_CONVERSATION

    user_id
    Returned parameter. Provides the user identifier specified by the partner TP, using MC_ALLOCATE or ALLOCATE (if the partner TP set the MC_ALLOCATE or ALLOCATE verb's security parameter to AP_PGM or AP_SAME). It is a type AE EBCDIC character string.

    lu_alias
    Returned parameter. Provides the alias by which the local logical unit (LU) is known to the local TP. It is an ASCII character string.

    plu_alias
    Returned parameter. Provides the alias by which the partner LU (which initiated the incoming allocate) is known to the local TP. It is an ASCII character string.

    mode_name
    Returned parameter. Provides the mode name specified by MC_ALLOCATE or ALLOCATE in the partner TP. It is the name of a set of networking characteristics defined during configuration. The mode_name is a type A EBCDIC character string.

    reserv3
    A reserved field.

    conv_group_id
    Conversation group identifier.

    fqplu_name
    This returned parameter provides the fully qualified LU name.

    pip_incoming
    This optional supplied and returned parameter is applicable only if Sync Point services are required.

    For the supplied parameter:

    AP_YES if TP does accept PIP data.

    AP_NO if TP does not accept PIP data.

    For the returned parameter:

    AP_YES if PIP data is available.

    AP_NO if PIP data is not available.

    syncpoint_rqd
    This parameter indicates if Sync Point services are required.

    AP_YES if Sync Point is required.

    AP_NO if Sync Point is not required.

    reserv4
    A reserved field.

Return Codes

AP_OK
Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK
Primary return code; the verb did not execute because of a parameter error.

AP_UNDEFINED_TP_NAME

Secondary return code; the TP name was not configured correctly.

AP_STATE_CHECK
Primary return code; the verb did not execute because it was issued in an invalid state.

AP_ALLOCATE_NOT_PENDING

Secondary return code; APPC did not find an incoming allocate (from the invoking TP) to match the value of tp_name, supplied by RECEIVE_ALLOCATE. RECEIVE_ALLOCATE waited for the incoming allocate and eventually timed out.

AP_INVALID_PROCESS

Secondary return code; the process issuing RECEIVE_ALLOCATE was different from the one started by APPC.

AP_COMM_SUBSYSTEM_ABENDED
Primary return code; indicates one of the following conditions:

  • The node used by this conversation encountered an ABEND.

  • The connection between the TP and the PU 2.1 node has been broken (a LAN error).

  • The SnaBase at the TP's computer encountered an ABEND.

    The system administrator should examine the error log to determine the reason for the ABEND.

    AP_CONV_BUSY
    Primary return code; there can only be one outstanding conversation verb at a time on any conversation.

    AP_THREAD_BLOCKING
    Primary return code; the calling thread is already in a blocking call.

    AP_COMM_SUBSYSTEM_NOT_LOADED
    Primary return code; a required component could not be loaded or terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

    AP_INVALID_VERB_SEGMENT
    Primary return code; the VCB extended beyond the end of the data segment.

    AP_STACK_TOO_SMALL
    Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

    AP_UNEXPECTED_DOS_ERROR
    Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

This must be the first APPC verb issued by the invoked TP. The initial state is RESET. If the verb executes successfully (primary_rc is AP_OK), the state changes to RECEIVE.

In response to this verb, APPC establishes a conversation between the two TPs and generates a TP identifier for the invoked TP and a conversation identifier. These identifiers are required parameters for subsequent APPC verbs.

If the invoked TP issues RECEIVE_ALLOCATE and a corresponding incoming allocate (resulting from MC_ALLOCATE or ALLOCATE issued by the invoking TP) is not present, the invoked TP waits until the incoming allocate arrives or the verb times out. The time-out value is set by the system administrator.

Host Integration Server also supports APPC RECEIVE_ALLOCATE_EX and RECEIVE_ALLOCATE_EX_END functions, to simplify the design and implementation of some invokable transaction programs. This function allows an APPC application to receive all incoming FMH-5 Attach requests received by Host Integration Server over a specific Local APPC LU, allowing an application to act as an "attach manager." An attach manager is a program that handles an incoming FMH-5 Attach request to start an LU6.2 conversation. When an APPC application calls RECEIVE_ALLOCATE (as opposed to RECEIVE_ALLOCATE_EX), Host Integration Server handles the attach manager functionality.

For more information on attach manager, see RECEIVE_ALLOCATE_EX.