Environment

Format

CALL ATBIDEN (Scheduler_name, 
              Scheduler_extract_exit_addr, 
              Scheduler_extract_user_field, 
              Scheduler_member_token, 
              TP_profile_processing, 
              LU_initial_status, 
              Return_code 
             ); 

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 which 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 which identifies a particular copy of the transaction scheduler (for example, subsystems might wish to use the subsystem name which 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 can be left zero. See Extract Exit for information about coding 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 will 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 or LUs 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. The transaction scheduler has to call Control Resume in order for the LU to begin accepting inbound requests. 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 is called to set the status.

When the APPC address space terminates and restarts, the transaction schedulers that have done 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.

Return_code

Returned parameter

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

Identify may 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 may 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 may arise because the APPCPMxx parmlib member did not specify the correct transaction scheduler name on the SCHED keyword of LUADD, or it may 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.

20

The Identify request was rejected. The Scheduler_Name parameter value 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

1. 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”.
2. Timing restrictions on activities after Identify
   The transaction scheduler may create subordinate address spaces and invoke 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.
3. Factors delaying asynchronous completion of Identify

   Some conditions may 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.

4. 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 might not be able 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, APPC/MVS will issue 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.

5. Use of XCF by a transaction scheduler

   See ATBMIGRP— Join_Sysappc_Group for information regarding joining an XCF group.

6. 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.

7. 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 that 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 might wish to issue its own operator message asking the operator to perform such a SET command.

8. 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

1. Identify performs an automatic Connect of the home address space of the calling transaction scheduler. (See Connect.)
2. APPC/MVS supports one Identify per address space. Because of this, each transaction scheduler must be in its own address space.
3. The Identify service causes APPC/MVS to open a VTAM ACB or ACBs for the transaction scheduler's LUs. The ACB or 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.
4. As soon as APPC/MVS accepts the Identify request, the scheduler's corresponding XCF message user routine and information extract exit can be invoked at any time.
5. 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.
6. 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.