DEFINE_LOCAL

The DEFINE_LOCAL_LU verb defines a new local LU. It can also be used to modify the attach routing data or description of an existing LU (or of the default LU associated with the local node's Control Point), but not any of the other parameters; when modifying an existing LU, all the other parameters must be set to their currently defined values.

VCB Structure

typedef struct define_local_lu
{
   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                  */
   LOCAL_LU_DEF_DATA    def_data;          /* defined data                   */
} DEFINE_LOCAL_LU;

typedef struct local_lu_def_data
{
   unsigned char    description[32];       /* resource description           */
   unsigned char    reserv1;               /* reserved                       * 
   unsigned char    security_list_name[14] /* security access list name      */
   unsigned char    lu_alias[8];           /* local LU alias                 */
   unsigned char    nau_address;           /* NAU address                    */
   unsigned char    syncpt_support;        /* is Syncpoint supported?        */
   AP_UINT16        lu_session_limit;      /* LU session limit               */
   unsigned char    default_pool;          /* is LU in the pool of default   */
                                           /*  LUs?                          */
   unsigned char    reserv2;               /* reserved                       */
   unsigned char    pu_name[8];            /* PU name                        */
   unsigned char    lu_attributes;         /* LU attributes                  */
   unsigned char    sscp_id[6]             /* SSCP ID                        */
   unsigned char    disable;               /* disable or enable local LU     */
  ROUTING_DATA      attach_routing_data;   /* routing data for incoming      */
                                           /* attaches                       */
} LOCAL_LU_DEF_DATA;

typedef struct routing_data
{
   unsigned char    sys_name[64];          /* Name of target system for TP   */
   signed long      timeout;               /* timeout value in seconds       */
   unsigned char    back_level;            /* is target system back-level?   */
   unsigned char    reserved[59];          /* reserved                       */
} ROUTING_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_DEFINE_LOCAL_LU

lu_name

Name of the local LU. This is an 8-byte type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces.

To modify the attach routing data or description of the default LU associated with the local node's Control Point, set this parameter to 8 binary zeros.

def_data.description

A null-terminated text string (0-31 characters followed by a null character) describing the local LU. This string is for information only; it is stored in the node's configuration file and returned on the QUERY_LOCAL_LU verb, but SNAplus2 does not make any other use of it.

def_data.security_list_name

Name of the security access list used by this local LU (defined using the DEFINE_SECURITY_ACCESS_LIST verb). This parameter restricts the use of the LU to only the users named in the specified list. To specify that the LU is available for use by any user, set this parameter to 14 binary zeros.

def_data.lu_alias

Alias of the local LU. This is an 8-byte ASCII string, using any locally displayable characters, padded on the right to 8 bytes if necessary.

def_data.nau_address

Network accessible unit address of the LU. Specify zero if the LU is an independent LU, or an address in the range 1-255 if the LU is a dependent LU.

def_data.syncpt_support

Specifies whether the LU supports Syncpoint functions. Set this to AP_YES only if you have a Sync Point Manager (SPM) and Conversation Protected Resource Manager (C-PRM) in addition to the standard SNAplus2 product. Possible values are:

AP_YES: Syncpoint is supported.
AP_NO: Syncpoint is not supported.

def_data.lu_session_limit

The maximum total number of sessions (across all modes) supported by the LU.

For a dependent LU, this must be set to 1. For an independent LU, specify zero for no limit, or a value in the range 1-65,535. If you specify an explicit limit, note the following:

If the LU will be communicating with parallel-session remote LUs, the session limit must include sufficient sessions for CNOS negotiation; a safe minimum is 3, or an additional 2 sessions for each partner LU.
The LU session limit must be greater than or equal to the sum of the session limits for all modes that the LU will use.

def_data.default_pool

Specifies whether the LU is in the pool of default dependent LUs. For more information, see “Default LUs”. Possible values are:

AP_YES: The LU is in the pool of default LUs, and can be used by applications that do not specify an LU name.
AP_NO: The LU is not in the pool.

If the LU is an independent LU, this parameter is reserved.

def_data.pu_name

Name of the PU which this LU will use, as specified on the DEFINE_LS verb. This field is used only by dependent LUs, and should be set to 8 binary zeros for independent LUs. The name is an 8-byte type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces if necessary.

def_data.lu_attributes

Identifies additional information about the LU. Possible values are:

AP_NONE: No additional information identified.
AP_DISABLE_PWSUB: Disable password substitution support for the local LU.

def_data.sscp_id

Specifies the ID of the SSCP permitted to activate this LU. This ID is a 6-byte binary string. This parameter is used only by dependent LUs, and is set to all binary zeros if the LU is an independent LU or if the LU can be activated by any SSCP.

def_data.disable

Specifies whether the local LU should be disabled or enabled. Possible values are:

AP_YES: Disable the local LU.
AP_NO: Enable the local LU.

def_data.attach_routing_data.sys_name

The name of the target computer for incoming Allocate requests (requests from a partner TP to start an APPC or CPI-C conversation) that arrive at this local LU.

If the target TP is a broadcast queued TP (that is, servers are informed of its location when it starts, so that they can route incoming Allocate requests to it), or if it always runs on the same SNAplus2 server as the node that owns this LU, set this parameter to binary zeros. Otherwise, set it to the name of the computer where the TP runs.

def_data.attach_routing_data.timeout

The timeout value for dynamic load requests. A request will time out if the invoked TP has not issued a Receive_Allocate verb (APPC), or Accept_Conversation or Accept_Incoming (CPI-C), within this time. Specify the timeout value in seconds, or -1 to indicate no timeout (dynamic load requests will wait indefinitely).

def_data.attach_routing_data.back_level

Specifies whether the target computer specified by the sys_name parameter above is a back-level computer. This parameter is used only when you are in the process of migrating a client-server SNAplus2 system to a later version, so that not all servers and clients on the system are running the same version; it is reserved otherwise.

If both the node that owns this LU and the target system are running the same version of SNAplus2, set this parameter to AP_NO.

If the node that owns this LU is running the newer version of SNAplus2, but the target system is running the older version, set this parameter to AP_YES. When you upgrade the target system later, change this parameter back to AP_NO.

Returned Parameters: Successful Execution

If the verb executes successfully, SNAplus2 returns the following parameters:

primary_rc: AP_OK

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

Possible values are:

AP_INVALID_LU_NAME: The supplied LU name contained a character that was not valid.
AP_INVALID_NAU_ADDRESS: The supplied NAU address was not in the valid range.
AP_INVALID_SESSION_LIMIT: The supplied session limit was not in the valid range.
AP_INVALID_TIMEOUT: The supplied timeout value was not in the valid range.

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

Possible values are:

AP_INVALID_LU_NAME: The lu_name or lu_alias parameter contained a character that was not valid.
AP_LU_ALREADY_DEFINED: An LU with this name has already been defined. You cannot use this verb to modify any parameters of an existing LU except the attach routing data.
AP_PU_NOT_DEFINED: The pu_name parameter did not match any defined PU name.
AP_LU_ALIAS_ALREADY_USED: An LU with this alias has already been defined. You cannot use this verb to modify any parameters of an existing LU except the attach routing data.

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.

Default LUs

You can set up the configuration of local LUs so that applications do not have to specify an LU name explicitly when starting a conversation; the node will select a suitable default LU for the application to use. The method for doing this depends on whether the applications require dependent or independent LUs, as follows. You cannot provide this facility for both dependent and independent LUs.

If the applications require dependent LUs, use the default_pool parameter on DEFINE_LOCAL_LU for one or more dependent LUs, to specify that they can be used as default LUs. When an application attempts to start a conversation without specifying a local LU name, SNAplus2 will select an unused LU from the pool of LUs defined as default LUs.
You can define LUs on more than one node as default LUs. An application requesting a default LU may be assigned to any of these LUs as available; there is no requirement for the LU to be on the same computer as the application. However, if you are defining partner LUs for the applications, these must be defined on all nodes where default LUs are defined (so that the application can contact the correct partner LU using any of the default local LUs).
If the applications require independent LUs, do not use the default_pool parameter to define any local LUs as default LUs. In this case, an application requesting a default LU will be assigned to the LU associated with a local node's CP (this is an independent LU automatically defined by SNAplus2 for each node).

DEFINE_LOCAL_LU

Technical documentation

» Table of Contents

» Index