|
|
|
|
For each MS verb, this chapter provides the following information:
Purpose and usage of the verb.
Verb Control Block (VCB) structure used by the verb. All the VCB structures are defined in the header file /usr/include/sna/ms_c.h.
Supplied parameters (VCB fields supplied to the verb). For each parameter, the following information is listed:
Description
Valid values and their meanings
Additional information where necessary
Returned parameters. When a verb completes, it contains the following returned parameters:
This parameter indicates whether the verb completed successfully. If the verb did not complete successfully, this parameter indicates a category of reasons for unsuccessful execution.
This parameter indicates a specific reason for unsuccessful execution.
In addition, some verbs have additional returned parameters.
Many of the supplied and returned parameter values are numeric. To simplify
coding, make the applications more portable, and make the program source easier
to read, these values are represented by symbolic constants defined in the
header file /usr/include/sna/ms_c.h. For example, the
opcode (operation code) parameter for the SEND_MDS_MU verb is
the value represented by the symbolic constant
Because different systems store these values differently in memory, it is important that you use the symbolic constant, and not the numeric value, when setting values for supplied parameters or when testing values of returned parameters. The value shown in the header file may not be in the format recognized by your system.
The MS 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));
This verb connects an application to a SNAP-IX node. It returns a handle that should be used on all subsequent calls to the MS entry points.
An application that only sends data using either the TRANSFER_MS_DATA verb or the SEND_MDS_MU verb and does not need to receive MS data or status indications does not need to issue this verb or supply a handle to any subsequent calls to the MS entry points.
typedef struct connect_ms_node
{
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 node_name[64]; /* Name of Node to connect to */
AP_UINT32 target_handle; /* Handle to identify Node on */
/* subsequent verbs */
} CONNECT_MS_NODE;
An application supplies the following parameters when it issues the CONNECT_MS verb:
Name of the SNAP-IX node to connect to. This is an ASCII character string.
If the application will be registering to receive NMVTs to act as a service point for an NMVT-level version of the NetView program, specify the name of a node that owns a direct connection to the NetView host (the node whose PU-SSCP session is used to transmit NMVTs to the NetView program). For more information about NMVT-level programs, see Introduction to Management Services.
If any of the following conditions is true, you can set this parameter to all binary zeros (you do not need to specify the node name):
SNAP-IX is running with all components on a single Solaris computer (not on a LAN).
The SNAP-IX LAN contains only one server.
The application is MDS-level and will be sending and receiving data in MDS_MU format and not in NMVT format.
When the SNAP-IX LAN has multiple servers and this parameter is set to all binary zeros, the application will be connected to the node on the same server as the application, if available, or to any other available node.
After the verb executes, SNAP-IX returns parameters to indicate whether the execution was successful. If the verb execution was successful, SNAP-IX also returns a target handle that the application uses on subsequent MS entry points. If the verb execution was not successful, SNAP-IX returns parameters to indicate the reason the execution was not successful.
If the verb executes successfully, SNAP-IX returns the following parameters:
AP_OK
Not used.
Returned value for use on future verbs directed to this node.
When a verb does not execute successfully, SNAP-IX returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:
AP_PARAMETER_CHECK
The node_name parameter did not match the name of any SNAP-IX node.
If the verb does not execute because of a state error, SNAP-IX returns the following parameters:
AP_STATE_CHECK
One of the following:
An error occurred in connecting to the node either because the specified node is not active or, if a null node name was specified, because no nodes are active.
The target handle used on the call to MS was not set to 0 (zero). For CONNECT_MS_NODE, the target handle must be set to 0 (zero).
The application used the synchronous entry point to issue this verb, but another synchronous verb was in progress for this target handle. Only one synchronous verb can be in progress on a particular target handle at any time.
The application used the synchronous MS entry point to issue this verb within a callback routine. The application must use the asynchronous entry point to issue any verb from a callback routine.
If the verb does not execute because the SNAP-IX software is not active, SNAP-IX returns the following parameter:
One of the following:
The SNAP-IX software has not been started or has been stopped.
The SNAP-IX software has failed.
SNAP-IX does not return a secondary_rc when the SNAP-IX software is not active.
If the verb does not execute because of a system error, SNAP-IX returns the following parameters:
An operating system call failed during processing of the verb.
The return code from the operating system call. For the meaning of this return code, check the returned value in the file /usr/include/sys/errno.h .
|
|
|
 |
|