HP 3000 Manuals HP 3000 Manuals
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:
1. Entering the :HELLO command correctly.
2. Pressing [[RETURN]]
3. 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 XL 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 XL 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 XL 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 XL 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 XL 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 XL displays the newly created session in EXEC*
state.
If ;NOWAIT is not specified in logonstr, MPE XL 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 XL continues
with session startup as if it had actually received a carriage return
from the target terminal.
After MPE XL recognizes that you pressed [[RETURN]] on the target
terminal:
1. The logon banner appears.
2. The line "***PROGRAMMATIC LOGON***" appears.
3. MPE XL finishes the normal logon sequence (initializing or
executing logon UDCs).
At this point, MPE XL 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
XL 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 XL 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 XL
accomplishes the logon sequence and executes all logon UDCs. In this
case, the novice user does not need any knowledge of the :HELLO command.
________________________________________________________________________
| |
| program Create_Session (input, output); |
| |
| {This program demonstrates the use of the MPE XL 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 XL 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.
________________________________________________________________________
| |
| 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 XL 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 XL System Startup State Configurator,
refer to Managing Jobs and Sessions (32650-90035).