|
|
|
|
This chapter provides the following information for each NOF API verb:
Description of the verb's purpose and usage
Whether the verb can be issued to an active node, an inactive node, the domain configuration file, or the SNA network data file (unless otherwise stated, verbs may be issued either to an active node or to an inactive node)
Verb control block (VCB) structure, as defined in the NOF API header file /usr/include/sna/nof_c.h
Parameters supplied to the verb by the application
Parameters returned to the application
Error return codes for unsuccessful execution
Most parameters supplied to and returned by the NOF interface 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 NOF header file nof_c.h. For example,
the opcode parameter of the ACTIVATE_SESSION 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.
The error return codes described in this chapter are specific to each verb. Additional return codes, which are common to all NOF API verbs, are described in Common Return Codes.
NOF API indications, which the application can accept by registering using the REGISTER_INDICATION_SINK verb, are described separately in NOF Indications.
The NOF 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(nofvcb, 0, sizeof(nofvcb));
The ACTIVATE_SESSION verb requests SNAP-IX to activate a session between
the local LU and a specified partner LU, using a specified mode. You must
issue an INITIALIZE_SESSION_LIMIT verb before issuing an ACTIVATE_SESSION
verb, unless cnos_permitted is set to
This verb must be issued to a running node.
typedef struct activate_session
{
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 lu_name[8]; /* local LU name */
unsigned char lu_alias[8]; /* local LU alias */
unsigned char plu_alias[8]; /* partner LU alias */
unsigned char mode_name[8]; /* mode name */
unsigned char fqplu_name[17]; /* fully qualified partner LU name */
unsigned char polarity; /* requested session polarity */
unsigned char session_id[8]; /* session ID */
unsigned char cnos_permitted; /* is implicit CNOS permitted? */
unsigned char reserv4[15]; /* reserved */
} ACTIVATE_SESSION;
The application supplies the following parameters:
LU name of the local LU, as defined to SNAP-IX. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 bytes. To indicate that the LU is defined by its LU alias instead of its LU name, set this parameter to 8 binary zeros.
LU alias of the local LU, as defined to SNAP-IX. This is an 8-byte ASCII string, using any locally displayable characters, padded on the right with spaces if the name is shorter than 8 bytes. This parameter is used only if lu_name is set to zeros.
If both the LU name and the LU alias are set to all zeros, the verb is forwarded to the LU associated with the CP (the default LU).
LU alias of the partner LU. This is an 8-byte ASCII string, using any locally displayable characters, padded on the right with spaces if the name is shorter than 8 bytes. To indicate that the partner LU is defined by its fully qualified LU name instead of its LU alias, set this parameter to 8 binary zeros.
Name of the mode to be used by the LUs. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces if the name is shorter than 8 bytes.
Fully qualified LU name for the partner LU, as defined to SNAP-IX. This parameter is used only if the plu_alias field is set to zeros; it is ignored if plu_alias is specified.
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.
The polarity for the session. Possible values are:
If
Indicates that CNOS processing is permitted. Possible values are:
CNOS processing is permitted.
CNOS processing is not permitted.
If the activation of a new session is not possible because the session
limits for the specified mode are reset, and this parameter is set to
If the verb executes successfully, SNAP-IX returns the following parameters:
AP_OK
Possible values are:
The session was activated successfully; the session limit defined for the mode was negotiated during the activation process.
The session was activated successfully; the session limit was not changed.
The 8-byte identifier of the activated session.
If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:
AP_PARAMETER_CHECK
Possible values are:
The session cannot be activated, because this would exceed the current session limit for this LU-LU-mode combination.
The lu_alias parameter did not match any defined local LU alias.
The lu_name parameter did not match any defined local LU name.
The fqplu_name parameter did not match any defined partner LU name, or the plu_alias parameter did not match any defined partner LU name.
The value specified in the cnos_permitted parameter was not valid.
Common Return Codes lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.
If the verb does not execute because of other errors, SNAP-IX returns one of the following parameters.
Possible values are:
The session could not be activated because of a condition that requires action (such as a configuration mismatch or a session protocol error). Check the SNAP-IX log file for information about the error condition, and correct it before retrying this verb.
The session could not be activated because of a temporary condition (such as a link failure). Retry the verb, preferably after a timeout to allow the condition to clear. Check the SNAP-IX log file for information about the error condition.
Common Return Codes lists further combinations of primary and secondary return codes that are common to all NOF verbs.
|
|
|
 |
|