Character Run Support
Beta Draft
Author: (Author's Name)
Date Last Updated: (Date)
Scheduled Release: (Release Number)
Revision History
The following revisions have been made to this document:
Date: (date)
Revision: (rev-no)
Developer: (developer)
Summary of Changes: (summary)
Copyright (C) 2000 by Progress Software Corporation ("PSC"), 14 Oak Park, Bedford, MA 01730, and other contributors as listed below. All Rights Reserved.
The Initial Developer of the Original Code is PSC. The Original Code is Progress IDE code released to open source December 1, 2000.
The contents of this file are subject to the Possenet Public License Version 1.0 (the "License"); you may not use this file except in compliance with the License. A copy of the License is available as of the date of this notice at:
http://www.possenet.org/license.html
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. You should refer to the License for the specific language governing rights and limitations under the License.
Contributors
Jane Contributor, Joe Contributor
Contents
The AppBuilder allows you to run character-mode procedures and view them in actual character-mode format. This document describes the internal and technical aspects of AppBuilder's character run support.
When a character procedure is run from the AppBuilder, the AppBuilder starts a multi-user Progress character client session called the Character Run Window. The Character Run Window runs the character procedure. The AppBuilder and Character Run Window sessions communicate with each other by reading and writing messages through a file on disk called the TTY, or character message file. (The terms TTY or character command file may also be used in this document and in the ADE tools source code to refer to the TTY, or character message file.) The character message file contains information needed by both sessions to support character run.
Several source procedures work together to accomplish character run support. These include the following:
The following sections describe character run support in more detail.
2.1 How the AppBuilder Starts and Communicates with the Character Client Session
To run the character procedure in an actual character session, the AppBuilder must start a multi-user Progress character client session. The AppBuilder calls procedure adeuib/_ttyss.p to start the character client session. This procedure is called the TTY Session Start procedure.
Note: The character client session must be started in a multi-user mode because the client and the AppBuilder session connect to the same databases.
2.1.1 Detailed Steps in the TTY Session Start Procedure
The TTY Session Start procedure performs the following activities:
The TTY Session Start procedure also determines when the AppBuilder can resume design-mode control.
2.2.1.1 Details About the TTY Session Start Procedure
The TTY Session Start procedure performs these actions as follows:
The command line contains the command (such as "RUN" or "RUN-DEBUG") and the AppBuilder assigned temporary file name of the character procedure to run, and other important information. See 2.1.4, "Character Message File", in this document for details.
If the character message file… |
Then… |
does not exist |
create it and write the command line information to the message file. Perform a no-wait OS-command shell to the operating system and start the multi-user Progress character client session. |
does exist |
write the command line information to the existing message file. Do not start another character client session. The existence of the message file indicates that the character client session is already running and the Character Run Window is waiting for the AppBuilder to run another character procedure. |
Note:
Note: Run commands indicate that the character procedure is still running in the Character Run Window, and that the AppBuilder must remain in run-mode.
If the character message file contains the … |
Then… |
OK command |
1. The character procedure has completed running and the Character Run Window is waiting for the next character procedure to run. 2. End the looping and the TTY Session Start procedure, returning design-mode control to the AppBuilder. Note: The character message file is not deleted so that the next time the AppBuilder runs a character procedure, the Start Session procedure will not start a new character client session and instead, use the existing one. |
OK-EXIT command |
1. The Character Run Window and the client session have been closed. 2. End the looping, delete the character message file, and end the TTY Session Start procedure, returning design-mode control to the AppBuilder. |
2.1.2 Detailed Steps on How the Character Run Window Works and Communicates with the AppBuilder
The Character Run Window runs the character procedure in the multiuser character client session started by the AppBuilder. The Character Run Window is displayed and managed by procedure adecomm/_ttysr.p. This procedure is called the TTY Session Run procedure. It communicates with the AppBuilder (via TTY Session Start procedure) using the character message file. The TTY Session Run procedure connects to a list of specified databases, runs the character procedure, and waits to run another character procedure. It also ends the character client session when necessary.
2.2.2.1 Details About the TTY Session Run Procedure
The TTY Session Run procedure performs these actions as follows:
If the command is… |
Then… |
A run command such as "RUN" or "RUN-DEBUG" |
Connect to any databases read from the message file, if they are not already connected, and run the character procedure file indicated by the name of the temporary run file retrieved from the character message file. When the character procedure is finished running, display the message "Procedure complete. Waiting for next run.", and write an "OK" command to the character message file. Note: The "OK" message communicates back to the AppBuilder session (via the message file) that the character procedure has completed running, and the Character Run Window is ready to run another procedure. The AppBuilder then returns to design-mode. Continue looping and reading the character message file for commands from the AppBuilder. |
"OK-EXIT" |
End the looping, delete the character message file, and close the Character Run Window. End the character client session with a QUIT command. Note: The Character Run Window receives an "OK-EXIT" command from the AppBuilder when the user chooses Compile®Close Character Run Window in the AppBuilder Main window, or when the user exits AppBuilder. |
Note: If the character message file becomes deleted any time the Character Run Window is waiting to run another procedure, end the looping, close the Character Run Window, and end the character client session with a QUIT command.
2.1.3 Startup Parameters for Character Client Session
The following table identifies and describes the startup parameters that the TTY Session Start procedure adeuib/_ttyss.p invokes to run the character client Progress executable:
Startup Parameter |
Description |
-p adecomm/_ttysr.p |
TTY Session Run procedure. See "Detailed Steps on How the Character Run Window Works and Communicates with the AppBuilder" for details. |
-param s_tmp_file |
AppBuilder defined shared variable used only for character run support to specify the name of the character message file. In adeuib/_ttyss.p and adeuib/_ttysx.p, its eventually stored in a local variable named tty_command. |
-T SESSION:TEMP-DIR |
Specifies the character client session to use the same Progress Temporary Directory as the AppBuilder session. |
The AppBuilder and character client (also referred to as the Character Run Window) sessions communicate with each other through the character message file (also referred to as the TTY message file or command file). The AppBuilder creates the file before starting the character client session. This file name follows this formatting convention:
"pNNNNNm.tty" Example: "p14325m.tty"
This list identifies the elements in the file name:
Note: When the end user closes the Character Run Window, the character message file is deleted.
The AppBuilder and character client write a command line to the message file. The following sections describe the command line format and message file commands.
The following code shows the standard format of the character message file command line:
code-page|command|proc-filename|DB=-db dbname -ld ldbname …
Example. The following code shows a specific use of this command line format:
ibm850|RUN|p12345cf.ab|DB=-db demo -ld demo
The following table identifies and describes each element of the character message file command line code format:
Code element |
Description |
Code-page |
Stream code page used to create the message file. |
|
Specifies the character run support command. Commands are: RUN, RUN-DEBUG, OK, and OK-EXIT. Note: Command descriptions are given in section 2.1.6, "Message File Commands", in this document. |
|
Identifies the AppBuilder-assigned temporary file name of the character procedure to run. |
DB |
Specifies the database connection information used to connect databases in the character client session. The ellipses indicate additional -db and -ld pairs can follow. |
2.2.5.1 Resolving Different Stream Code Page Settings
It is possible for the AppBuilder client to start its session with a stream code page setting (either -cpstream or the obsolete -stream parameter) that is different than that which starts the character client session. This means the AppBuilder could write a character message file that the character client session cannot properly read.
To address this potential problem, the TTY Session Start procedure _ttyss.p adds the AppBuilder's stream code page session setting to the front of the command line it writes to the message file. Each time the character client reads the character message file, it examines the command line string and checks the code page; if it's not the same as its setting, the character client reopens the file with code page specified in the message file. The character client can read and check the stream code page value because the first 128 (positions 0 through and including 127) characters of all code pages are the US-ASCII characters, and code page names are made up of only US-ASCII (positions 0 through and including 127) characters.
The command line in the character message file contains, among other elements, a command that the AppBuilder and character client sessions use to communicate character run instructions and status information.
The following table identifies the character message file commands:
Character Message File Commands |
Description |
RUN |
When read by the character client, the RUN command instructs the Character Run Window to run the character procedure. When read by the AppBuilder session, it indicates the character procedure is currently running in the Character Window. |
RUN-DEBUG |
When read by the character client, it instructs the Character Run Window to run the character procedure by invoking it in the Progress Debugger. When read by the AppBuilder session, it indicates the character procedure is currently running in the Character Window in debug mode. |
OK |
When read by the AppBuilder session, it indicates the character procedure has ended running and the Character Run Window is waiting to run another procedure. The OK command is not sent to the character client. |
OK-EXIT |
When read by the character client, it instructs the Character Run Window to close and end its client session. When read by the AppBuilder session, it indicates the character client session has ended and AppBuilder returns to design-mode from run-mode. |
2.1.7 Closing the Character Run Window
To close the Character Run Window, the end user chooses Compile®Close Character Run Window in the AppBuilder Main window. This action:
When TTY Session Run procedure detects the character message file has been deleted, it ends the character client session, thereby closing the Character Run Window. If no character message file exists, the TTY Session Close procedure displays a message indicating the Character Run Window is not open.
2.1.8 Character Client Connection: Tips and Issues
Note the following information as it pertains to character client connections:
2.1.9 Source File Descriptions
There are several source files that implement most of the character run support. Refer to section 2, "Architecture", earlier in this document. It describes the source files for character run support.
Not Applicable
4. Primary Algorithms and Processes
This section more fully explains how the AppBuilder runs a character procedure, focusing on the technical information related to the procedure steps described earlier in this document:
AppBuilder then runs the TTY Session Start procedure adeuib/_ttyss.p, which writes information to the character message file that is needed by the character client session to run the character procedure. The information includes run command (RUN or RUN-DEBUG), the name of the procedure to run, and the databases to connect.
TTY Session Start procedure then waits for the character client session to communicate back to it using the character message file.
TTY Session Run procedure reads the character message file command line, connects the necessary databases, and runs the specified character procedure.
When the character run procedure ends, TTY Session Run procedure writes to the character message file the "OK" command to indicate to the AppBuilder that it is waiting for another procedure to run.
User can change the character procedure and run it again, or open and run another character procedure (see item 1).
When TTY Session Run procedure detects the character message file has been deleted, it ends the character client session, thereby closing the Character Run Window.
Not Applicable
Not Applicable
Not Applicable
Not Applicable
Not Applicable
10. Requirements and Strategies
Not Applicable
Not Applicable
The following document contains additional information about Character Run Support: