Displaying a Row on a Form

This example uses forms to collect a customer number from the user and then display a
summary of all information about the customer. It demonstrates the value of 4GL forms, which
give the user an interface for interacting with the database. To move information from the
database to a form, you first retrieve the information into program variables and then display
the information on the form. Similarly, to update a database row, you set program variables
based on the values of form fields and then update the database row from the variables. The
following form appears in this example:

This example introduces the following 4GL programming techniques:

Retrieving information from the database.

Collecting information from the user with a form.

Handling data entry, database, and program errors.

Returning values from functions.

Manipulating a record composed of values of different types.

Extracting and addressing a substring within a character value.

Defining Records

This example defines a record to store several kinds of information about customers.
Resembling a C struct definition or a Pascal record, a 4GL record is a variable that specifies a
set of other variables. The advantage of defining a record is that you can manipulate the
components of the record as a unit. A record differs from an array in that an array is a list of
values of the same type, whereas a record is a single collection of values that may have many
different types. The example defines the record globally so that it is available in all functions.

Returning Values from Functions

A 4GL function can return values to the calling statement. You list the variables that receive
the values in the RETURNING clause of the CALL statement. If the function returns a single
value, you can also call the function in an expression to supply a value for the expression. For
example, a function can return a true or false value that is tested by a CASE, IF, or WHILE
statement. Testing a single value may seem strange if you are used to testing Boolean
expressions containing an equals sign or other logical operator. You should recognize that a
Boolean expression always evaluates to the true or false value. Thus, the conditional
statement really determines whether to execute its code block based on a single value.

Recovering from Runtime Errors

By default, 4GL terminates whenever a statement generates an error. This behavior is

desirable in most cases because you do not want to continue executing with an unknown
program state. However, in some situations you may want to recover from the error within the
program and continue executing the program. The following technique suppresses termination
for the statement that can generate the recoverable error:

Suppress termination with the WHENEVER ERROR CONTINUE statement.

Execute the statement.

Resume termination with the WHENEVER ERROR STOP statement.

Use an IF statement to execute the recovery code when the built-in status variable has a
value less than zero.

4GL automatically sets the status variable to zero when a statement succeeds and to a
negative number when a statement fails. After an SQL statement, the status variable shows
the same number as the built-in SQLCA.SQLCODE variable. Unlike SQLCODE, however, 4GL also
sets the status variable after a 4GL screen statement.

The prompt_window() function uses this technique to adjust the positioning of a window, but
later examples make extensive use of this technique for SQL statements. SQL statements are
particularly appropriate for recovery because an SQL statement can be invalidated at runtime
by changes in the database schema or by locks on the desired rows.

You should always use the standard termination behavior for statements for which you are not
providing recovery code. The continuation behavior increases the size of the executable code
compiled from the 4GL code. In addition, terminating the program is the appropriate recovery
mechanism for statements for which you have not provided explicit recovery code.

Note that the WHENEVER statement is not a runtime statement that applies to statements in
the thread of execution. Instead, WHENEVER is an instruction to the compiler that takes effect
when the module is compiled. That is, the WHENEVER statement applies to all lower lines
within the module until the next WHENEVER statement or the end of the module. The
WHENEVER statement does not apply to functions called from the covered lines.
Function Name Purpose cust_summary() Loops through the action until the user is done.
get_custnum() Obtains a customer number from the user.

get_summary() Uses a series of SELECT statements to fetch from the database and summarize
customer information.

dsply_summary() Displays the customer summary on a form.

tax_rates() Supplies the appropriate tax schedule for a customer.

init_msgs() Initializes the members of the ga_dsplymsg array to null. See the description in
Example 2.

prompt_window() Displays a message and prompts the user for confirmation. This function is
a variation of the

message_window() function that appears in Example 2.

The f_custkey and f_custsum Forms

1 The SCREEN and ATTRIBUTES sections of the form specification fulfill the same purpose as
described in the section The f_logo Form Specification on page 34. In contrast with Example
3, for which the database was FORMONLY, the f_custkey form and f_custsum form are defined
to work with the stores7 demonstration database. The TABLES section specifies the relevant
tables from the database. The ATTRIBUTES section can associate a field tag with a database
column to assign the data type of the database column to the corresponding screen variable.
Note that, if the data type of the database column changes, you must recompile the form.

The f001 field in the f_custkey form is specified as a member of the FORMONLY table. You
use this pseudo-table within the specification of a database form for fields that cannot or
should not correspond to a database column.

The customer_num column of the customer table has a SERIAL data type. To prevent a user
from inputting or updating a SERIAL value, 4GL automatically moves the cursor out of a screen
field that is defined like a SERIAL field. Because the user must be able to enter a customer
number to select the customer, the f_custkey form specification defines the customer_num
screen variable as a member of the FORMONLY table. The customer_num name merely
clarifies for any programmer reading the code that the information entered in the field
corresponds to the database column. The name does not apply any characteristics of the
column.
3 The f002, f003, and f004 fields in the f_custsum form are also specified as members of the
FORMONLY table. These formonly fields display information synthesized from several columns
in several tables.

Mostrar una fila en un formulario

Este ejemplo utiliza formularios para recopilar un nmero de cliente del usuario y luego
mostrar un resumen de toda la informacin sobre el cliente. Demuestra el valor de los
formularios 4GL, que proporcionan al usuario una interfaz para interactuar con la base de
datos. Para mover informacin desde la base de datos a un formulario, primero recupera la
informacin en variables de programa y luego muestra la informacin en el formulario. De
forma similar, para actualizar una fila de base de datos, se establecen variables de programa
basadas en los valores de los campos de formulario y luego se actualiza la fila de la base de
datos a partir de las variables. El siguiente formulario aparece en este ejemplo:
Este ejemplo introduce las siguientes tcnicas de programacin 4GL:
Recuperacin de informacin de la base de datos.
Recopilar informacin del usuario con un formulario.
Manejo de entrada de datos, base de datos y errores de programa.
Devolver valores desde funciones.
Manipulacin de un registro compuesto por valores de diferentes tipos.
Extraccin y direccionamiento de una subcadena dentro de un valor de carcter.
Definicin de registros
Este ejemplo define un registro para almacenar varios tipos de informacin acerca de los
clientes. Parecido a una definicin de estructura C o un registro Pascal, un registro 4GL es una
variable que especifica un conjunto de otras variables. La ventaja de definir un registro es que
puede manipular los componentes del registro como una unidad. Un registro difiere de una
matriz en que una matriz es una lista de valores del mismo tipo, mientras que un registro es
una coleccin nica de valores que pueden tener muchos tipos diferentes. El ejemplo define el
registro globalmente para que est disponible en todas las funciones.
Devolucin de valores de funciones
Una funcin 4GL puede devolver valores a la sentencia llamante. Enumerar las variables que
reciben los valores en la clusula RETURNING de la instruccin CALL. Si la funcin devuelve un
valor nico, tambin puede llamar a la funcin en una expresin para suministrar un valor para
la expresin. Por ejemplo, una funcin puede devolver un valor verdadero o falso que es
probado por una instruccin CASE, IF o WHILE. La prueba de un solo valor puede parecer
extraa si est acostumbrado a probar expresiones booleanas que contengan un signo igual u
otro operador lgico. Debe reconocer que una expresin booleana siempre evala al valor
verdadero o falso. Por lo tanto, la instruccin condicional realmente determina si ejecutar su
bloque de cdigo basado en un solo valor.
Recuperacin de errores de tiempo de ejecucin
Por defecto, 4GL termina cada vez que una sentencia genera un error. Este comportamiento es
deseable en la mayora de los casos porque no desea continuar ejecutndose con un estado de
programa desconocido. Sin embargo, en algunas situaciones es posible que desee recuperarse
del error dentro del programa y continuar ejecutando el programa. La siguiente tcnica
suprime la terminacin de la sentencia que puede generar el error recuperable:
Suprima la terminacin con la sentencia WHENEVER ERROR CONTINUE.
Ejecutar la sentencia.
Reanude la terminacin con la instruccin WHENEVER ERROR STOP.
? Utilice una instruccin IF para ejecutar el cdigo de recuperacin cuando la variable de
estado incorporada tiene un valor menor que cero.
4GL establece automticamente la variable de estado en cero cuando una sentencia tiene
xito y en un nmero negativo cuando una sentencia falla. Despus de una instruccin SQL, la
variable de estado muestra el mismo nmero que la variable SQLCA.SQLCODE incorporada. Sin
embargo, a diferencia de SQLCODE, 4GL tambin establece la variable de estado despus de
una declaracin de pantalla 4GL.
La funcin prompt_window () utiliza esta tcnica para ajustar el posicionamiento de una
ventana, pero ejemplos posteriores hacen uso extensivo de esta tcnica para sentencias
SQL. Las sentencias SQL son particularmente apropiadas para la recuperacin porque una
sentencia SQL puede ser invalidada en tiempo de ejecucin por cambios en el esquema de la
base de datos o por bloqueos en las filas deseadas.
Siempre debe utilizar el comportamiento de terminacin estndar para las sentencias para las
que no est proporcionando cdigo de recuperacin. El comportamiento de continuacin
aumenta el tamao del cdigo ejecutable compilado a partir del cdigo 4GL. Adems, finalizar
el programa es el mecanismo de recuperacin apropiado para las sentencias para las que no
ha proporcionado cdigo de recuperacin explcito.
Tenga en cuenta que la sentencia WHENEVER no es una instruccin runtime que se aplica a
sentencias en el subproceso de ejecucin. En su lugar, WHENEVER es una instruccin para el
compilador que surte efecto cuando se compila el mdulo. Es decir, la instruccin WHENEVER
se aplica a todas las lneas inferiores dentro del mdulo hasta la siguiente instruccin
WHENEVER o al final del mdulo. La instruccin WHENEVER no se aplica a las funciones
llamadas desde las lneas cubiertas.
Funcin Nombre Propsito cust_summary () Rodea la accin hasta que el usuario
termine. Get_custnum () Obtiene un nmero de cliente del usuario.
Get_summary () Utiliza una serie de sentencias SELECT para obtener de la base de datos y
resume la informacin del cliente.
Dsply_summary () Muestra el resumen del cliente en un formulario.
Tax_rates () Proporciona la programacin de impuestos apropiada para un cliente.
Init_msgs () Inicializa los miembros de la matriz ga_dsplymsg en null. Vea la descripcin en el
Ejemplo 2.
Prompt_window () Muestra un mensaje y solicita confirmacin al usuario. Esta funcin es una
variacin de la
Message_window () que aparece en el ejemplo 2.
Los formularios f_custkey y f_custsum

1 la pantalla y ATRIBUTOS secciones de la especificacin de forma cumplen el mismo

propsito como se describe en la seccin La f_logo Especificacin Form en la pgina 34. En
contraste con el Ejemplo 3, para lo cual la base de datos era FORMONLY, la forma f_custkey y
forma f_custsum son Definido para trabajar con la base de datos de demostracin stores7. La
seccin TABLES especifica las tablas relevantes de la base de datos. La seccin ATRIBUTOS
puede asociar una etiqueta de campo con una columna de base de datos para asignar el tipo
de datos de la columna de base de datos a la variable de pantalla correspondiente. Tenga en
cuenta que si cambia el tipo de datos de la columna de la base de datos, debe volver a
compilar el formulario.

El campo F001 en forma f_custkey se especifica como un miembro de la mesa

FORMONLY. Utiliza esta pseudo-tabla dentro de la especificacin de un formulario de base de
datos para campos que no pueden o no deben corresponder a una columna de base de datos.
La columna customer_num de la tabla customer tiene un tipo de datos SERIAL. Para evitar que
un usuario ingrese o actualice un valor SERIAL, 4GL mueve automticamente el cursor fuera de
un campo de pantalla que se define como un campo SERIAL. Debido a que el usuario debe
poder introducir un nmero de cliente para seleccionar al cliente, la especificacin de
formulario f_custkey define la variable de pantalla customer_num como miembro de la tabla
FORMONLY. El nombre customer_num simplemente aclara para cualquier programador que
lea el cdigo que la informacin introducida en el campo corresponde a la columna de la base
de datos. El nombre no aplica ninguna caracterstica de la columna.

3 Los F002, F003, F004 y campos en forma f_custsum tambin se especifican como
miembros de la tabla FORMONLY. Estos campos formonly muestran informacin sintetizada de
varias columnas en varias tablas.