DEFINE_INTERNAL_PU

The DEFINE_INTERNAL_PU verb defines a DLUR-served local PU. This verb is not used to define a local PU which is directly attached to the host. See DEFINE_LS for this purpose.

Note: The DEFINE_LS verb should be used to define the following:

A downstream PU served by:
- DLUR
- PU concentration
A local PU that is directly attached to the host

VCB Structure

typedef struct define_internal_pu
{
        unsigned short  opcode;             /* verb operation code   */
        unsigned char   attributes;         /* verb attributes       */
        unsigned char   format;             /* format                */
        unsigned short  primary_rc;         /* primary return code   */
        unsigned long   secondary_rc;       /* secondary return code */
        unsigned char   pu_name[8];         /* internal PU name      */
        INTERNAL_PU_DEF_DATA def_data;      /* defined data          */
} DEFINE_INTERNAL_PU;

typedef struct internal_pu_def_data
{
        unsigned char   description[RD_LEN];
                                            /* resource description  */
        unsigned char   dlus_name[17];      /* DLUS name             */
        unsigned char   bkup_dlus_name[17]; /* backup DLUS name      */
        unsigned char   pu_id[4];           /* PU identifier         */
        unsigned short  dlus_retry_timeout; /* DLUS retry timeout    */
        unsigned short  dlus_retry_limit;   /* DLUS retry limit      */
        unsigned char   conventional_lu_compression;
                                            /* Data compression      */
                                            /* requested for con-    */
                                            /* ventional LU sessions */
        unsigned char   conventional_lu_cryptography;
                                            /* Cryptography required */
                                            /* for conventional LU   */
                                            /* sessions              */
        unsigned char   reserv2[2]  ;         /* reserved            */
} INTERNAL_PU_DEF_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_DEFINE_INTERNAL_PU

attributes

The attributes of the verb. This field is a bit field. The first bit contains the visibility of the resource to be defined and corresponds to one of the following:

AP_EXTERNALLY_VISIBLE
AP_INTERNALLY_VISIBLE

format

Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.

pu_name

Name of the internal PU that is being defined. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.

def_data.description

Resource description (returned on QUERY_DLUR_PU and QUERY_PU). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.

def_data.dlus_name

Name of the DLUS node that DLUR will use when it initiates SSCP-PU activation. This should be set to all zeros or a 17-byte string composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) If the field is set to all zeros, the global default DLUS (if it has been defined, using the DEFINE_DLUR_DEFAULTS verb) is used in DLUR-initiated SSCP-PU activation.

def_data.bkup_dlus_name

Name of the DLUS node that will serve as the backup DLUS for this PU. This should be set to all zeros or a 17-byte string composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) If the field is set to all zeros, the global backup default DLUS (if it has been defined by the DEFINE_DLUR_DEFAULTS verb) is used as the backup for this PU.

def_data.pu_id

PU identifier. This a 4-byte hexadecimal string. Bits 0–11 are set to the Block number and bits 12–31 to the ID number that uniquely identifies the PU. This must match the pu_id configured at the host.

def_data.dlus_retry_timeout

Interval in seconds between second and subsequent attempts to contact the DLUS specified in the def_data.dlus_name and def_data.bkup_dlus_name fields. The interval between the initial attempt and the first retry is always one second. If zero is specified, the default value configured through DEFINE_DLUR_DEFAULTS is used. This field is ignored if def_data.dspu_services is not set to AP_DLUR.

def_data.dlus_retry_limit

Maximum number of retries after an initial failure to contact the DLUS specified in the def_data.dlus_name and def_data.bkup_dlus_name fields. If zero is specified, the default value configured through DEFINE_DLUR_DEFAULTS is used. If X'FFFF' is specified, the Program retries indefinitely. This field is ignored if def_data.dspu_services is not set to AP_DLUR.

def_data.conventional_lu_compression

Specifies whether data compression is requested for conventional LU sessions dependent on this PU.

AP_NO: The local node should not be compressing or decompressing data flowing on conventional LU sessions using this PU.
AP_YES: Data compression should be enabled for conventional LU sessions dependent on this PU if the host requests compression. If this value is set, but the node does not support compression (defined on the START_NODE verb) then the INTERNAL_PU is successfully defined but without compression support.

def_data.conventional_lu_cryptography

Note: This function applies only to Communications Server.

Specifies whether session level encryption is required for conventional LU sessions dependent on this PU.

AP_NONE: The local node should not be compressing or decompressing data flowing on conventional LU sessions using this PU.
AP_MANDATORY: Mandatory session level encryption is performed by APPN if an import key is available to the LU. Otherwise, it must be performed by the application that uses the LU (if this is PU Concentration, then it is performed by a downstream LU).
AP_OPTIONAL: This value allows the cryptography used to be driven by the host application on a per session basis. If the host request cryptography for a session is dependent on this PU, then the behaviour of the Program is the same for AP_MANDATORY. If the host does not request cryptography, then the behaviour is the same as AP_NONE.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:

primary_rc: AP_OK

If the verb does not execute because of a parameter error, the Program returns the following parameters:

primary_rc: AP_PARAMETER_CHECK
secondary_rc: AP_INVALID_PU_NAME
AP_INVALID_PU_ID
AP_INVALID_DLUS_NAME
AP_INVALID_BKUP_DLUS_NAME
AP_INVALID_CLU_CRYPTOGRAPHY

If the verb does not execute because of a state error, the Program returns the following parameters:

primary_rc: AP_STATE_CHECK
secondary_rc: AP_PU_ALREADY_DEFINED
AP_CANT_MODIFY_VISIBILITY

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:

primary_rc: AP_NODE_NOT_STARTED

If the verb does not execute because the node is stopping, the Program returns the following parameter:

primary_rc: AP_NODE_STOPPING

If the verb does not execute because of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR