snalu62_allocate(3) — Subroutines

NAME

snalu62_allocate − Allocates a basic or mapped conversation between a local transaction program and a remote transaction program to a session between the local LU and the remote LU. Call this verb prior to any other conversation verbs that refer to the conversation.

LIBRARY

/usr/shlib/libsnatprm.so

SYNOPSIS

#include <sna/snatprmdf.h>

STATUS_RTN snalu62_allocate(
       RES_ID ∗resource,
       TP_ID tp_id,
       STATUS_VEC status_vec,
       char ∗local_lu_name,
       char ∗remote_lu_name,
       char ∗mode_name,
       TP_NAME ∗tpn,
       UINT32 type,
       UINT32 return_control,
       UINT32 conversation_group_id,
       UINT32 sync_level,
       SECUR_INFO ∗security,
       PIP_DATA ∗pip,
       ASYNC_INFO ∗wait_object,
       BUFFER ∗luwid,
       BUFFER ∗conversation_correlator,
       SRV_INFO ∗server_info
       );

Valid Conversation States

HDX: Reset

FDX: Reset

SUPPLIED PARAMETERS

tp_id

This parameter is a place holder. The functionality represented by this parameter is not implemented.

local_lu_name

A pointer to a null-terminated ASCII string specifying either the fully-qualified network name or the locally-known alias of the local LU.

remote_lu_name

A pointer to a null-terminated ASCII string specifying either the fully-qualified network name or the locally-known alias of the remote LU.

mode_name

A pointer to a null-terminated ASCII string specifying the mode name. A mode designates the network properties of the session to be allocated for the conversation. If this parameter is NULL or contains a zero length string, then any mode group may be selected (except the SNASVCMG and CPSVCMG mode names) as long as all other allocation requirements (for example, sync_level) are met. The SNA-architected mode names, SNASVCMG and CPSVCMG, are allowed only when the type parameter indicates a basic conversation, the tpn parameter specifies an SNA services transaction program, and the calling program is a process having superuser privileges or a user listed in the system group in the etc/group file.

tpn

A pointer to a TP_NAME structure specifying the name of the remote transaction program to which this program wants to connect.

type

A UINT32 value specifying the type of conversation that the interface should allocate. Specify one of the following values:

•SNALU62_C_BASIC (the default)

•SNALU62_C_MAPPED

•SNALU62_C_FDX_BASIC

•SNALU62_C_FDX_MAPPED

return_control

A UINT32 value specifying when the interface should return control to the transaction program. Specify one of the following values:

•SNALU62_C_WHEN_SESSION_ALLOC (the default)

Specifies that the interface should allocate the conversation to a session before returning control to the program. The interface can use either a contention-winner or contention-loser session. If no session is immediately available and the session limits have not been reached, the interface activates a new session and allocates the conversation to it. If the session limits have been reached, the interface queues the allocation requests until a free session becomes available.

•SNALU62_C_IMMEDIATE

Specifies that the interface must allocate the conversation immediately. In this case, the interface must use a contention-winner session that is active and not already allocated. If no contention-winner session is available, the requests fails with a return code of SNALU62_S_UNSUC.

•SNALU62_C_WHEN_CONWINNER_ALLOC

Specifies that the interface should allocate the conversation to a contention-winner session before returning control to the program. If no contention-winner session is immediately available and the contention-winner session limit has not been reached, the interface activates a new contention-winner session and allocates the conversation to it. If the contention-winner session limit has been reached, the interface queues the allocation requests until a free contention-winner session becomes available.

•SNALU62_C_WHEN_CONV_GROUP_ALLOC

Specifies that the interface should allocate the conversation using a session having the specified conversation group ID before returning control to the program. If the indicated session is in use, the interface queues the allocation requests until the session becomes available. If the indicated session does not exist, the operation fails.

•SNALU62_C_WHEN_SESSION_FREE

Specifies that the interface should allocate the conversation to a session before returning control to the program. The interface can use either a contention-winner or contention-loser session. If no session is immediately available, the session limits have not been reached, and no other allocation requests are queued, the interface activates a new session and allocates the conversation to it. If the session limits have been reached and there are pending session activation requests, the interface queues the allocation request. If the session limits have been reached and there are no pending session activation requests, the operation fails.

conversation_group_id

A UINT32 value specifying a conversation group ID that identifies a particular session. This parameter is only valid when return_control specifies SNALU62_C_WHEN_CONV_GROUP_ALLOC. Otherwise, the interface ignores this parameter. This parameter can be retrieved by a call to either the snalu62_get_attributes or snalu62_display_mode verbs.

sync_level

A UINT32 value specifying the synchronization level that the local and remote transaction programs can use on this conversation. Specify one of the following values:

•SNALU62_C_SL_NONE (the default)

Specifies that the conversation cannot use any confirmation verbs or sync-point processing.

•SNALU62_C_SL_CONFIRM

Specifies that the conversation can use only confirmation verbs.

•SNALU62_C_SL_SYNCPT

Specifies that the conversation can use both confirmation verbs and sync-point processing.

Sync_level SNALU62_C_SL_CONFIRM is not supported for full-duplex conversations.

The interface does not fully support the synchronization level SNALU62_C_SL_SYNCPT. The transaction program is required to provide all Sync Point Services (SPS) functions (including providing an LUW identifier and conversation correlator on this verb).

security

A pointer to a SECUR_INFO structure specifying the conversation-level security verification information that the remote LU uses to validate access to the remote program and its resources.

pip

A pointer to a PIP_DATA structure specifying the Program Initialization Parameters (PIP) for the remote transaction.

wait_object

A pointer to an ASYNC_INFO structure specifying whether the interface should process the verb in a blocking or non-blocking manner.

luwid

A pointer to a BUFFER structure specifying the logical unit of work (LUW) identifier that the interface should use for this conversation. If the sync_level parameter is SNALU62_C_SL_SYNCPT, this parameter specifies the protected LUW identifier. Otherwise, this parameter specifies the unprotected LUW identifier.

conversation_correlator

A pointer to a BUFFER structure specifying the conversation correlator that the interface should use for this conversation.

server_info

A pointer to a SRV_INFO structure specifying the LU6.2 Server to use. Specify sufficient information to uniquely identify the LU6.2 Server. If this parameter is not specified, the interface tries to connect to a local server with the name LU62_SRV.

RETURNED PARAMETERS

resource

A pointer to a RES_ID structure to receive an ID structure assigned to the conversation by the interface. Supply this ID on all subsequent verb calls for this conversation.

status_vec

A pointer to a STATUS_VEC array to receive the completion status information.

DESCRIPTION

By default, snalu62_allocate attempts to allocate an active available LU6.2 session for the conversation. If such a session does not exist and the remote LU/mode pair can support another session, snalu62_allocate attempts to establish an LU6.2 session. The session limit for the remote LU/mode pair must have been negotiated prior to calling this verb.

Use the returned resource ID in all subsequent conversation verbs for this conversation.

RESTRICTIONS

None

RETURN VALUES

SNALU62_S_OKnormal successful completion

SNALU62_S_ALLERR
conversation could not be allocated

SNALU62_S_CONVCANC
conversation canceled

SNALU62_S_OPINCOMP
non-blocking operation not completed

SNALU62_S_OPNOTACC
non-blocking operation not accepted

SNALU62_S_PARERR
parameter error, function-name

SNALU62_S_PRGPARCHK
program parameter check

SNALU62_S_UNSUC
verb did not execute successfully

ERRORS