TP_STARTED

The TP_STARTED verb is issued by the invoking TP, and notifies APPC that the TP is starting.

For the Microsoft® Windows® version 3.x system, it is recommended that you use the WinAsyncAPPC function rather than the blocking version of this call.

The following structure describes the verb control block used by the TP_STARTED verb.

struct tp_started {
    unsigned short  opcode;
    unsigned char   opext;
    unsigned char   reserv2;
    unsigned short  primary_rc;
    unsigned long   secondary_rc;
    unsigned char   lu_alias[8];
    unsigned char   tp_id[8];
    unsigned char   tp_name[64];
    unsigned char   syncpoint_rqd;
};

Members

opcode
Supplied parameter. Specifies the verb operation code, AP_TP_STARTED.
opext
Supplied parameter. Specifies the verb operation extension. If the AP_EXTD_VCB bit is set, this indicates that the tp_started structure includes the syncpoint_rqd member used for Sync Point support. Otherwise the verb control block ends immediately after the tp_name member.
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.
lu_alias
Supplied parameter. Specifies the alias by which the local LU is known to the local TP.

The name must match an LU alias established during configuration. APPC checks the LU alias against the current SNA Server configuration file. Due to the client/server architecture used by SNA Server, however, this parameter is not validated until an ALLOCATE or MC_ALLOCATE is performed.

This parameter is an 8-byte ASCII character string. It can consist of the following ASCII characters:

The first character of this string cannot be a space.

If the value of this parameter is fewer than eight bytes in length, pad it on the right with ASCII spaces (0x20).

To use an LU from the default LU pool, set this field to eight hexadecimal zeros. For more information, see Default LUs.

tp_id
Returned parameter. Identifies the newly-established TP.
tp_name
Supplied parameter. Specifies the name of the local TP.

Under the SNA Server implementation of APPC, this parameter is ignored when issued by TP_STARTED. However, this parameter is required if the program runs under the IBM ES for OS/2 version 1.0 implementation of APPC.

This parameter is a 64-byte EBCDIC character string and is case-sensitive. The tp_name parameter can consist of the following EDCDIC characters:

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

The SNA convention for a service TP name is up to four characters. The first character is a hexadecimal byte between 0x00 and 0x3F.

syncpoint_rqd
This optional parameter is only applicable if the AP_EXTD_VCB bit is set in the opext parameter and Sync Point services are required.

Return Codes

ap_ok
Primary return code; the verb executed successfully.
ap_comm_subsystem_abended
Primary return code; indicates one of the following conditions:

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

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.

When this return code is used with ALLOCATE or MC_ALLOCATE, it can indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there is no node available that can satisfy the ALLOCATE or MC_ALLOCATE request.

When ALLOCATE or MC_ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

0xF0000001
Secondary return code; no nodes have been started.
0xF0000002
Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:
·    The node with the local LU is not started.
·    The local LU is not configured.

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_tp_busy
Primary return code; the local TP has issued a call to APPC while APPC was processing another call for the same TP.
ap_thread_blocking
Primary return code; the calling thread is already in a blocking call.
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

In response to TP_STARTED, APPC generates a TP identifier for the invoking TP. This identifier is a required parameter for subsequent APPC verbs issued by the invoking TP.

This must be the first APPC verb issued by the invoking TP. Consequently, no prior APPC state exists.

If the verb executes successfully (primary_rc is ap_ok), the state changes to RESET.