 |
» |
|
|
|
This verb returns the side information entry for a given symbolic destination
name, or for multiple symbolic destination names, depending on the
options used. Note the difference between this verb and the CPI-C function Extract_CPIC_Side_Information(). This verb queries a configuration file, so that it
returns the default information used by all SNAplus2 CPI-C applications.
The CPI-C function queries the application's own copy in memory
of the side information table, which the application may have modified
using the other CPI-C side information functions. This verb must be issued to the domain configuration file. VCB
Structure | |
typedef struct query_cpic_side_info
{
AP_UINT16 opcode; /* verb operation code */
unsigned char reserv2; /* reserved */
unsigned char format; /* reserved */
AP_UINT16 primary_rc; /* primary return code */
AP_UINT32 secondary_rc; /* secondary return code */
unsigned char *buf_ptr; /* pointer to buffer */
AP_UINT32 buf_size; /* buffer size */
AP_UINT32 total_buf_size; /* total buffer size required */
AP_UINT16 num_entries; /* number of entries */
AP_UINT16 total_num_entries; /* total number of entries */
unsigned char list_options; /* listing options */
unsigned char reserv3; /* reserved */
unsigned char sym_dest_name[8]; /* Symbolic destination name */
} QUERY_CPIC_SIDE_INFO;
|
typedef struct cpic_side_info_data
{
AP_UINT16 overlay_size; /* size of returned entry */
unsigned char sym_dest_name[8]; /* Symbolic destination name */
unsigned char reserv1[2]; /* reserved */
CPIC_SIDE_INFO_DEF_DATA def_data;
} CPIC_SIDE_INFO_DATA;
|
typedef struct cpic_side_info_def_data
{
unsigned char description[32]; /* resource description */
unsigned char reserv1[16]; /* reserved */
CPIC_SIDE_INFO side_info; /* CPIC side info */
unsigned char reserv2[24]; /* reserved */
} CPIC_SIDE_INFO_DEF_DATA;
|
typedef struct cpic_side_info
{
unsigned char partner_lu_name[17]; /* Fully qualified partner */
/* LU name */
unsigned char reserved[3]; /* Reserved */
AP_UINT32 tp_name_type; /* TP name type */
unsigned char tp_name[64]; /* TP name */
unsigned char mode_name[8]; /* Mode name */
AP_UINT32 conversation_security_type; /* Conversation security */
/* type */
unsigned char security_user_id[10]; /* User ID */
unsigned char security_password[10]; /* Password */
unsigned char lu_alias[8]; /* LU alias */
} CPIC_SIDE_INFO;
|
Supplied
Parameters | |
The application supplies the following parameters: - opcode
AP_QUERY_CPIC_SIDE_INFO - overlay_size
For compatability with future releases of SNAplus2, your
application must use this field to determine the exact length of
the overlay structure returned, and should not rely on the use of
the sizeof() function. - buf_ptr
A pointer to a data buffer that SNAplus2 will use
to return the requested information. - buf_size
Size of the supplied data buffer. - num_entries
Maximum number of symbolic destination names for which
data should be returned. To request data for a specific symbolic
destination name rather than a range, specify the value 1.
To return as many entries as possible, specify zero; in this case,
SNAplus2 will return the maximum number of entries that can be accommodated
in the supplied data buffer. - list_options
The position in the list of symbolic destination
names from which SNAplus2 should begin to return data. Possible
values are: - AP_FIRST_IN_LIST
Start at the first entry in the list. - AP_LIST_INCLUSIVE
Start at the entry specified by the sym_dest_name parameter. - AP_LIST_FROM_NEXT
Start at the entry immediately following the entry
specified by the sym_dest_name parameter.
For more information about how the list is ordered and how
the application can obtain specific entries from it, see “List
Options For QUERY_* Verbs”. - sym_dest_name
Symbolic destination name for which data is required, or
the name to be used as an index into the list. This value is ignored
if list_options is set to AP_FIRST_IN_LIST.
The name is an ASCII string, consisting of uppercase A-Z and
numerals 0-9, padded on the
right with spaces if the name is shorter than 8 characters.
Returned
Parameters: Successful Execution | |
If the verb executes successfully, SNAplus2 returns the following parameters: - primary_rc
AP_OK - buf_size
Length of the information returned in the supplied buffer. - total_buf_size
Returned value indicating the size of buffer that
would have been required to return all the list information requested.
A value greater than buf_size indicates that not all the available entries were returned. - num_entries
Number of entries returned in the data buffer. - total_num_entries
Total number of entries available. A value greater
than num_entries indicates that not all the available entries were returned. Each entry in the data buffer consists of the following parameters: - cpic_side_info_data.overlay_size
The size of the returned cpic_side_info_data structure, and therefore the offset to the start of the next
entry in the data buffer. - cpic_side_info_data.sym_dest_name
Symbolic destination name for the returned side information
entry. - cpic_side_info_data.def_data.description
A null-terminated text string describing the side information
entry, as specified in the definition of the side information entry. - cpic_side_info_data.def_data.side_info.partner_lu_name
Fully qualified name of the partner LU. The name
is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It
consists of a network ID of up to 8 A-string characters, an EBCDIC
dot (period) character, and a network name of up to 8 A-string characters. - cpic_side_info_data.def_data.side_info.tp_name_type
The type of the target TP (the valid characters
for a TP name are determined by the TP type). Possible values are: - XC_APPLICATION_TP
Application TP. All characters in the TP name must
be valid ASCII characters. - XC_SNA_SERVICE_TP
Service TP. All characters, except the first, in
the TP name must be valid ASCII characters. The first character must
be a hexadecimal digit in the range 0x01-0x3F,
excluding 0x0E and 0x0F.
- cpic_side_info_data.def_data.side_info.tp_name
TP name of the target TP. This is a 64-byte ASCII character
string, right-padded with spaces. - cpic_side_info_data.def_data.side_info.mode_name
Name of the mode used to access the target TP. This
is an 8-byte ASCII character string, right-padded with spaces. - cpic_side_info_data.def_data.side_info.conversation_security_
type Specifies whether the target TP uses conversation security.
Possible values are: - XC_SECURITY_NONE
The target TP does not use conversation security. - XC_SECURITY_PROGRAM
The target TP uses conversation security. The security_user_id and security_password parameters specified below will be used to access the
target TP. - XC_SECURITY_PROGRAM_STRONG
As for XC_SECURITY_PROGRAM,
except that the local node must not send the password across the
network in clear text format. (This value is included for compatibility
with IBM CPI-C implementations. The SNAplus2 node cannot provide
the appropriate restrictions on sending the password; if a CPI-C
application attempts to issue the Allocate call with this value set,
the call will fail with a return code indicating that the requested security
type is not supported.) - XC_SECURITY_SAME
The target TP uses conversation security, and can
accept an “already verified” indicator from the local
TP. (This indicates that the local TP was itself invoked by another
TP, and has verified the security user ID and password supplied
by this TP.) The security_user_id parameter specified below will be used to access the
target TP; no password is required.
- cpic_side_info_data.def_data.side_info.security_user_id
User ID used to access the partner TP. This parameter is
not used if the conversation_security_type parameter is set to XC_SECURITY_NONE. - cpic_side_info_data.def_data.side_info.security_password
Password used to access the partner TP. This parameter
is used only if the conversation_security_type parameter is set to XC_SECURITY_PROGRAM or XC_SECURITY_PROGRAM_STRONG. - cpic_side_info_data.def_data.side_info.lu_alias
The alias of the local LU used to communicate with
the target TP. This alias is a character string using any locally
displayable characters.
Returned
Parameters: Parameter Check | |
If the verb does not execute because of a parameter error,
SNAplus2 returns the following parameters: - primary_rc
AP_PARAMETER_CHECK - secondary_rc
- AP_INVALID_LIST_OPTION
The list_options parameter was not set to a valid value.
Appendix A “Common
Return Codes” lists further
secondary return codes associated with AP_PARAMETER_CHECK,
which are common to all NOF verbs. Returned
Parameters: State Check | |
If the verb does not execute because of a state error, SNAplus2
returns the following parameters. - primary_rc
AP_STATE_CHECK - secondary_rc
- AP_INVALID_SYM_DEST_NAME
The list_options parameter was set to AP_LIST_INCLUSIVE,
to list all entries starting from the supplied name, but the sym_dest_name parameter was not valid.
Appendix A “Common
Return Codes” lists further
secondary return codes associated with AP_STATE_CHECK,
which are common to all NOF verbs. Returned
Parameters: Other Conditions | |
Appendix A “Common
Return Codes” lists further
combinations of primary and secondary return codes that are common
to all NOF verbs. |
Printable version
