Contents of this Section:

Completing Your Application
Generating Progress 4GL Source Code
Host Communications Parameters
Writing Stored Procedures in Oracle PL/SQL
Writing Java Servlet Host Procedures
Writing Active Server Pages in VBScript
Writing Host Procedures in the Progress 4GL
Testing and Deploying Your Application

When designing your application, you should consider and answer the following questions at the outset:

1. Will any of the processing be done in a state-aware mode, or will all processing be "stateless"? This is probably the most important issue that must be answered up front, as it has a major impact on the number of host processes that will be needed for a given transaction workload and on how the host and client sides will be designed. See Writing Host Procedures in the Progress 4GL below for more details on the issues involved with this decision.

2. How will security be handled? A common approach is to present the user with a login screen (User ID and password) when the client application starts, followed by a host task which validates the user against a database table. Once approved, a user's identity must be sent in some manner as parameters with each host task, particularly in a stateless model, since any available host process might receive a processing request from any client, unlike in traditional character terminal applications.

3. How will the application maintain "context" between client requests in a stateless model? Context information includes such items as the nature of the latest action that the client had previously completed, intermediate values, security settings, and many similar data values. See the "Stateless and Event-Driven Programming" document for more on this topic.

4. What parameters must be sent to the host for each host task? As mentioned above, in a stateless model there will usually be User ID/password or session ID parameters that are sent each time, plus other parameters appropriate for the particular task, such as sending a customer number to the host in order to display the customer's name and address on the client screen.

5. What processing will the host do for each host task? If the database will be updated, how will the transaction be structured? How will the client be notified, or how will its original screen contents be restored, if the transaction is unwound (if the host program executes an "undo")?

6. What the possible responses that the host may return to the client for each possible outcome of the processing? If the processing completes normally, what will be changed on the client? If errors occur, how will the client be notified?

7. (Progress only) What directory structure will be used for the Progress programs (".p" source files) and include files (".i" source files)?

8. What naming conventions will be used for host procedures and related files?

Generating Progress 4GL Source Code

In a Progress host environment, Jargon Writer can automate some of the creation of the host programming for you by generating one or more Progress ".p" programs that handle the receiving and parsing of the parameters sent from the client to the host for each remote procedure call ("rpc"). When you have completed the definition of each rpc in your client application, you are ready to generate the 4GL source programs.

For the automated code generation to work correctly, each rpc must be defined within a separate function, starting with a call to "MakeURL", followed by zero or more "rpc.AddNameValuePair" statements for any host parameters, and ending with "rpc.Execute".

Here is a simple example of a script containing one rpc call:

    function MakeURL(program, procedure) {
      var HostURL = preference.GetPreference("HostURL");
      var Script  = preference.GetPreference("Script");
      rpc.SetURL(HostURL + "/" + Script + "/" + program);
      rpc.AddNameValuePair( "ProcName", procedure);
    }

    function Dummy() {
     MakeURL("debug/ForDocs.p", "MainProc");
     rpc.AddNameValuePair( "TF0", textfield0.GetText());
     rpc.Execute();
    }

The steps to follow are straightforward:

1. In the Script Editor Window, review the parameters of each rpc to make sure that you have correctly entered the names for the Program file and the Internal Procedure name as parameters of a "MakeURL(program,procedure)" statement, and that the MakeURL function has been defined. If the host is a Unix system, also remember that Unix is case-sensitive, so double-check the case of the Program filename.

 
2. Create all subdirectories referenced in any of the host parameter program filenames or include filenames. These must be created both on the client (in Jargon Writer's working directory) and on the host (in the WebSpeed or AppServer working directory). If you are using NFS (Network File System) or other techniques to map a host directory under the client working directory, then there will only be one set of subdirectories that are shared by both host and client.

 
3. In Jargon Writer, open the primary app file for which you want to create 4GL source code. Also, be sure to open all other app files that are referenced by the primary app. If this is not done, the 4GL source may not be created correctly if any host parameters are values of components in these referenced apps.

 
4. Now, generate the 4GL program file(s) by selecting Run-->Generate Host Procedure from the menubar, or click the fifth button in the toolbar. Jargon Writer will examine all functions in the primary app that contain "MakeURL" and "rpc.Execute" statements, and will create all referenced programs and procedures and all necessary temp-tables, variables and logic to parse the parameters and populate these variables, as well as referencing the include files in which you will put your host business logic.

 
5. If the host directories are not mounted under the client working directory, you must now move the generated programs to the host system. This may be done by using a file transfer program (FTP) that runs on the client.
 
IMPORTANT: If you have a Windows client and a Unix host, be sure to specify "text" mode (not "binary" mode) in FTP, before transferring the file. Since a Progress program is a text file, each line is delimited by some special character(s). On Windows systems, this is a CR/LF character pair, but on Unix, it should only be a LF character. (LF means line feed which is decimal "10"; CR means carriage return which is decimal "13"). In binary mode, FTP will not strip out the CR characters when uploading a text file from Windows to Unix, and this may cause a variety of problems which you are better off not experiencing firsthand.

• Several include file references in the main procedure section
• A separate "internal procedure" section for each procedure named in a "MakeURL" function call in the xml script
• A set of variables and the include statements to populate them, within each internal procedure, for each host parameter defined in an "rpc.AddNameValuePair" statement in the script function that calls that procedure

• The variable names will be the same as the parameter names specified in the client script
• The data type for each variable may be specified as an optional third parameter of each "rpc.AddNameValuePair" statement. The choices are: date, decimal, integer, logical (boolean), or character (default is character).

Here is a simple example of a generated program (with some added comments):

 /* top-level include file for temp-tables and other functions/procedures */
{demo/cust.i}

procedure getcust:
  def var tCustNum         as int  no-undo.
  {jsi/getint.i &fieldname='tCustNum' &targetvar=tCustNum}
  {jsi/output.i}
  {demo/cust/getcust.i}  /* Business Logic goes into this include file */
end procedure.

procedure setcust:
  def var tCustNum         as int  no-undo.
  def var tCustName        as char no-undo.
  def var tLastOrderDate   as date no-undo.
  def var ckOnCreditHold   as logi no-undo.
  def var tCreditLimit     as dec  no-undo.
  {jsi/getint.i  &fieldname='tCustNum'       &targetvar=tCustNum}
  {jsi/getchar.i &fieldname='tCustName'      &targetvar=tCustName}
  {jsi/getdate.i &fieldname='tLastOrderDate' &targetvar=tLastOrderDate}
  {jsi/getlog.i  &fieldname='ckOnCreditHold' &targetvar=ckOnCreditHold}
  {jsi/getdec.i  &fieldname='tCreditLimit'   &targetvar=tCtCreditLimit}
  {jsi/output.i}
  {demo/cust/setcust.i}  /* Business Logic goes into this include file */
end procedure.

Host Communications Parameters
When a host task is executed on the client, it always sends one or two parameters automatically: the stored procedure name (for Oracle), or the Program name and the Internal Procedure name (for Progress). These parameters are defined by "rpc" methods in the Script Editor for the host task. These parameters tell the middleware which program should be run, and which internal procedure should be run within the program.

For some tasks that may be all there is to it -- no other parameters are needed. Examples might be a host task which kicks off a host report program that has no options, or a batch update program that likewise needs no options. In these examples, the host processing logic is "hard-wired".

However, most host tasks will require one or more parameters in order to accomplish the desired processing logic. As discussed above, a common parameter is a User ID or session ID of some kind, which is used both for security purposes and to access context information that may have been saved (in the database or elsewhere) from a previous interaction.

For an inquiry ("get") task, the client might supply a customer number as a parameter, so that the host task can find that customer in a database table and send back the customer's name and address values to be displayed on the client screen.

For an update ("set") task, the client will send all data fields that the user may have filled in, so that the database can be updated with these values.  Many other scenarios are also possible.

Each parameter sent by the client can be a constant, or it can be a result of invoking some method on a client component object, such as getting the current value of a quantity textfield. All parameters populate a corresponding variable (Progress) or input parameter (Oracle) in the host procedure.

The data type (character, integer, decimal, date, logical) of the Oracle input parameters or of the Progress variables and temp-table fields must match the corresponding data type of the client component or constant. Note that the Progress "logical" data type is referred to as "boolean" in Java (and in Jargon Writer). All values of buttons, checkboxes and radio buttons will be mapped to logical variables. Current selection values for comboboxes and listboxes will be mapped to character variables.

Writing Stored Procedures in Oracle PL/SQL

(This section is not yet available).

Although Jargon Software does not supply a source code generator for Oracle PL/SQL, the means to do so are provided by fact that the name of the Java class that generates the source code is a parameter in the preferences.ini file used by Jargon Writer. The parameter name and default value for Progress 4GL source code generation is: SourceCodeGeneratorClass=SrcCodeGenP4GL . If you are interested in writing a source code generator for Oracle PL/SQL or for any other host environment, please contact Jargon Software (email support@jargonsoft.com)

Please see "Host Procedures for Oracle PL/SQL" for a list of the "jsi" procedures that can be used in PL/SQL to send data and commands from the host to a client app.

Writing Java Servlet Host Procedures
(This section is not yet available).

Although Jargon Software does not supply a source code generator for Java servlets, the means to do so are provided by fact that the name of the Java class that generates the source code is a parameter in the preferences.ini file used by Jargon Writer. The parameter name and default value for Progress 4GL source code generation is: SourceCodeGeneratorClass=SrcCodeGenP4GL . If you are interested in writing a source code generator for Java servlets or for any other host environment, please contact Jargon Software (email support@jargonsoft.com).

To obtain a copy of the "jsi" host methods for Java servlets, please contact Jargon Software (email support@jargonsoft.com).

Writing Active Server Pages in VBScript
(This section is not yet available).

Although Jargon Software does not supply a source code generator for Active Server Page (ASP) VBScript, the means to do so are provided by fact that the name of the Java class that generates the source code is a parameter in the preferences.ini file used by Jargon Writer. The parameter name and default value for Progress 4GL source code generation is: SourceCodeGeneratorClass=SrcCodeGenP4GL . If you are interested in writing a source code generator for ASP VBScript or for any other host environment, please contact Jargon Software (email support@jargonsoft.com).

To obtain a copy of the "jsi" host methods for ASP VBScript, please contact Jargon Software (email support@jargonsoft.com).

Writing Host Procedures in the Progress 4GL
Coding the host-side business logic for your application is done by creating each of the include files that were defined in the client host tasks, and writing the Progress 4GL statements that accomplish the desired processing. All logic should be placed in these include files. The automatically generated program should never be modified, as it may be regenerated in the future if new parameters are added or for other reasons. The Progress 4GL host procedures used with AppServer or with WebSpeed use standard Progress 4GL syntax (Version 9), with two exceptions:

1. No screen I/O statements are allowed, since the WebSpeed or AppServer agent does not have a direct connection to the client screen. This means that no "DISPLAY", "ASSIGN", "PROMPT-FOR", "SET" or "UPDATE" statements can be used in relation to screen frames, and no screen "frames" or other screen "widgets" can be used with the default input and output streams, nor can INPUT FROM TERMINAL or OUTPUT TO TERMINAL be used.

2. In "stateless" mode, the WebSpeed or AppServer agent starts a new copy of the program each time, so variable and temp-table contents are not retained between interactions with the client ("context" is not maintained). In fact, on a host system with two or more agents running, the agent which handles one client host task may not be the same agent that handles the next host task from that same client. This means that, if knowledge of previous client actions is needed, the host must have some other way to get this context information. Possible means of doing this include storing context information in a database table or a text file and associating it with a User ID or session ID that is sent by the client with each interaction, or sending all context information to the client and having the client send it back each time. Each approach has different benefits and drawbacks, which are beyond the scope of this document (see "Stateless and Event-Driven Programming" for a more detailed discussion of this topic).

Then, use the "jsi" include files to create one or more commands to be sent back to the client. These commands may change the contents of a client component (such as displaying a customer name in a textfield) or change the state of a component (such as disabling a button so that it cannot be clicked). New components may also be created dynamically by host commands, with all of the same options for assigning component properties as are available when creating components in Jargon Writer. Other important general-purpose include files allow a host program to invoke any client method on a client object, and to invoke any existing client tasklist to perform whatever actions it specifies. For details of available "jsi" include files, see the Host Methods for Progress 4GL section.

Some important syntax rules to remember:

1. A literal character value used as an include parameter should be enclosed in single quotes.

Example: &b='true'.

This is needed because single quotes are passed through to the referenced include file, and many jsi include files contain nested include files that require quoted parameters to pass through multiple levels of include parameters. (Double quotes are not passed through and do not work correctly for this purpose).

2. If using a literal character value with embedded spaces as an include parameter, it should be enclosed in an outer pair of double quotes and an inner pair of single quotes.

Example:  &msg="'Hi there'".

Do not put any spaces between the double and single quotes. Failure to follow these rules will result in some very misleading Progress compiler syntax errors.

3. All "jsi" include files are either single statements or contain enclosing "DO:  END" blocks that make them the equivalent of a single statement. This means that you do NOT need to enclose "jsi" statements with your own "DO:  END" blocks inside of "IF" statements or otherwise. For example, you can write code such as:

IF condition1 THEN {jsi/...}. ELSE {jsi/...}.

Testing and Deploying Your Application
When you have completed the coding of all include files, use a compiler provided by the language vendor, or the Jargon Software RDU utility (Progress only), to compile the host procedure to make sure there are no syntax errors.

Then, open the client application in Jargon Writer and run it by selecting Run-->Execute from the menubar or by clicking the fourth toolbar button. Test as many different scenarios as possible. If possible, get real end users to test your application. They will often try sequences of actions that were not envisioned when the application was designed, and may expose possible problems that other users could experience. Also, observing a "naive" user (one who did not participate in designing the application) may highlight areas where the user interface is confusing or misleading.

If the host communication progress bar never stops, the host process may have failed. To view any error messages generated by a host procedure, use a text editor on the host to view the contents of any available log files. See the Progress and Oracle installation instructions for details on log files.

When your quality assurance testing is completed, the final step is to deploy the client and host programs that you have developed. For information on the various ways to deploy the client-side files, see the Jargon Software Installation Instructions. The host procedures are deployed like any other application. You can deploy source files, encrypted source files, or object files only, depending on your organization's policies and requirements.