SET_TP_PROPERTIES

The SET_TP_PROPERTIES verb allows a TP to set its logical unit-of-work identifiers (LUWIDs) to either an existing value, by providing the LUWIDs, or request that Microsoft® SNA Server generate new ones and use them from then on. When the LUWID is generated by SNA Server, it is guaranteed to be unique. This verb is used only if Sync Point support is enabled.

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

struct set_tp_properties {
    unsigned short  opcode;
    unsigned char   opext;
    unsigned char   reserv2;
    unsigned short  primary_rc;
    unsigned long   secondary_rc;
    unsigned char   tp_id[8];
    unsigned char   set_prot_id;
    unsigned char   new_prot_id;
    unsigned char   prot_id[26];
    unsigned char   set_unprot_id;
    unsigned char   new_unprot_id;
    unsigned char   unprot_id[26];
    unsigned char   set_user_id;
    unsigned char   reserv3;
    unsigned char   user_id[10];
    unsigned char   reserv4[10];
};

Members

opcode
Supplied parameter. Specifies the verb operation code, AP_SET_TP_PROPERTIES.
opext
Supplied parameter. Specifies the verb operation extension. The AP_EXTD_VCB bit must be set to indicate that the set_tp_properties structure requires Sync Point support.
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_id
Supplied parameter. Identifies the local TP. The value of this parameter was returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
set_prot_id
Supplied parameter. Indicates whether the prot_id member should be modified. Legal values are AP_YES or AP_NO.
new_prot_id
Supplied parameter. Indicates whether SNA Server should use the supplied prot_id LUWID member or create a new LUWID. Legal values are AP_YES (create a new LUWID) or AP_NO (use the supplied LUWID).
prot_id
This member is the protected logical unit-of-work identifier for the transaction in which the TP is participating. It is ignored if set_prot_id is AP_NO. It is a supplied parameter if new_unprot_id is AP_NO or a returned parameter if new_unprot_id is AP_YES.

Several TPs can be involved in a transaction. This identifier, which is assigned on behalf of the TP initiating the transaction, allows the conversation that makes up the transaction to be logically connected.

The prot_id can be represented as an luw_id_overlay structure with the following fields: 

typedef struct   luw_id_overlay {
    unsigned char  fqla_name_len;
    unsigned char  fqla_name[17];
    nsigned char   instance[6];
    unsigned char  sequence[2];
} LUW_ID_OVERLAY;
luw_id.fqla_name_len
A 1-byte length of the fully qualified LU name for the LU of the originating TP.
luw_id.fqla_name
The fully qualified name of the LU for the originating TP. The name is returned as a 17-byte EBCDIC string, consisting of the NETID, a period, and the LU name. If the length of the name is fewer than 17 bytes, the instance and sequence numbers follow immediately. (Note that because of this, you should not use the fields of the luw_id_overlay structure to access those values. These are provided for compatibility only).
luw_id.instance
A 6-byte string uniquely generated by the LU for the originating TP.
luw_id.sequence
A 2-byte number that indicates the segment of unit-of-work. (This is always set to 1 if Sync Point is not supported.)

If the luw_id length is fewer than 26 bytes, it is padded on the right with EBCDIC spaces.

set_unprot_id
Supplied parameter. Indicates whether the unprot_id member should be modified. Legal values are AP_YES or AP_NO.
new_unprot_id
Supplied parameter. Indicates whether SNA Server should use the supplied unprot_id LUWID member or create a new LUWID. Legal values are AP_YES (create a new LUWID) or AP_NO (use the supplied LUWID).
unprot_id
This member is the unprotected logical unit-of-work identifier for the transaction in which the TP is participating. It is ignored if set_unprot_id is AP_NO. It is a supplied parameter if new_unprot_id is AP_NO or a returned parameter if new_unprot_id is AP_YES.

Several TPs can be involved in a transaction. This identifier, which is assigned on behalf of the TP initiating the transaction, allows the conversation that makes up the transaction to be logically connected.

The prot_id can be represented as an luw_id_overlay structure with the following fields: 

typedef struct   luw_id_overlay {
    unsigned char  fqla_name_len;
    unsigned char  fqla_name[17];
    nsigned char   instance[6];
    unsigned char  sequence[2];
} LUW_ID_OVERLAY;
luw_id.fqla_name_len
A 1-byte length of the fully qualified LU name for the LU of the originating TP.
luw_id.fqla_name
The fully qualified name of the LU for the originating TP. The name is returned as a 17-byte EBCDIC string, consisting of the NETID, a period, and the LU name. If the length of the name is fewer than 17 bytes, the instance and sequence numbers follow immediately. (Note that because of this, you should not use the fields of the luw_id_overlay structure to access those values. These are provided for compatibility only).
luw_id.instance
A 6-byte string uniquely generated by the LU for the originating TP.
luw_id.sequence
A 2-byte number that indicates the segment of unit-of-work. (This is always set to 1 if Sync Point is not supported.)

If the luw_id length is fewer than 26 bytes, it is padded on the right with EBCDIC spaces.

set_user_id
Supplied parameter. Indicates whether the user_id member should be modified. Legal values are AP_YES or AP_NO.
user_id
Supplied parameter. Indicates the user_id that should be used by the initiating TP in the allocation request. The name is a 10-byte EBCDIC string, padded on the right with EBCDIC spaces. This parameter is ignored if set_user_id is AP_NO.

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_bad_tp_id
Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.
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. This can occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same tp_id.
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 verb relates to the TP rather than a specification conversation, so the TP can issue the verb in any state. There is no state change.

The prot_id and unprot_id members contain fields for fqla_name_len (the length of the fully qualified LU name of the LU originating the TP), fqla_name (the fully qualified name of the LU originating the TP), instance (generated uniquely by the LU originating the TP), and sequence (always set to 1 and indicating the segment of unit-of-work).

It is the responsibility of the application (the Sync Point support component) to transmit the new LUWID PS header to the partner Sync Point support when the protected LUWID is changed. Similarly, when the new LUWID PS header is received, the application must inform the LU by issuing a SET_TP_PROPERTIES verb.