Introduction to User Language

Overview

Model 204 is a comprehensive, multipurpose database management system for IBM and compatible mainframes.

Model 204 incorporates a versatile self-contained User Language programming language for ad hoc inquiry, simple and complex data retrieval, updating, report writing, transaction processing, and application development. No background in programming is required to use the query statements; yet, as you gain experience with User Language, you can write increasingly complex programs, called requests.

Request structure

A typical User Language request begins with statements that select records from one or more files. Loop statements then specify a series of operations to be performed on each of the selected records. The operations for each record can be simple output, field update, or computation statements. User Language also provides statements that generate loops for each value of a field, for each occurrence of a repeating field, and for each element of an array.

In addition to record, value, occurrence, and index loops, User Language also provides statements for conditional execution and loop control.

Example

The following example illustrates the simplicity of User Language. Using English-like statements, you can select from a CLIENTS file all drivers who are registered in San Diego, whose agent is either Kessler or Wagner, and who have a total premium greater than $200. The User Language request would contain these statements:

BEGIN GET.RECS: FIND ALL RECORDS FOR WHICH CITY = SAN DIEGO TOTAL PREMIUM IS GREATER THAN 200 AGENT = KESSLER OR WAGNER END FIND FOR EACH RECORD IN GET.RECS PRINT FULLNAME WITH AGENT AT COLUMN 30 END FOR END

The online output from this request would be in this format:

FREEMAN, IRA U. KESSLER GRIFFIN, SCOTT G. KESSLER HEATH, RUTH S. KESSLER O'BRIEN, EARL Q. WAGNER OWENS, MARGARET C. WAGNER RICHARDSON, LISA O. WAGNER

Stored procedures

Any combination of commands and User Language statements can be saved for later execution. These sequences can be rerun at any time, or edited and rerun at any time, without being reentered. Stored procedures are permanently stored in your database until they are deleted or revised.

Stored procedures can be included as parts of requests, or they can be run alone either unconditionally or as a result of a specified test. Typical practice is to store commonly used requests, application procedures, screen layouts, or print statements for standard report formats.

Stored procedures can be made more flexible by using techniques which call for end-user input at runtime by suspending execution and displaying a prompt. The user's input is used by the procedure as the value of a variable which can specify, for example, a record search criterion.

Optional User Language/DATABASE 2 Interface

Rocket Software offers the User Language/DATABASE 2 Interface, which allows you to access DB2 data from within Model 204 User Language procedures. This interface gives you the following capabilities:

• Allows you to use User Language %variables as host variables from within SQL statements
• Allows you to issue SQL commands from within a User Language procedure

See the Rocket User Language/DATABASE 2 Interface Guide for more information about this product.

MP/204

The MP/204 product provides full support of multiple processing capability under the z/OS operating systems. MP/204 allows your site to take full advantage of multiprocessor configurations for Model 204.

Refer to the Rocket Model 204 System Manager's Guide for information on using MP/204, including User Language considerations.

Parallel Query Option/204

Parallel Query Option/204 (PQO) is a Model 204 distributed processing facility that allows the sharing of data between two or more copies of Model 204.

Parallel Query Option/204 provides User Language applications access to remote files. A single User Language transaction can read and/or update multiple remote files.

Types of User Language statements

User Language consists of several types of statements, including those listed below. Each type of statement is described in more detail in the following sections.

Type of statement	Provides...
Record selection statements	Selection based on the values of one or more fields, combined with a full range of Boolean facilities.
Logic and control statements	Record set looping, request termination, and data dependent operations.
Computational facilities	Full range of numeric and string computations.
Reporting operations	Facilities suitable for simple ad hoc requests and sophisticated multifile reports.
Full-screen formatting facilities	For the creation of full-screen applications and for the control of the attributes (such as color and highlighted fields) for formatted screens.
Database maintenance operations	Wide range of update facilities.
File and terminal access statements	User Language image facility to allow access to VSAM and sequential files and to a terminal.
Program communication facilities	Connection and communication between a User Language request and a CICS transaction or CMS EXEC, as well as LU 6.2 program-to-program processing.
Request development and manipulation statements	Online application development facilities for the creation, storage, modification, and execution of User Language requests.

Record selection

You can select records from Model 204 databases on the basis of one or more field values. Complex retrieval conditions can be created using AND, OR, NOT, and NOR. The selection criteria can include comparison to alphanumeric patterns and previous record selection lists.

Logic and control statements

User Language provides statements that allow a portion of a program to loop based on found record sets, field values, index values, or a specified number of repetitions. Conditional processing statements, including IF statements, are supported. User Language also has statements to control request termination such as END, END MORE, and STOP.

Computation

User Language can perform arithmetic and logical operations using constants, field values, special temporary variables, and functional values. You can define any number of temporary variables within the context of a request. Variables can be set in assignment statements or used within expressions, and they can be arrays. The number of significant digits retained by fixed point or string variables can be set. Variable names always start with a percent sign (for example, %YEAR).

A set of built-in functions extends the capabilities of User Language. These functions provide facilities for data editing and validation, character string manipulation, global variables, and current date and time. The FORTRAN set of mathematical functions is also available as an option. Function names always start with a dollar sign (for example, $DATE).

Expressions are formed by combining constants, variables, functions, field names, or other expressions with operators. Parentheses can be used to alter the normal sequence of operations.

Computational results can be used for output purposes, to store derived information in the database, or to control the sequence of operations within a request.

Report statements

User Language provides statements for sorting and formatting output from requests into reports. System reports can also be generated to the journal or audit trail.

Entire records, the contents of selected fields within records, or computations based on the selected fields can be formatted and displayed. Output can be displayed at the terminal, directed to a data set for intermediate storage, or directed to system spooling facilities (that is, printers).

Field values can be positioned anywhere on the terminal display: left-justified, right-justified, truncated between two positions, or positioned at variable tab stops. Field values can be concatenated and edited for output. Quoted strings can be printed for output labels or comments. Page header and trailer lines can be entered or deleted on multiple page reports. Paging is specified by a variable line count parameter; new page and multiple line-skip statements are provided.

Output can be formatted using the full-screen feature and displayed for subsequent review and data entry.

Full-screen formatting

User Language has a comprehensive set of full-screen capabilities that display screens that are formatted with user-specified titles, prompts, and input items. These capabilities are particularly useful in data entry applications.

You can format menus and screens, specify validation tests for input fields entered by the end user, and to select certain optional terminal facilities. These facilities include:

• Use of bright intensity and terminal color options to highlight particular fields on the screen
• Fields to blink on and off
• Audible terminal alarm to alert the end user that a menu or screen is being displayed.

When the full-screen feature is used with a video display terminal, the full screen is treated as a single entry. The entire screen is transmitted to a Model 204 request at one time, rather than field by field. Thus, the terminal operator can enter fields in any order on the screen and correct input data at any time before the screen is transmitted.

Database maintenance

Database store, update, and delete capabilities are provided by Model 204 for sets of selected records as well as for individual records. You can add or delete entire records and add, change, or delete individual fields in a set of one or more records.

No restrictions are placed on allowable data maintenance operations by the original configuration of the file. For example, existing individual records can be extended to include new fields neither previously used nor included in the file.

File and terminal access

The User Language image facility provides read access to VSAM KSDS files as well as read and write access to sequential files and to a terminal. A terminal can be a physical device or a Host Language application program connected to User Language through IFDIAL.

Program communication

You can request communication with user-written CICS programs or CMS EXECs. These facilities include a process-to-process facility in CICS and CMS, a CICS transfer control facility, a SNA Communications Server (formerly VTAM) transfer control facility, and the optional Horizon Interface, which supports LU 6.2 communications.

Request development and manipulation

You can name and save User Language procedures for reuse. User Language allows requests to be named and saved as procedures, to be reused. The Subsystem Management facility of Dictionary supports the definition of a collection of procedures as a subsystem, which can have its own characteristics and shared routines.

Database structure

Model 204 databases are structured to provide a very high degree of flexibility, data independence, and retrieval efficiency. Model 204 databases are groups of files that consist of sets of variable-length, variable-format records.

Records consist of sets of individually named variable-length fields, which can be of several types. The variable-length, variable-format records provide independence of the database structure from users' application queries and updates.

Fields

The fundamental unit of Model 204 data is a pairing of a field name and a corresponding field value (field name = value pair). For example, in CITY = SAN DIEGO, CITY is the field name and SAN DIEGO is the field value. Field names and field values are treated by Model 204 as variable-length strings of information. Both field names and field values can contain any number of words up to a limit of 255 characters.

When more than one space is left between words in a field name or value, the extra spaces are ignored. Blanks surrounding the equal sign are optional. Therefore:

NAME = JOHN SMITH

and

NAME=JOHN SMITH

are treated as if each were

NAME = JOHN SMITH

Field names can appear more than once within single records. Such multiply occurring fields can be used in expressing retrieval conditions in the same manner as other fields. File maintenance statements are provided for changing or deleting multiply occurring fields.

Each Model 204 field has a set of one or more attributes called the field description. In Request structure, the field CITY might be a KEY field. Thus, records containing the value CITY = SAN DIEGO can be located through the index (Table C), rather than by directly searching the data records (Table B). CITY might also be an FRV (for-each-value) or ORDERED field, which means that it can be used with FOR EACH VALUE statements (see Value loops).

Records

Records are collections of fields. Because the field, not the record, is the fundamental unit of data, records within a given file can all have the same format (same collection of field names), or they can have different formats. File maintenance activities such as adding new fields to individual records can be performed at any time.

Model 204 imposes no limit on the number of fields per record.

Files

A collection of related records stored together with their associated index pointers forms a Model 204 file.

The creation of a file, the definition of field names, and the initial loading of records are the responsibility of the file manager. These operations are described in detail in the Rocket Model 204 File Manager's Guide.

Once a file has been defined to Model 204, records can be added or changed by using User Language statements.

Files are discussed in more detail in the next section.

Files

Model 204 offers a unique file structure which provides several different ways of ordering records to allow for differing database requirements.

Inverted files

A data access method is called inverted when the DBMS maintains, in addition to the data records, a map of the records that contain particular values for certain fields called retrieval fields. Model 204 has a unique approach to handling inverted structures. It permits very rapid access to records that satisfy selection conditions based on the values of key fields. The inversion maps or indexes provide several paths through which you can access the data.

Composition of a Model 204 file

A file is stored on one or more physical data sets on direct access devices.

A file is divided into the following logical sections:

Logical section	Purpose
File Control Table	Keeps track of file parameter settings, data set or file definition names of all data sets in the file, the status of the file, and other control information.
Table A	Is a dictionary of the field names and coded field values in the file.
Table B	Contains the retrievable data of all records in the file.
Table C	Stores an entry for every field name = value pair that occurs in the file for fields defined as KEY. There are also many entries for every field name = value pair that occurs for fields that have the NUMERIC RANGE attribute.
Table D	Contains the Ordered Index, which includes an entry for every field name = value pair that occurs in the file for fields defined as ORDERED. Table D also contains lists of Table B record numbers for all KEY or NUMERIC RANGE or ORDERED field name = value pairs that occur more than once in the file. Procedures and the procedure dictionary are stored in Table D as well.
Table E	Stores Large Object data that includes a Large Object data descriptor for the length, reserve, and a pointer to the Large Object data in Table E. Large object data is not automatically indexed.Your application must associate the Large Object field with another field in the record that can be indexed.

File types

Records are stored in Model 204 files in one of four orders: entry order, unordered, sorted, or hash key. Each file order is discussed separately in the following section. For a more detailed description of each file order, refer to the Rocket Model 204 File Manager's Guide.

Entry order files

The most frequently used method of storing records is in the order in which they are entered (hence "entry order" files). Records are retrieved in the order in which they were entered.

When a record in an entry order file is deleted, the record number is not reused. The space occupied by the deleted record, however, does become available for the expansion of existing records. New records are appended to the end of the file.

Unordered files

When a file is unordered, the space freed by deleted records can be reused when new records are added.

Sorted files

Records are stored in order of the value of a particular field called the sort key. The sort key is designated by the file manager when the file is initialized. For example, the demonstration database file CLIENTS is a sorted file in which FULLNAME is the designated sort key.

The sort field can be specified as either mandatory or optional. When a sort field is mandatory, all records must have it. If it is optional, records without sort fields are accepted. (For example, STORE RECORD statement.) The sort is based on the standard EBCDIC character set and collating sequence: punctuation, then letters, then numbers. Sorted files are useful when a large percentage of reports are produced in the same sort sequence.

Hash key files

Hashing is a technique for key-to-storage address translation that eliminates the need for multiple levels of indexing. This file order allows Model 204 to retrieve quickly on a single unique key, without the overhead of index searches. The records themselves are stored in random order. The hash key can be specified as either mandatory or optional.

File groups

A file group is a collection of Model 204 files that Model 204 treats as a single file. The file group facility is useful in applications where certain data is maintained in separate files but it is necessary to process all of the data together. For example, fifty individual state files can be processed as members of regional file groups (such as SOUTH) and as a file group for the entire country, USA.

Remote files and scattered groups

Parallel Query Option/204 users can access data stored in files in remote locations, in single remote file context, or in scattered group context. A scattered group is a file group which is locally defined, and which includes at least one remote file as a member.

Throughout this manual, all references to remote files, scattered groups, and remote file or scattered group context, are addressed to Parallel Query Option/204 users.

Request compilation and evaluation

Model 204 processes a User Language request in two phases: compilation and evaluation. During compilation, the text of the request is checked for proper syntax, and the statements are translated into an internal format that Model 204 can execute. During evaluation, certain types of user responses are entered and the request is actually executed.

Compilation errors

Errors can occur during compilation or evaluation. If errors occur during compilation, Model 204 reports them by displaying appropriate error messages. In most cases, if you have the appropriate display privileges, Model 204 displays, on the next line, the line of the User Language request in which a compilation error occurred. Compilation errors must be corrected before a request can be run.

Compilation error handling

Sometimes an initial compilation error causes a cascade of subsequent error messages that do not help you analyze the problem. Furthermore, the error messages do not point out just where the problem occurred. The COMPERR parameter lets you determine how many error message--one or many--to display and to highlight the code that resulted in the error.

You can set COMPERR to X'01', X'02', X'04', or a sum of a combination of your choice.

• COMPERR=X'01' points to (>> <<) the first error and displays only that error.

** 1***** M204.2775: INVALID EXPRESSION IN INITIAL CLAUSE ************ ***** %A IS STRING LEN 10 DP 0 INITIAL(>>C'A1B2'<<) STATIC ******* ***** (FILE = ULP42, PROCEDURE = V4R2.TEST.42FINIT.ERRORA, LINE=10 ***** M204.1042: COMPILATION ERRORS

• COMPERR=X'02' underlines (__) the error and displays only that error.

** 1***** M204.2775: INVALID EXPRESSION IN INITIAL CLAUSE ************ ***** %A IS STRING LEN 10 DP 0 INITIAL(C'A1B2') STATIC *********** ***** (FILE = ULP42, PROCEDURE = V4R2.TEST.42FINIT.ERRORA, LINE=10 ***** M204.1042: COMPILATION ERRORS

• COMPERR=X'03' both underlines and points to (>>__<<) the error and displays only that error.
• COMPERR=X'04' displays all messages.
• COMPERR=X'07' both underlines and points to (>>__<<) the error, as well as displays all messages.

Counting errors

Certain types of Model 204 compilation errors cause a counter to be incremented. When a counting error is encountered, a message is displayed and evaluation continues. However, if the counter reaches the value set by the ERMX, processing is stopped and the user's session is also stopped. For more information on counting errors, refer to the Model 204 core messages.

Evaluation errors

If errors occur during evaluation, the way they are handled by Model 204 depends upon the type of error that has occurred. The various methods of error handling are described as follows:

Automatic evaluation continuation

In some cases such as an arithmetic overflow or division by zero, Model 204 prints out an informational message, provides a default value or course of action, and continues to evaluate the request.

For User Language functions, Model 204 provides a default value or course of action (such as returning a null string or an error indicator) and continues to evaluate the request. See Standard SOUL $functions, for detailed individual descriptions, including information on the default value returned or action taken.

Request control

The request can determine how to handle certain error conditions through the use of the following facilities:

• Error message retrieval: The error message retrieval facility allows you to retrieve the error message when an I/O error occurs such as a file open failure on an external file. This facility allows the request to determine the course of action to be taken. For more information refer to:
  • Error handling on file opening
  • Images error handling
  • Program communications facilities
• ON units: The ON unit facility allows you to specify a course of action to be taken when an event occurs that is beyond your ability to control. Refer to ON units for more information on this facility.
• Error procedure: Using the Subsystem Management facility, you can define the error procedure to invoke when a condition occurs that cannot be handled by the executing procedure. For a complete discussion of the Subsystem Management facility and error procedure definition, see Application Subsystem Development.

Request cancellation

In some cases, errors that normally would be determined during compilation cannot be determined until evaluation. For example, when a variable is used, the value of the variable is not determined until evaluation. The value might result in an error (such as an attempt to print a field with the INVISIBLE attribute). Errors of this type cancel the request, and back out the transaction (if necessary).

User restart

If a serious error occurs such as the filling of internal tables, Model 204 cannot recover while the user is running. Therefore, Model 204 stops the request, closes all files, logs the user out, and displays a message. The user can then log back in and start over. If the files have been physically damaged, the file manager must correct the damage before the user can proceed. For more information on user restarts, refer to the Rocket Model 204 Terminal User's Guide.

Security

Model 204 provides these security features to protect users:

• Field-level
• File
• Group
• Login
• Procedure
• Record-level
• Terminal

All Model 204 security features are optional. In addition, Model 204 interfaces also are available for other security products.

The discussions of User Language operations in this manual assume that the user has the required privileges and access rights according to the security features in use.

Login security

Logging into Model 204 invokes login security, the most basic Model 204 security mechanism. The login security scheme requires users to identify themselves at the start of a Model 204 session. Model 204 uses this identification to determine the type of operations that a particular user is authorized to perform during the session.

A user login is optional at some installations. When a login is required, user login operations include the issuing of a login command (with a valid user ID) and, optionally, the entering of a password.

LOGIN or LOGON

If a user login is required, every user must issue the following LOGIN or LOGON command (described further in the discussion of the LOGIN command in the Rocket Model 204 Parameter and Command Reference Manual):

LOGIN [userid [account]]

or:

LOGON [userid [account]]

where:

• userid is a 1- to 10-character name that identifies the user to Model 204.
• account is a 1- to 10-character name that identifies the account under which you are logging into Model 204.

Password protection

After LOGIN or LOGON is issued, Model 204 may prompt you for a password by displaying:

*** M204.0347: PASSWORD

Model 204 expects you to reply with a password of as many as eight characters. If you enter a valid password (and your account is also valid), Model 204 grants you the privileges associated with your user ID.

• With application subsystems, an automatic login facility is available. Refer to the Rocket Model 204 System Manager's Guide for more information.
• If you have the appropriate privileges, you can change the password at login time. The procedure for changing a password is discussed in the description of the LOGIN command in Rocket Model 204 Parameter and Command Reference Manual.

For more information

• For a detailed description of other Model 204 security features, refer to the Rocket Model 204 System Manager's Guide.
• Refer to the Rocket Model 204 Security Interfaces Manual for more information about the optional security interfaces available in Model 204.