The following section describes the parameters you specify when
calling the Register_For_Allocates service.
- Notify_type
- Supplied parameter
- Type: Structure
- Length: 4-8 bytes
Specifies the type of processing and notification (synchronous
or asynchronous) requested for this service. The possible types are:
- None
No notification is requested. APPC/MVS processes this
call synchronously, and returns control to the caller when processing
is complete. APPC/MVS sets all returned parameters on return to the
caller. To specify no notification, set this parameter to a four-byte
structure that contains binary zeroes.
- ECB
Programs can request asynchronous processing by specifying
an ECB to be posted when processing completes. To specify an ECB,
set this parameter to an eight-byte structure that contains 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 caller's home
address space.
When you specify an ECB, APPC/MVS returns control
to the caller before processing is complete, with only the return
code set. If APPC/MVS accepts the asynchronous request, it sets the
return code to 0 to show that it is processing the service asynchronously.
APPC/MVS fills in the other returned parameters during asynchronous
processing, and posts the specified ECB when it has set all the returned
parameters. The completion code field in the ECB contains the return
code for the service. APPC/MVS places the reason code, if any, in
the server's reason_code parameter.
- Sym_dest_name
- Supplied parameter
- Type: Character string
- Char Set: 01134
- Length: 8 bytes (left justified, padded with blanks)
Specifies a symbolic destination name that represents the
transaction program and local LU for which you are registering. This
parameter, if used, must contain a value that matches a symbolic destination
name defined in the active side information data set. APPC/MVS obtains
the TP name and local LU name from the side information data set (the
mode name, which is also contained in the side information, is ignored).
To
omit a symbolic destination name, set the sym_dest_name parameter
value to 8 blanks and specify values for the local_LU_name, TP_name,
and TP_name_length parameters.
If you specify a symbolic destination
name, APPC/MVS obtains the local LU name from the PARTNER_LU keyword
value in the symbolic destination entry. If the LU name specified
in the symbolic destination entry is network-qualified (includes both
the network ID and network LU name), APPC/MVS uses only the network-LU-name
portion for the local LU name. If the keyword value is a VTAM generic
resource name, this service fails with return code 16 (atbcts_request_unsuccessful)
and reason code 12 (atbcts_inval_local_lu). If both the local_LU_name
parameter and the LU name in the symbolic destination entry is blank,
this service fails with return code 8 (atbcts_parameter_error), and
reason code 5 (atbcts_local_lu_not_specified).
If the local
LU name is obtained from the side information data set and the LU
name is a network-qualified LU name, APPC/MVS ensures that the netid
in the symbolic destination name is the local netid. If not, the Register_For_Allocates
service returns return code 4 (atbcts_warning) and reason code 28
(atbcts_netid_does_not_match). If VTAM is not active and therefore
APPC/MVS cannot determine whether the netid is valid, the Register_For_Allocates
service returns return code 4 (atbcts_warning) and reason code 39
(atbcts_cannot_determine_netid). Both of these codes are warnings
only; APPC/MVS continues to process the call to the Register_For_Allocates
service.
If you also specify values for the local_LU_name or
the TP_name/TP_name_length parameters, these values override any obtained
from the side information data set.
If you specify a symbolic
destination name that does not match an entry in the side information
data set, the Register_For_Allocates service returns control with
return code 16 (atbcts_request_unsuccessful) and reason code 11 (atbcts_sym_dest_name_unknown).
- TP_name_length
- Supplied parameter
- Type: Integer
- Length: 32 bits
- Range: 0-64
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 TP name from the side information
data set.
- TP_name
- Supplied parameter
- Type: Character string
- Char Set: 00640 or Type A (Type A if the TP is protected by RACF)
- Length: 1 - 64 bytes
Specifies the name of transaction program that was targeted
by the client TP's allocate request. This name must match the name
that the client TP specified in the TP_name parameter of the Allocate
service.
If you specify a symbolic destination name in the sym_dest_name
parameter, set TP_name to 0 to use the TP name from the side information
data set.
You can specify a SNA service transaction program
name in this parameter.
If the TP is to be protected by a RACF
security profile in the APPCTP class or the APPCSERV class, the TP
name must consist of Type A characters only. See Character Sets for
a list of Type A characters.
- Local_LU_name
- Supplied parameter
- Type: Character string
- Char Set: Type A
- Length: 8 bytes (left justified, padded on right with blanks)
Specifies the name of the LU at which the transaction program
specified in the TP_name parameter resides. The local LU name must
match the name of the LU that the client TP specified on its allocate
call (in the partner_LU_name parameter).
If you specify a symbolic
destination name in the sym_dest_name parameter, set local_LU_name
to 8 blanks to use the value for the PARTNER_LU keyword in the side
information entry. The keyword value cannot be a VTAM generic resource
name, or this service fails.
- Partner_LU_name
- Supplied parameter
- Type: Character string
- Char Set: Type A
- Length: 17 bytes (left justified, padded on right with blanks)
Specifies the name of the LU from which the client TP's allocate
request originated. The client TP might have specified this LU on
its allocate request, or have used the default local LU (by setting
the local_LU_name parameter of the Allocate service to blanks). The
local LU transforms this locally known LU name to an LU name used
by the network. (For more information about the local_LU_name parameter
of the Allocate service, see z/OS MVS Programming: Writing Transaction Programs for APPC/MVS.)
The
partner_LU_name parameter can contain one of the following values:
- 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.
Inbound
allocate requests from any LU with the network LU name specified on
the call to the Register_For_Allocates service can be placed on this
allocate queue. APPC/MVS, however, will first check to see if there
are any allocate queues with a matching network-qualified partner
LU name.
- 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 of a network-qualified name may be a VTAM generic resource
name.
If the network-qualified LU name is specified, both the
network ID and the network LU name on the inbound allocate request
will have to match the value specified on the Register_For_Allocates
call to be placed on the allocate queue. If VTAM is inactive, APPC/MVS
is unable to determine the network ID, therefore no inbound allocate
requests will be placed on an allocate queue that has a network-qualified
partner LU name. When an inbound allocate request enters the system,
APPC/MVS first checks for a match with the network-qualified LU name
and then just the network LU name.
- Blank:
A blank value for the partner_LU_name parameter indicates
that allocate requests from any partner LU are to be accepted.
Table 1 shows whether the partner LU name specified
on a call to Register_For_Allocates will successfully match the LU
associated with the inbound request:
Table 1. How APPC/MVS Handles Partner LU Name Specifications| Register_For_Allocates
specifies... |
LU of the inbound
request... |
|---|
| netid.LUNAME |
net2.LUNAME |
LUNAME |
|---|
| LUNAME |
Match |
Match |
Match |
| netid.LUNAME |
Match |
No Match |
No Match |
| net2.LUNAME |
No Match |
Match |
No Match |
- User_ID
- Supplied parameter
- Type: Character string
- Char Set: Type A
- Length: 8 bytes (left justified, padded on right with blanks)
Specifies the user ID associated with the inbound allocate
requests to be served.
A blank value for the user_ID parameter
indicates that allocate requests from any user ID are to be accepted.
Note
that APPC/MVS does not ensure that the specified user ID is a member
of the security profile specified in the profile parameter. The server
must perform this check itself, if needed.
- Profile
- Supplied parameter
- Type: Character string
- Char Set: Type A
- Length: 8 bytes (left justified, padded on right with blanks)
Specifies the security profile associated with the inbound
allocate requests to be served. APPC/MVS treats the profile name
as a RACF group name.
A blank value for the profile parameter
indicates that allocate requests from any security profile are to
be accepted.
APPC/MVS compares this profile with the profile
that flows in with the allocate request, or with the user ID's default
profile, if no profile flows in with the allocate request.
- Allocate_queue_token
- Returned parameter
- Type: Character string
- Length: 8 bytes
Returns the allocate queue token, which uniquely identifies
an allocate queue. Use the allocate queue token on later calls to
APPC/MVS allocate queue services to indicate the particular allocate
queue on which a requested function is to be performed.
This
field contains a valid token only when the return code from this service
is either 0 or 4 (atbcts_warning).
- Reason_code
- Returned parameter
- Type: Integer
- Length: 32 bits
Contains additional information about the result of the call
when the return_code parameter contains a non-zero value other than
decimal 64 (atbcts_appc_not_available).
Table 2 lists
the valid reason codes.
- Return_code
- Returned parameter
- Type: Integer
- Length: 32 bits
Contains the result of the call. If the return_code parameter
contains zero or decimal 64 (atbcts_appc_not_available), there is
no reason code. For other return codes, check the reason_code parameter
for additional information about the result of the call.
Table 2 lists the valid return and reason codes for the Register_For_Allocates
service.
Table 2. Return and
Reason Codes for Register_For_Allocates| Return Code (Decimal) |
Reason Code (Decimal) |
Symbolic Value |
|---|
| 0 |
|
atbcts_ok |
| 4 |
|
atbcts_warning |
| |
1 |
atbcts_already_registered |
| |
28 |
atbcts_netid_does_not_match |
| |
39 |
atbcts_cannot_determine_netid |
| 8 |
|
atbcts_parameter_error |
| |
2 |
atbcts_tp_name_not_specified |
| |
3 |
atbcts_inval_tp_name |
| |
4 |
atbcts_inval_tp_name_length |
| |
5 |
atbcts_local_lu_not_specified |
| |
18 |
atbcts_inval_notify_type |
| |
43 |
atbcts_inval_partner_lu |
| 16 |
|
atbcts_request_unsuccessful |
| |
7 |
atbcts_parameter_inaccessible |
| |
8 |
atbcts_cannot_hold_locks |
| |
10 |
atbcts_sched_cant_register |
| |
11 |
atbcts_sym_dest_name_unknown |
| |
12 |
atbcts_inval_local_lu |
| |
13 |
atbcts_lu_not_receiving |
| |
14 |
atbcts_not_auth_to_serve_tp |
| |
15 |
atbcts_not_auth_to_local_lu |
| |
20 |
atbcts_request_cancelled |
| 32 |
|
atbcts_service_failure |
| |
16 |
atbcts_appc_service_failure |
| 64 |
|
atbcts_appc_not_available |
z/OS MVS Programming: Writing Servers for APPC/MVS
Copyright IBM Corporation 1990, 2014