|
Equivalent to: - LU 6.2 (MC_)Allocate
- CPI Initialize_Conv (CMINIT) and Allocate (CMALLC)
This section describes the Allocate (ATBALC5) TP callable
service provided with OS/390 Release 8. The Allocate service was enhanced
for z/OS V1R7, and renamed ATBALC6 (see Allocate). The ATBALC5 call remains valid, but does 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
Variable |
Value |
---|
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. ATBALC5 - LU 6.2 AllocateCALL ATBALC5(
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,
Timeout_value,
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 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, NOSCHED1 |
System Base LU, ASCH1 |
NOSCHED LU |
ASCH LU |
Scheduler 2 LU |
---|
Address Space
Doing Allocate |
From an Address Space Not
Connected to a Scheduler |
OK |
OK |
OK |
NO2 |
NO2 |
From an Address Space Connected
to ASCH |
OK |
OK |
OK |
OK |
NO2 |
From an Address Space Connected
to Scheduler 2 |
OK |
NO2 |
OK |
NO2 |
OK |
From an Address Space Not
Connected to a Scheduler with Prohibit Default LU Specified4 |
NO3 |
NO3 |
NO3 |
NO3 |
NO3 |
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 SpecifiedProgram Calling
Allocate Service |
Base LUs exist |
---|
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 |
NO1 |
nosched |
nosched |
asch |
nosched |
From an Address Space Not
Connected to a Scheduler but with prohibit default LU specified |
NO1 |
NO1 |
NO1 |
NO1 |
NO1 |
NO1 |
NO1 |
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 |
NO1 |
Sched 2 |
nosched |
Sched 2 |
Sched 2 |
Sched 2 |
From an Address Space Connected
to Scheduler 2 and with prohibit default LU specified |
NO1 |
NO1 |
Sched 2 |
NO1 |
Sched 2 |
Sched 2 |
Sched 2 |
Note: - A Product_Specific_Error return code is returned if no base LU
exists.
|
- Timeout_value
- Supplied parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
- Value range: 0-1440 (decimal)
Sets a time limit in minutes that an allocate call and subsequent
APPC/MVS TP conversation calls will wait for VTAM APPCCMD requests
to complete. For more information, see Setting a Timeout Value for Potential Network Delays.
If the time limit is reached before the VTAM APPCCMD
request completes and returns control to APPC/MVS, the conversation
will be terminated by APPC/MVS and the caller of the conversation
callable service will regain control. If the conversation call was
issued with a Notify_Type=ECB (asynchronous processing), the specified
ECB will be posted when the time limit is reached.
To alter
the timeout_value set on the Allocate service, use the Set_Timeout_Value
service.
The maximum supported Timeout_Value is 1440 minutes
(24 hours). A Timeout_Value of 0 and any other positive integer (<=
1440) is valid. When a Timeout_Value of zero is specified, the allocate
call and any subsequent APPC/MVS TP conversation calls will not be
timed. You can activate the time-out feature later by invoking the
Set_Timeout_Value conversation callable service and specifying a non-zero
Timeout_Value.
When a non-zero Timeout_Value is specified and a VTAM APPCCMD request issued during allocate processing does not complete within the time-out period, the conversation allocation
will fail and APPC/MVS will return control to the application with
a Product_Specific_Error return code.
Any error in the specification
of this parameter will result in a Program_Parameter_Check return
code.
- 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 ServiceReturn 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).
- The specified Timeout_value is not valid
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.
|