|
The Identify service is used by a transaction scheduler
to make itself known to APPC/MVS. A transaction scheduler issues
Identify after it has initialized itself and is ready to receive or
schedule requests from APPC/MVS. The transaction scheduler must supply
an XCF member token on Identify to allow APPC/MVS to communicate with
it. A transaction scheduler must identify itself to APPC/MVS before
its subordinate address spaces can connect to APPC/MVS.
Specifically, this service is used by a transaction scheduler
to do the following:
- Identify itself to APPC/MVS.
- Provide its XCF member token to APPC/MVS so that it can be notified
of inbound Allocate requests.
- Optionally identify an information extract exit that may be invoked
by APPC/MVS when it needs information from the transaction scheduler.
- Determine whether the APPCPMxx parmlib member correctly defines
the LUs for the transaction scheduler.
- Specify initial status for LUs belonging to the transaction scheduler.
- Identify an exit to convert a TP profile the first time it is
referenced, and store the converted profile for future references.
Environment
Authorization: |
Supervisor state or PSW key 0-7 |
Dispatchable unit mode: |
Task mode |
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. |
FormatFigure 1. ATBIDN1
- IdentifyCALL ATBIDN1 (Scheduler_name,
Scheduler_extract_exit_addr,
Scheduler_extract_user_field,
Scheduler_member_token,
TP_profile_processing,
LU_initial_status,
Scheduler_TP_profile_exit,
Scheduler_TP_profile_exit_data,
Return_codes
);
Parameters- Scheduler_Name
- Supplied parameter
- Type: Character String
- Char Set: 01134
- Length: 8 bytes
Specifies the name of the transaction scheduler. This field
must match a transaction scheduler name appearing in the LU definitions
of an APPCPMxx parmlib member. The value must be the same as the
value of the SCHED keyword of one or more LUADD statements in APPCPMxx.
The transaction scheduler name will also be used for operator displays.
If the transaction scheduler runs only as a “single instance
per system,” this value should be a string that suggests the name
of the component performing the Identify (for example, “ASCH” is
an abbreviation used to identify the APPC transaction scheduler).
If the transaction scheduler can run as “multiple copies per system,”
this value should be a string that identifies a particular copy of
the transaction scheduler (for example, subsystems may wish to use
the subsystem name that appears in the IEFSSNxx parmlib member).
Once a transaction scheduler has successfully been identified,
no other Identify call using the same Scheduler_Name will be accepted
unless a corresponding Unidentify statement is issued.
- Scheduler_Extract_Exit_Addr
- Supplied parameter
- Type: Address
- Char set: N/A
- Length: 32 bits
Specifies the address of the transaction scheduler's information
extract exit. This is an optional exit and may be left zero. See Extract Exit for information about the requirements
for and processing of a transaction scheduler extract exit.
- Scheduler_Extract_User_Field
- Supplied parameter
- Type: Character string
- Char set: No restriction
- Length: 8 bytes
Specifies a user-defined field or token passed to the transaction
scheduler's information extract exit.
- Scheduler_Member_Token
- Supplied parameter
- Type: Character string
- Char set: No restriction
- Length: 8 bytes
Specifies an XCF member token. The member token represents
a member of the XCF group that is joined when the Join_Sysappc_Group
service is invoked. Messages are sent to this member to report when
the transaction scheduler's LU name is activated or deactivated.
Messages are also sent to report the arrival of inbound Allocate requests.
APPC/MVS does not check the validity of this member token. If a transaction
scheduler passes an unknown member token, then the transaction scheduler
will not receive notification of the arrival of inbound Allocate requests.
- TP_Profile_Processing
- Supplied parameter
- Type: Integer
- Char set: N/A
- Length: 32 bits
Specifies the TP_Profile processing characteristics to use
for this transaction scheduler.
Valid values for this parameter
are: - Value
- Meaning
- 0
- Required
Specifies that APPC/MVS should reject any inbound
Allocate request that specifies a TP_Name for which a TP_Profile entry
does not exist. If a TP_Profile entry does not exist, the inbound
Allocate request is rejected with TP_Not_Recognized (sense code X'10086021').
- 1
- Optional
Specifies that a TP_Profile entry is not required.
APPC/MVS will perform all validity and security checks and reject
the request if any of these checks fail. If a TP_Profile entry does
not exist, APPC/MVS will indicate this in the XCF message sent to
the transaction scheduler to notify it of the inbound Allocate request.
- LU_Initial_Status
- Supplied parameter
- Type: Integer
- Char set: N/A
- Length: 32 bits
Specifies the initial status of LUs controlled by this transaction
scheduler. Any additional LUs being added for this transaction scheduler
after Identify will initially be given this status, unless Control
Halt_All or Resume_All is called to set the status.
Valid
values for this parameter are: - Value
- Meaning
- 0
- Active
Specifies that APPC/MVS should activate the LU(s) controlled
by this transaction scheduler. The status of every LU controlled
by this transaction scheduler will initially be put into Active state.
- 1
- Outbound_Only
Specifies that APPC/MVS should temporarily halt
processing of Allocate requests to the LU or LUs controlled by this
transaction scheduler. For the LU to begin accepting inbound requests,
the transaction scheduler has to call the Control service for the
Resume_All_Input function. The status of every LU controlled by this
transaction scheduler, whether it is added to the system at initialization
or by a subsequent SET command, will initially be put into Outbound_Only
state, unless Control Resume_All_Input is called to set the status.
When the APPC address space terminates and restarts, the transaction
schedulers that have called Identify and Connect before have to reidentify
themselves and reconnect all their subordinate address spaces. A
transaction scheduler can use this option to temporarily halt processing
of inbound Allocate requests to the LU while it is in the process
of reconnecting its subordinate address spaces. It can issue a Control
Resume request to activate all the LUs when the reconnect process
is finished.
- Scheduler_TP_profile_exit
- Supplied parameter
- Type: Character string
- Char set: 01134
- Length: 8 bytes
Specifies the name of the exit that will receive control
when the TP profile requires conversion. To specify no exit, set
this parameter to 8 blanks. For more information about the requirements
for and processing of this exit, see TP Profile Conversion Exit.
- Scheduler_TP_profile_exit_data
- Supplied parameter
- Type: Character string
- Char set: No restriction
- Length: 8 bytes
Specifies data to be passed to the TP profile conversion
exit each time it is invoked; for example, the address of a workarea
for the exit to use. For more information about how the exit receives
this input data, see TP Profile Conversion Exit.
- Return_code
- Returned parameter
- Type: Integer
- Char Set: N/A
- Length: 32 bits
Identify might return one of the following decimal values
in the return code parameter: - Decimal
- Meaning
- 0
- The Identify request was accepted. The LUs are activated asynchronously.
- 4
- The Identify request was accepted. No base LU name is present.
The APPCPMxx parmlib member or members specify at least one LU name
that is controlled by the transaction scheduler, but no LU name is
designated as the transaction scheduler's base LU. This situation
might arise because the APPCPMxx parmlib member was incorrectly coded,
or because the installation has deliberately chosen this configuration.
- 8
- The Identify request was accepted. No LU names are applicable.
APPC/MVS found that the APPCPMxx parmlib member specifies no LU names
that are controlled by the transaction scheduler. This situation
might arise because the APPCPMxx parmlib member did not specify the
correct transaction scheduler name on the SCHED keyword of LUADD,
or it might arise because APPC/MVS tried to initialize for the specified
LU name and encountered a failure (for example, APPC/MVS was unable
to open the required TP profile file).
- 12
- The Identify request was rejected. The calling transaction scheduler
address space is already identified using the same scheduler name
as the Scheduler_name parameter passed in. This may occur if the
caller issued Identify twice with the same scheduler name.
- 14
- The Identify request was rejected. The calling transaction scheduler
address space is already identified using a different scheduler name
from the Scheduler_name parameter passed in. This may occur if the
caller issued Identify twice with different scheduler names.
- 16
- The Identify request was rejected. The Scheduler_Name parameter
of Identify is already in use by some other address space that previously
issued Identify.
- 18
- The Identify request was rejected. The Scheduler_TP_profile_exit
name that was passed could not be loaded.
- 20
- The Identify request was rejected. The Scheduler_Name parameter
value is not valid.
- 22
- The Identify request was rejected. The Scheduler_TP_profile_exit
name is not valid.
- 24
- The Identify request was rejected. The TP_Profile_Processing
parameter value is not valid.
- 28
- The Identify request was rejected. The LU_Initial_Status parameter
value is not valid.
- 32
- The requested service is not supported in the caller's environment.
For example, this return code is given if the caller invokes any of
the transaction scheduler services while holding a lock.
- 38
- The requested transaction scheduler service cannot be invoked
from a subordinate address space, or an address space that has outstanding
APPC/MVS conversations.
- 40
- The requested transaction scheduler service cannot be invoked
from an APPC/MVS server address space.
- 44
- APPC/MVS is not active.
- 48
- APPC/MVS services failure.
Usage Notes- The transaction scheduler will be notified of an inbound Allocate
request only if the request passes all validity and security checks.
The userid specified in the request must have RACF authority to access
the TP profile entry (whether or not it exists), and if the TP profile
entry is found, it must be marked “activated”.
- Timing restrictions on activities after Identify
The transaction
scheduler might create subordinate address spaces and call Connect
before APPC/MVS reports that the base LU was successfully initialized.
However, the transaction scheduler must not dispatch any work that
might invoke an APPC/MVS Allocate service in these subordinate address
spaces, before one of the following occurs: - The base LU is successfully initialized
- ATBSASA is called to prevent allocated conversations being associated
with the system default LU. For more information about this option,
see Set_AS_Attributes.
- Factors delaying asynchronous completion of Identify
Some
conditions might substantially delay the activation of an LU; for
example, VTAM may be stopped when the Identify is accepted.
An XCF message will be sent to the XCF-member representing the transaction
scheduler when each of its LUs is activated.
- Factors causing asynchronous failure of Identify
Some conditions
might cause an Identify to fail asynchronously after it has been accepted,
for example, VTAM parameters might be mismatched (there might not
be an APPL macro for the specified LU name), or APPC/MVS may be unable
to open the specified TP profile file.
An XCF message will
be sent to the XCF member representing the transaction scheduler when
the attempt to initialize an LU fails asynchronously.
A transaction
scheduler address space must issue Unidentify to undo its Identify,
even if all of its LUs fail asynchronously.
When LU initialization
fails asynchronously, the system issues error messages indicating
the cause of the failure (for example, unable to open the TP profile
file). These messages will be issued to the same operator who receives
messages about failures of LUs after initialization is completed.
- Use of XCF by a transaction scheduler
See Join_Sysappc_Group for information regarding joining
an XCF group.
- Asynchronous initialization of the base LU name
If Identify
produces a return code of zero, then the transaction scheduler issuing
Identify will receive an LU activation or LU deactivation message,
with LU_Flags indicating that the message describes the base LU name.
An LU deactivation message will indicate asynchronous failure of
the attempt to initialize the LU name; an LU activation message will
indicate successful initialization of the LU name.
- Operation without a base LU name
If Identify produces a return
code of 4, then the transaction scheduler will receive neither an
LU activation nor an LU deactivation XCF message for the base LU name,
unless the operator issues a SET command which establishes a base
LU name for the transaction scheduler.
APPC/MVS does not issue
any operator message indicating that the operator should do this;
the transaction scheduler can issue its own operator message asking
the operator to perform such a SET command.
- Operation with no LU names
If Identify produces a return code
of 8, then the transaction scheduler will receive neither an LU activation
nor an LU deactivation message for the base LU name, unless the operator
issues a SET command that establishes a base LU name for the transaction
scheduler.
In this case, APPC/MVS issues an operator message
telling the operator to perform such a SET command.
Characteristics and Restrictions- Identify performs an automatic Connect of the home address space
of the calling transaction scheduler. (See Connect.)
- APPC/MVS supports one Identify per address space. Because of this,
each transaction scheduler must be in its own address space.
- The Identify service causes APPC/MVS to open one or more VTAM
ACBs for the transaction scheduler's LUs. The ACBs are opened asynchronously
if the Identify is accepted. Similarly, the TP profile file or files
are also opened asynchronously. The asynchronous OPEN lets a transaction
scheduler identify itself when VTAM is functioning. APPC/MVS informs
a transaction scheduler that its LU is operational.
- As soon as APPC/MVS accepts the Identify request, the scheduler's
corresponding XCF message user routine and information extract exit
may be invoked at any time.
- Transaction schedulers that call the Identify service should not
have any enabled unlocked task (EUT) functional recovery routines
(FRRs) established. For more information about EUT FRRs, see the
information on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.
- An APPC/MVS server address space cannot use the Identify service.
If an address space calls the Identify service while it is registered
for an allocate queue, the system does not perform the Identify service
function, and the caller receives a return code of 40 (decimal). For
information about APPC/MVS servers, see z/OS MVS Programming: Writing Servers for APPC/MVS.
|