ATBALC2 - Allocate (For MVS/ESA 4.3 through OS/390 Release 7)

Equivalent to:

LU 6.2 (MC_)Allocate
CPI Initialize_Conv (CMINIT) and Allocate (CMALLC)

This section describes the Allocate (ATBALC2) TP callable service provided with MVS/ESA Version 4 Release 3. The Allocate service was enhanced for OS/390 Release 8, and renamed ATBALC5 (see ATBALC5 - Allocate (For OS/390 Release 8 through z/OS V1R6)). The Allocate service was further enhanced for z/OS V1R7, and renamed ATBALC6 (see Allocate). The ATBALC2 and ATBALC5 calls remain valid, but do not contain the enhancements included in ATBALC6.

Note: The ATBALC6 call is the recommended programming interface for this service.

Allocates a session between the local LU and a partner LU, and on that session allocates a basic or mapped conversation between the local program and a partner program. A conversation ID is assigned to the conversation. Call this service before other calls that refer to the conversation.

If the program that issues the allocate call was not started by APPC/MVS in response to an inbound allocate call, and is not associated with an alternative transaction scheduler, the outbound allocate call and ensuing conversation flow through the base LU for the APPC/MVS transaction scheduler. If, in such a case, there is no base LU defined for the APPC/MVS transaction scheduler, APPC/MVS uses the system base LU. If there is no system base LU, APPC/MVS rejects the allocate request. For more information about base LUs and their definition, see z/OS MVS Planning: APPC/MVS Management.

Requirements

Authorization:

Supervisor state or problem state, any PSW key, with the following exceptions:

When the TP_name specified is an SNA TP name beginning with X'06', the caller must run either in supervisor state, or with PSW key 0-7.
When the TP_id specified is a value other than binary zeros, the caller must run either in supervisor state, or with PSW key 0-7.

Dispatchable unit mode:

Task or SRB mode, with the following exception: task mode only for callers that issue Allocate for a conversation with a synchronization level of Syncpt.

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31-bit

ASC mode:

Primary or access register (AR)

Interrupt status:

Enabled for I/O and external interrupts

Locks:

Unlocked

Control parameters:

All parameters must be addressable by the caller and in the primary address space.

Format

Figure 1. ATBALC2 - LU 6.2 Allocate

CALL ATBALC2(
        Conversation_type,
        Sym_dest_name,
        Partner_LU_name,
        Mode_name,
        TP_name_length,
        TP_name,
        Return_control,
        Sync_level,
        Security_type,
        User_ID,
        Password,
        Profile,
        User_Token,
        Conversation_ID,
        Notify_type,
        TP_ID,
        Local_LU_name,
        Return_code
       );

Parameters

Conversation_type

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Conversation_type specifies the type of conversation on which the service is invoked.

Valid values for this parameter are:

Value: Meaning
0: Basic_conversation
Specifies that in this conversation, the TPs will format their data into separate records, with record length and data specified, before sending it.
1: Mapped_conversation
Specifies that in this conversation, the TPs will rely on APPC to format the data that the TPs send.

Sym_dest_name

Supplied parameter

Type: Character string
Char Set: 01134
Length: 8 bytes

Specifies a symbolic name representing the partner LU, the partner TP_name, and the mode name for the session on which the conversation is to be carried. The symbolic destination name must match that of an entry in the side information data set. The appropriate entry in the side information is retrieved and used to initialize the characteristics for the conversation.

If you specify a symbolic destination name, the partner LU name, mode name, and TP name are obtained from the side information. If you also specify values for the Partner_LU_name, Mode_name, or TP_name parameters on the Allocate service, these values override any obtained from the side information.

The symbolic destination name in this field can be from 1 to 8 characters long, with characters from character set 01134. If the symbolic destination name is shorter than eight characters, it must be left-justified in the variable field, and padded on the right with blanks. To not specify a symbolic destination name, set the sym_dest_name parameter value to 8 blanks and provide values for the Partner_LU_name, Mode_name, and TP_name parameters.

Partner_LU_name

Supplied parameter

Type: Character string
Char Set: Type A
Length: 17 bytes (must be padded with blanks if less than 17 bytes)

Partner_LU_name specifies the name of the LU at which the partner program is located.

The Partner_LU_name is any name by which the local LU knows the partner LU for the purposes of allocating a conversation. The local LU transforms this locally known LU name to an LU name used by the network.

The Partner_LU_name can be one of the following:

LU name only (1-8 byte Type A character string).
This string represents the network LU name, which, if unique within the network and interconnected networks, is sufficient for most TP communications.

IBM recommends, however, that you specify either a symbolic destination name (in the Sym_dest_name parameter), or the network-qualified LU name, if known. While the network LU name might be unique currently, it might not remain so if the installation increases the number of networks in use. Specifying a symbolic destination name or network-qualified LU name can minimize the need for future network definitions and program changes.
A VTAM generic resource name.
If the partner LU is a member of a generic resource group, you may specify the 1- to 8-byte generic resource name of the group.
Combined network_ID and network LU name (two 1-8 byte Type A character strings, concatenated by a period: network_ID.network_LU_name).
This format is known as a network-qualified LU name; each LU in the network and all interconnected networks can be uniquely identified by its network-qualified LU name. The network-LU-name portion may be a VTAM generic resource name, or a specific LU name. If the local LU is not enabled to support network-qualified names, APPC/MVS passes only the network-LU-name portion to VTAM, which might cause an error if the network LU name is not unique across networks.
A value of 17 blanks:
If you specify a symbolic destination name in Sym_dest_name parameter, set Partner_LU_name to blanks to use the partner LU name from the side information.

If you do not specify a symbolic destination name, then use a blank Partner_LU_name to indicate that the partner program is located at the same LU as the local program (LU=OWN). If the local LU is defined as a member of a VTAM generic resource group, APPC/MVS uses the generic resource name for Partner_LU_name.

Mode_name

Supplied parameter

Type: Character string
Char Set: Type A
Length: 8 bytes (must be padded with blanks if less than 8 bytes)

Mode_name specifies the mode name designating the network properties for the session to be allocated for the conversation. The network properties include, for example, the class of service to be used.

The mode name value of "SNASVCMG" is reserved for use by APPC/MVS. If a mode name of "SNASVCMG" is specified on the Allocate service, the request is rejected with a return code of parameter_error.

If you specify a symbolic destination name in the sym_dest_name parameter, set mode_name to blanks to obtain the mode_name from the side information.

If you do not specify a sym_dest_name and do not specify a mode name, APPC/MVS uses the default mode name "ATB#MODE".

TP_name_length

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

TP_name_length specifies the length of data contained in the TP_name parameter.

If you specify a symbolic destination name in the sym_dest_name parameter, set TP_name_length to 0 to use the partner TP name from the side information.

TP_name

Supplied parameter

Type: Character string
Char Set: 006409 (Type A if the partner TP is protected by RACF)
Length: 1-64 bytes

TP_name specifies the name of the partner program to be connected at the other end of the conversation.

If you specify a symbolic destination name in the sym_dest_name parameter and set the TP_name_length parameter to zero, the TP name is obtained from the side information file.

TP_name can specify the name of any SNA service transaction program except for one whose first character is X'06'; see the authorization requirements in Requirements for more information about this exception. The names of SNA service transaction programs can contain blank characters. For a list of SNA service transaction programs, see SNA Transaction Programmer's Reference Document for LU 6.2.

If the partner TP is to be protected by a RACF security profile in the APPCTP class, the TP_name must consist of Type A characters only.

Return_control

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Return_control specifies when the local LU is to return control to the local program, in relation to the allocation of a session for the conversation.

Valid values for this parameter are:

Value: Meaning
0: When_session_allocated
Specifies to allocate a session for the conversation before returning control to the program. An error in allocating a session is reported on this call.
1: Immediate
Specifies to allocate a session for the conversation if a session is immediately available, and return control to the program with a return code indicating whether a session is allocated. An error in allocating a session that is immediately available is reported on this call.
100: When_conwinner_allocated
Specifies to allocate a session in which the local LU is the contention winner, before returning control to the program. As contention winner, the LU avoids having to compete with the partner LU to establish the session, thus potentially saving network traffic. An error in allocating a contention winner session for the conversation is reported on this call.

Sync_level

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Sync_level specifies the synchronization level that the local and partner programs can use on this conversation.

Valid values for this parameter are:

Value: Meaning
0: None
Specifies that the programs will not perform confirmation processing on this conversation. The programs will not call any services and will not recognize any returned parameters relating to confirmation.
1: Confirm
Specifies that the programs can perform confirmation processing on this conversation. The programs can call services and will recognize returned parameters relating to confirmation.
2: Syncpt
Specifies that the programs can perform sync point processing on this conversation. The programs can call services and will recognize returned parameters relating to sync point processing.

Security_type

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Security_type specifies the type of access security information that the partner LU uses to verify the identity of the end-user and validate access to the partner program and its resources.

Valid values for this parameter are:

Value

Meaning

100

Security_none

Specifies to omit access security information on this allocation request.

101

Security_same

Specifies to use the same user ID that is associated with the current program the Allocate service is issued from. The password (if present) is not used; instead, the user ID is indicated as being already verified. If the allocation request that initiated execution of the local program contained no security information, security information is omitted on this allocation request. APPC can retrieve the security information from a number of different places. If the user is authorized and the user specifies a valid User_Token parameter, APPC will use this to obtain the appropriate security information (a user ID and possible profile name). If this is not specified, APPC will send the user ID associated with the current application context environment, if this is available. Otherwise, APPC will send the user ID and possible profile name that is associated with the current executing task, or if unavailable, from the current address space.

102

Security_pgm

Specifies to use the access security information that the local program provides on the call. The local program provides the information by means of the User_ID, Password, and Profile parameters. These values are passed exactly as specified, without folding to uppercase.

Normally, User_ID and Password are required parameters for this Security_type. However, the User_ID parameter can be specified without the Password parameter if, on the local system, the user ID of the issuing address space has been granted surrogate authorization for the specified User_ID. In RACF terms, this requires READ access to the ATBALLC.userid profile (or a generic profile) in the SURROGAT class, where userid is the value specified on the User_ID parameter. If surrogate authorization is granted, the user ID specified on the call will be sent and will be indicated as being already verified. For general information on surrogate user IDs, see z/OS Security Server RACF Security Administrator's Guide. For specific information about ATBALLC.userid profiles, see z/OS MVS Planning: APPC/MVS Management.

Note: If the surrogate authorization is used, the specified User_ID must be a valid MVS user ID. For example, it cannot be longer than 8 characters.

User_ID

Supplied parameter

Type: Character string
Char Set: No restriction (Type A if APPC/MVS manages the partner LU)
Length: 10 bytes

Specifies the user ID. The partner LU uses this value and the password to verify the identity of the end user that initiated the allocation request. The partner LU may use this value for auditing and accounting purposes, and, together with the security profile (if present), to determine which partner programs the local program can access.

When the partner LU is on MVS with RACF protection, the user ID must be 1-8 alphanumeric characters.

This parameter is significant only when the Security_type parameter contains a value of Pgm. Otherwise, this parameter has no meaning and is ignored.

Password

Supplied parameter

Type: Character string
Char Set: No restriction (Type A if APPC/MVS manages the partner LU)
Length: 10 bytes (must be left-justified and padded with blanks if less than 10 bytes)

Specifies the password. The partner LU uses this value and the user ID to verify the identity of the end user that made the allocation request. When the partner LU is on MVS with RACF protection, the password must be 1-8 alphanumeric characters padded with blanks.

This parameter is significant only when the Security_type parameter contains a value of Pgm. Otherwise, this parameter has no meaning and is ignored.

Profile

Supplied parameter

Type: Character string
Char Set: No restriction (Type A if APPC/MVS manages the partner LU)
Length: 10 bytes

Profile specifies additional security information that may be used to determine what partner programs the local program may access, and which resources the local program may access. When the partner LU is on MVS with RACF protection, APPC/MVS treats the profile name as a RACF group name for verifying access to partner programs. The profile name must be 1-8 alphanumeric characters.

This parameter is significant only when the Security_type parameter contains a value of Pgm. Otherwise, this parameter has no meaning and is ignored.

User_Token

Supplied parameter

Type: Structure
Char Set: N/A
Length: 1-255 bytes

User_Token specifies the RACF UTOKEN which identifies the user requesting the Allocate. Only programs running in supervisor state or PSW key 0-7 can specify a User_Token. To not specify a User_Token, pass a field whose first byte contains a hexadecimal zero (X'00').

If a RACF UTOKEN is supplied, APPC/MVS uses it to obtain the appropriate security information only when you specify a Security_Type of Security_Same. In that case, APPC/MVS obtains the user ID and RACF group name from the UTOKEN. This parameter will not be consulted if Security_Type is Security_None or Security_Pgm.

Conversation_id

Returned parameter

Type: Character string
Char Set: No restriction
Length: 8 bytes

Conversation_id, sometimes called the resource identifier, identifies a conversation to the system.

Notify_type

Supplied parameter

Type: Structure
Char Set: N/A
Length: 4-8 bytes

Specifies the type of processing and notification (synchronous or asynchronous) requested for this service. Programs can request asynchronous processing, which returns control to the program immediately and later notifies the program by ECB when the service is complete. The possible types are:

None
No notification is requested. The service is performed synchronously, and control is returned to the caller when processing is complete. All returned parameters are set on return to the caller. To specify no notification, set the parameter value to a four-byte structure containing binary zeros.
ECB
Programs can request asynchronous processing by specifying an ECB to be posted when processing completes. To specify an ECB, set the parameter to an eight-byte structure containing a fullword binary one (X'00000001') followed by the address of a fullword area to be used as the ECB. The ECB must reside in the home address space.

When you specify an ECB, control is returned before processing is complete, with only the return code set. If the asynchronous request was accepted, the return code is set to 0 to indicate that the service is being processed asynchronously. Other returned parameters are filled in during asynchronous processing, and the specified ECB is posted when all returned parameters are set. The completion code field in the ECB contains the return code for the service.

Note: As of MVS/ESA SP 4.2.2, unauthorized callers can specify a Notify_type of ECB on calls to Allocate. With MVS/ESA SP 4.2, unauthorized callers cannot specify a Notify_type of ECB.

TP_ID

Supplied parameter

Type: Character string
Char Set: No restriction
Length: 8 bytes

Allows authorized TPs to designate the transaction program instance with which this conversation should be associated. (See Requirements for more information about specific authorization requirements.) Unauthorized TPs must set this parameter to binary zeros, which causes the TP_ID assignment to occur automatically and transparently to the transaction program.

Advanced TPs that run in supervisor state or PSW key 0-7 can select the TP_ID assigned. See the Define_Local_TP callable service description in z/OS MVS System Messages, Vol 3 (ASB-BPX) for information on how to create a new TP_ID.

Local_LU_name

Supplied parameter

Type: Character string
Char Set: Type A
Length: 8 bytes

Local_LU_name specifies the name of the local LU from which the caller's allocate request is to originate. The ability to specify the local LU name allows the caller to associate its outbound conversations with particular LUs. You cannot specify a VTAM generic resource name for the local LU name.

The caller's address space must have access to the named LU. Otherwise, a parameter_error return code is returned. Use Table 1 to determine whether you can specify a particular local LU.

Table 1. Local LUs for Which an Address Space Can Allocate
		LU Specified
		System Base LU, NOSCHED¹	System Base LU, ASCH¹	NOSCHED LU	ASCH LU	Scheduler 2 LU
Address Space Doing Allocate	*From an Address Space Not Connected to a Scheduler*	OK	OK	OK	NO²	NO²
	*From an Address Space Connected to ASCH*	OK	OK	OK	OK	NO²
	*From an Address Space Connected to Scheduler 2*	OK	NO²	OK	NO²	OK
	*From an Address Space Not Connected to a Scheduler with Prohibit Default LU Specified⁴*	NO³	NO³	NO³	NO³	NO³
Note: Columns 1 and 2 are mutually exclusive. The system returns a Parameter_error return code to the caller. If the specified LU is not defined, the system also returns a Product_specific_error return code to the caller. The system returns a Product_specific_error return code to the caller. For information about how to prohibit the use of a default LU for an address space, see the description of the Set_AS_Attributes service in z/OS MVS System Messages, Vol 3 (ASB-BPX).

If the caller sets local_LU_name to blanks, the system uses the following hierarchy to select an LU for the conversation:

The LU associated with the transaction program
If no LU is associated with the TP, the system uses the base LU for the transaction scheduler associated with the caller's address space.
If no transaction scheduler is associated with this address space, the system uses the system base LU, which is either:
- An LU defined with the NOSCHED and BASE parameters, or
- If a base NOSCHED LU is not defined, the LU defined as the base LU for the APPC/MVS transaction scheduler.
If no system base LU is defined, the system rejects the Allocate call.

For more information about base LUs and their definitions, see z/OS MVS Planning: APPC/MVS Management.

Table 2 shows which LU is used by default.

Table 2. Default Local LUs Used If None Are Specified
Program Calling Allocate Service	Base LUs exist
Program Calling Allocate Service	*nosched*	*ASCH*	*Sched 2*	*nosched, ASCH*	*nosched, Sched 2*	*ASCH, Sched 2*	*nosched, ASCH, Sched 2*
*From an Address Space Not Connected to a Scheduler*	nosched	asch	NO¹	nosched	nosched	asch	nosched
*From an Address Space Not Connected to a Scheduler but with prohibit default LU specified*	NO¹	NO¹	NO¹	NO¹	NO¹	NO¹	NO¹
*From an Address Space Connected to ASCH*	N/A	N/A	N/A	N/A	N/A	N/A	N/A
*From an Address Space Connected to ASCH and with prohibit default LU specified*	N/A	N/A	N/A	N/A	N/A	N/A	N/A
*From an Address Space Connected to Scheduler 2*	nosched	NO¹	Sched 2	nosched	Sched 2	Sched 2	Sched 2
*From an Address Space Connected to Scheduler 2 and with prohibit default LU specified*	NO¹	NO¹	Sched 2	NO¹	Sched 2	Sched 2	Sched 2
Note: A Product_Specific_Error return code is returned if no base LU exists.

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Return_code specifies the return code that is returned to the local program. In cases where an error code is returned, the program should not examine any other returned variable associated with the call because nothing is placed in the variables.

When APPC/MVS returns an error return code to Allocate, your TP:

Can use the conversation ID returned on the Conversation_ID parameter as input to the Error_Extract service (which returns detailed information about error return codes)
Should not examine any other returned parameter associated with the call because no values are placed in the parameters.

An allocation error resulting from the local LU's failure to obtain a session for the conversation is reported on this call. An allocation error resulting from the partner LU's rejection of the allocation request is reported on a subsequent call.

See Return Codes for descriptions of return codes that can be returned to a caller of Allocate.

Return Codes

If the Return_control parameter contains a value of When_session_allocated or When_conwinner_allocated, possible values of Return_code are:

Decimal Value: Meaning
0: OK
1: Allocate_failure_no_retry
2: Allocate_failure_retry
7: Sync_lvl_not_supported_lu
19: Parameter_error
20: Product_specific_error
24: Program_parameter_check
25: Program_state_check

If the Return_control parameter contains a value of Immediate, possible values of Return_code are:

Decimal Value: Meaning
0: OK
7: Sync_lvl_not_supported_lu
19: Parameter_error
20: Product_specific_error
24: Program_parameter_check
25: Program_state_check
28: Unsuccessful

The following table describes all of the possible return codes for Allocate:

Table 3. Return Codes for the Allocate Service
Return Code	Value, Meaning, and Action
0	Value: OK Meaning: The call completed successfully. System Action: If the call specified a Notify_type of ECB, APPC/MVS posts the ECB specified on the Notify_type parameter when APPC/MVS finishes processing the call asynchronously. Application Programmer Response: None required.
1	Value: Allocate_failure_no_retry Meaning: A TP submitted an allocate request. The request specified a value on the Return_control parameter that was other than Immediate. One of the following occurred: Virtual telecommunications access method (VTAM) could not establish a session with the partner LU. APPC/MVS could not establish a conversation. System Action: The system returns this return code to the caller of Allocate. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format. If the conversation is not LU=LOCAL, see z/OS Communications Server: SNA Programmer's LU 6.2 Guide for a description of the sense codes included in the message from Error_Extract. If the error persists, or if the conversation is LU=LOCAL, verify that the name specified on the Local_LU_name parameter is correct. If the name is correct, contact the system programmer. System Programmer Response: At the request of the application programmer, ensure that the local LU is defined correctly in the VTAM application (APPL) statement in SYS1.VTAMLST.
2	Value: Allocate_failure_retry Meaning: A TP submitted an allocate request. The request specified a value on the Return_control parameter that was other than Immediate. The system cannot allocate the conversation because of a condition that might be temporary. System Action: The system returns this return code to the caller of Allocate. Application Programmer Response: Retry the allocate request.
7	Value: Sync_lvl_not_supported_lu Meaning: A TP submitted an Allocate request with a synchronization level that is not supported by the partner LU. System Action: The system returns this return code to the caller of the Allocate call. Application Programmer Response: Ensure that the partner LU supports the receipt of conversations with a synchronization level of syncpt.
19	Value: Parameter_error Meaning: A local TP called an APPC service. A parameter specified on the call is not valid. The error could be one of the following: The TP name is not 1 to 64 characters long. Either the SYMDEST name or the TP name length were not specified. SNASVCMG is specified as mode name. X'0E' or X'0F' was used as the first character of a TP name. X'06' was used as the first character of a TP name by a caller that was not running either in supervisor state or with PSW key 0-7. An SNA service TP name is used with a mapped conversation verb. The partner LU name was not valid. The mode name was not valid. The local LU name specified is either undefined or not allowed; for example, the TP might have specified a VTAM generic resource name, which is valid only for partner LU names. System Action: The system returns this return code to the caller of Allocate. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.
20	Value: Product_specific_error Meaning: The system found a product-specific error. System Action: The system might write symptom records, which describe the error, to the logrec data set. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format. If necessary, see Diagnosing Product-Specific Errors for more information about product-specific errors.
24	Value: Program_parameter_check Meaning: The local TP called an APPC service. One of the following errors occurred in one or more parameters specified on the call: An unauthorized caller passed a non-zero TP_ID. For a Security_type of Security_pgm, both the user ID and password were not specified. For a Security_type of Security_pgm, a user ID was specified with a blank password, or a password was specified with a blank user ID. The SYMDEST name was not found in the side information. The specified TP_ID is not associated with the address space. An unauthorized caller specified a UTOKEN that was non-zero. The specified local LU does not support protected conversations (conversations with a synchronization level of syncpt). System Action: The system returns this return code to the caller of Allocate. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.
25	Value: Program_state_check Meaning: For a conversation with sync_level set to SYNCPT, the conversation's context (unit of work) is in the Backout-Required condition. New protected conversations cannot be allocated for a context in this condition. System Action: The conversation allocation request fails. A new conversation is not allocated. Application Programmer Response: Backout the current unit of recovery associated with the transaction program's context.
28	Value: Unsuccessful Meaning: The request specified an allocate_type of Immediate. One of the following occurred: APPC/MVS could not establish a session with the partner LU Virtual telecommunications access method (VTAM) could not establish a conversation. System Action: The system returns this return code to the caller of the APPC service in error. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.

For more detailed information about these return codes, refer to Explanations of Return Codes for CPI Communications Services.

Restrictions

Transaction programs that call the Allocate service while in task mode should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the section on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.