Creating a Session Programmatically

Normally, if you wish to create a session for yourself, you must be at a terminal and log on to the system by:

Entering the :HELLO command correctly.
Pressing RETURN
Waiting for the logon banner and prompt to appear on your terminal screen before continuing.

With Programmatic Sessions (PS) Capability, you can create a session for yourself, or for other users, on an available (not currently assigned to a session) terminal without having to be at the specified terminal(s). The operating system facilities for performing the PS task are available to you through the STARTSESS intrinsic and the :STARTSESS command.

Assigning the Programmatic Sessions Capability

Your System Manager (SM) or Account Manager (AM) must assign the PS capability to any user who plans to:

Run a program that calls the STARTSESS intrinsic.
Execute the :STARTSESS command from the MPE/iX CI, from a UDC, from the Startup State Configurator, or programmatically through the MYCOMMAND or HPCICOMMAND intrinsic.

When the operating system executes the code of either STARTSESS or :STARTSESS, it examines the user's capability list for the PS capability:

If the PS capability is not found when invoking STARTSESS, the intrinsic fails and the program is aborted.
If the PS capability is not found when invoking :STARTSESS, the command fails and control returns to the CI.

STARTSESS Description

The syntax for the STARTSESS intrinsic is:


   STARTSESS (ldev,logonstr,jsid,jsnum,errorstat);

The syntax for the :STARTSESS command is:


   :STARTSESS ldev,logonstr

The ldev parameter of STARTSESS and the ldev parameter of :STARTSESS are functionally equivalent, as are logonstr and logonstr, respectively. The intrinsic has additional parameters that return the job/session number (jsid, jsnum) and possible error conditions (errorstat).

Specifying a Terminal

You must specify, with the ldev parameter, the logical device number of the terminal on which the session is to be created (the target terminal). The target terminal must be:

A real physical device
An available terminal
Job accepting
Hard wired
Set to the configured baud rate

Specifying the Logon

You must specify with the logonstr parameter a character array containing the logon. The logon is a superset of the :HELLO command syntax and includes an additional optional parameter ;NOWAIT. The :HELLO command options are described in the MPE/iX Commands Reference Manual (32650-90003). The ;NOWAIT parameter is described below.

If you specify the ;NOWAIT keyword parameter in logonstr and the session is successfully created, MPE/iX continues with session startup as if it had actually received a carriage return from the target terminal. There are two additional requirements for the ;NOWAIT keyword parameter:

The target terminal must be turned on and set to the configured baud rate. Otherwise, STARTSESS/:STARTSESS fails and the session is not created.
You must have SM capability if the target terminal is the System Console.

You must supply all required password(s) in the logonstr parameter. If required passwords are not supplied in logonstr, STARTSESS/:STARTSESS fails because MPE/iX does not prompt for passwords on the target terminal. You must place a carriage return character (%15) in the array element following the last valid character of logonstr to indicate the end of valid data.

Session Creation

If STARTSESS/:STARTSESS is successful, a session is created at the terminal specified in the ldev. MPE/iX returns a successful status to STARTSESS/:STARTSESS, and the session or process that called STARTSESS/:STARTSESS can continue execution without having to wait for a carriage return from the target terminal. If you execute a :SHOWJOB command from another terminal prior to RETURN being pressed on the target terminal, MPE/iX displays the newly created session in EXEC* state.

If ;NOWAIT is not specified in logonstr, MPE/iX waits for a carriage return from the target terminal before continuing session startup and printing I/O to the terminal. If ;NOWAIT is specified, MPE/iX continues with session startup as if it had actually received a carriage return from the target terminal.

After MPE/iX recognizes that you pressed RETURN on the target terminal:

The logon banner appears.
The line "***PROGRAMMATIC LOGON***" appears.
MPE/iX finishes the normal logon sequence (initializing or executing logon UDCs).

At this point, MPE/iX no longer distinguishes between a session started with STARTSESS/:STARTSESS and a session started with the :HELLO command.




	NOTE: If the target terminal is not set to the configured baud rate, MPE/iX cannot recognize a carriage return (or any input) from that terminal because there is no baud rate sensing by the intrinsic or the command. If this situation arises, you must change the baud rate setting on the target terminal to the configured rate and again press RETURN.

If you put a :STARTSESS command into a Startup State Configurator file, you can also start a session on the System Console. MPE/iX does not log OPERATOR.SYS on to the Console, but instead treats the Console as an available terminal requiring a session logon.

Using STARTSESS in a Program

Example 4-1 is a simple Pascal XL program that demonstrates the use of the STARTSESS intrinsic. The program can facilitate the logon process for novice users by creating the desired session on the specified logical device. Because the logonstr parameter specifies ;NOWAIT, MPE/iX accomplishes the logon sequence and executes all logon UDCs. In this case, the novice user does not need any knowledge of the :HELLO command.

Figure 4-1 Example 4-1. Program Using STARTSESS Intrinsic to Create Sessions


   program Create_Session (input, output);



   {This program demonstrates the use of the MPE/iX STARTSESS intrinsic to}

   {programmatically create sessions on specified terminals.  This program}

   {prompts the user for the ldev, then creates a session for NOVICE.ACCT }

   {specifying the :NOWAIT option.  When the user inputs a zero, the      }

   {program ends.                                                         }



   const

      logon_string_size = 20;

      blank = ' ';



   var

      ldev       :shortint;

      logonstring:packed array [1..logon_string_size] of char;

      jsid       :shortint;

      jsnum      :integer

      error      :shortint;



   procedure STARTSESS; intrinsic;



   begin

      logonstring := 'NOVICE.ACCT;NOWAIT   ';



      logonstring[17] := ch(13);            {Required delimiter.          }



      write ('Please input ldevs where you wish sessions started');

      writeln (' (0 = end of list)');

      readlin (ldev);

      while ldev <> 0 do

      begin                                 {Create session on ldev.     }

          error := 0;

          STARTSESS (ldev,logonstring,jsid,jsnum,error);

          if error <> 0 then

          begin                             {Return error status.        }

              write ('STARTSESS error = ',error);

              writeln (' on ldev = ' ldev);

          end;

          readln (ldev);

       end;                                 {End while loop.             }

   end.

If the following UDC is located in the UDC file of the specified session(s), the novice user is further relieved of having to deal with the MPE/iX CI:


   LOGON

   OPTION LOGON,NOBREAK,NOHELP,NOLIST

   RUN HPMENU.PUB.SYS

   BYE

   ***

This UDC is executed at each session logon when the STARTSESS program is run. It automatically places the user into the application specified in the :RUN command (in this case, HPMENU.PUB.SYS).

Using :STARTSESS in the Startup State Configurator

Example 4-1 illustrates how you can programmatically create sessions on specified terminals. However, the system must be up and running, and you must execute the program from a session you have already logged onto.

You can use :STARTSESS from within the System Startup State Configurator to create sessions on specified terminals every time you start the system. If you have SM Capability as well as PS capability, you can use the System Startup State Configurator facility to automatically:

Reset any of the system-defined defaults
Stream special jobs
Open DS lines
Create user sessions on specified terminals when the system comes up

Using the full functionality of the System Startup State Configurator, it is possible for you to describe beforehand exactly what the desired System Startup State should be.

In Example 4-2, the STARTUP command defines actions that the system will perform regardless of the type of system startup used by the operator. WARMSTART (corresponds to the system startup command START RECOVERY) and COOLSTART (corresponds to the system startup command START NORECOVERY), as defined below, will cause sessions to be created for MGR.ACCT on logical device 20 (the Console) and for NOVICE.ACCT on logical devices 21, 22, and 23.

Figure 4-2 Example 4-2. :STARTSESS Command Used in Startup State Configurator


   STARTUP

   STREAMS 10

   ALLOW @.@;COMMANDS=REPLY

   ALLOCATE COBOLII.PUB.SYS

   LIMIT 4,16

   JOBFENCE 4

   OUTFENCE 5

   ***

   WARMSTART

   STARTSESS 20;MGR.ACCT;HIPRI;NOWAIT

   STARTSESS 21;NOVICE.ACCT;NOWAIT

   STARTSESS 22;NOVICE.ACCT.NOWAIT

   ***

   COOLSTART

   STARTSESS 20;MGR.ACCT;HIPRI;NOWAIT

   STARTSESS 21;NOVICE.ACCT;NOWAIT

   STARTSESS 22;NOVICE.ACCT;NOWAIT

   STARTSESS 23;NOVICE.ACCT;NOWAIT

   ***

If the following UDC is located in the UDC file of the specified sessions, the user is relieved of having to deal with the MPE/iX CI:


   LOGON

   OPTION LOGON,NOBREAK,NOHELP,NOLIST

   RUN HPMENU.PUB.SYS

   BYE

   ***

This UDC is executed at the time of session logon. It automatically places the user into the application specified in the :RUN command (in this case, HPMENU.PUB.SYS).

For more information about the MPE/iX System Startup State Configurator, refer to Managing Jobs and Sessions (32650-90035).