Session allocation

You acquire an LUTYPE6.1 session to a remote IMS system by using the ALLOCATE command.

The ALLOCATE command has the following format: 
  ALLOCATE {SYSID(name)|SESSION(name)}
    [PROFILE(name)]
    [NOQUEUE]

You can use the SYSID option to name the remote system and allow CICS to select an available session, or you can use the SESSION option to request the use of a specific session to the remote IMS system. The use of the SESSION option is not normally recommended, because it can result in an application program queuing on a specific session when others are available. In most cases, therefore, you will use the SYSID option to name the system with which the session is required.

If CICS cannot find the named system, or no sessions are available, it raises the SYSIDERR condition. If CICS cannot find the named session or the session is out of service, CICS raises the SESSIONERR condition.

You can use the PROFILE option to specify a communication profile for an LUTYPE6.1 session. The profile, which is set up during resource definition, contains a set of terminal control processing options that are to be used for the session.

If you omit the PROFILE option, CICS uses the default profile DFHCICSA. This profile specifies INBFMH(ALL), which means that incoming function management headers are passed to your program and cause the INBFMH condition to be raised.

You can use the NOQUEUE option to specify explicitly that you do not want your request for a session to be queued if a session is not available immediately. A session is not immediately available in any of the following situations:
  • All the sessions to the specified system are in use.
  • The only available sessions are not bound (in which case, CICS would have to bind a session).
  • The only available sessions are contention losers (in which case, CICS would have to bid to begin a bracket).
The action taken by CICS if a session is not immediately available depends on whether you specify NOQUEUE and also on whether your application has issued a HANDLE (that is still active) for the SYSBUSY condition. The possible combinations are as follows:
  • Active HANDLE for SYSBUSY condition.

    Control is returned immediately to the label specified in the HANDLE command, regardless of whether you specified NOQUEUE.

  • No active HANDLE for SYSBUSY condition.
    • If you specified NOQUEUE, control is returned immediately to your application program. The SYSBUSY code (X'D3') is set in the EIBRCODE field of the EXEC interface block. You should test this field immediately after issuing the ALLOCATE command.
    • If you omitted the NOQUEUE option, CICS queues the request until a session is available.

Whether a delay in acquiring a session is acceptable depends on your application.

Similar considerations apply to an ALLOCATE command that specifies SESSION rather than SYSID. The associated condition is SESSBUSY (EIBRCODE=X'D2').