|
|
|
|
This chapter contains a description of each APPC control 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 TP_STARTED 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 control verbs are described in the following order:
The TP_STARTED verb is issued by the invoking TP. It notifies APPC that the TP is starting, and specifies the local LU that it will use.
If the TP is using dependent LUs for multiple concurrent conversations, it must issue a separate TP_STARTED verb (followed by [MC_]ALLOCATE) for each conversation, to obtain a different LU for each conversation; this is because each dependent LU can support only one conversation at a time.
In response to this verb, APPC generates a TP identifier for the invoking TP. This identifier is a required parameter for subsequent APPC verbs issued by the invoking TP.
The definition of the VCB structure for the TP_STARTED verb is as follows:
typedef struct tp_started
{
AP_UINT16 opcode;
unsigned char opext; /* Reserved */
unsigned char format; /* Reserved */
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
unsigned char lu_alias[8];
unsigned char tp_id[8];
unsigned char tp_name[64];
unsigned char delay_start; /* Reserved */
unsigned char enable_pool; /* Reserved */
unsigned char pip_dlen; /* Reserved */
} TP_STARTED;
The definition of the VCB structure for the TP_STARTED verb is as follows:
typedef 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];
} TP_STARTED;
The TP supplies the following parameters to APPC:
Alias by which the local LU is known to the local TP. This name must match an LU alias established during configuration.
This parameter is an 8-byte ASCII character string. It can consist of any of the following characters:
Uppercase letters
Numerals 0-9
Blanks
Special characters $, #, %, and @
The first character of this string cannot be a blank (unless the whole string consists of blanks).
If the LU alias is shorter than eight characters, pad it on the right with ASCII blanks (0x20).
Depending on the configuration, you may be able to specify that the application uses a default local LU (check with your System Administrator); to do this, set lu_alias to a string of eight binary zeros. For compatibility with other APPC implementations, SNAP-IX also accepts a string of eight ASCII blanks to indicate the default LU; however, new applications should use binary zeros.
Name of the local TP. The first eight characters of this name are translated into ASCII, and used by SNAP-IX administration programs to identify the TP in a list of running APPC TPs.
This parameter is a 64-byte case-sensitive EBCDIC character string. The tp_name parameter normally consists of characters from the type-AE EBCDIC character set (unless it is the name of a service TP). These characters are as follows:
Uppercase and lowercase letters
Numerals 0-9
Special characters $, #, @, and period (.)
If the TP name is fewer than 64 bytes, use EBCDIC blanks ( 0x40) to pad it on the right.
The SNA convention for naming a service TP is an exception to the normal tp_name parameter; the name consists of up to four characters, of which the first character is a hexadecimal byte between 0x00 and 0x3F. The other characters are from the EBCDIC AE character set.
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:
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 the lu_alias parameter was not valid.
The reserved parameter format was set to a nonzero value.
Using the synchronous APPC entry point, the application issued this verb within a callback routine. 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.
TP_STARTED must be the first APPC verb issued by the invoking TP. Consequently, no conversations are active and no conversation state exists.
A single APPC program can issue more than one TP_STARTED verb. Each verb creates a logically different APPC TP, although they are all executing in the same process.
Not applicable (no conversations have been started, so there is no conversation state).
|
|
|
 |
|