Terminal session
Overview
This topic provides an example of using a terminal to perform a database retrieval and a variety of other operations.
This topic introduces the Model 204 remote terminal facilities; it does not describe SOUL nor system control commands in any detail. For more information about these facilities, refer to the SOUL and Commands wiki pages.
The terminal used in this session is a Teletype-compatible device that connects to Model 204 by means of a dialup telephone line and an acoustical coupler. Refer to CICS terminal interface for a discussion of this device.
The prompt character shown in this session is a question mark (?). The particular prompt that appears on a user's terminal can differ, depending on terminal type and the Model 204 system interface used.
Terminal dialog
The entire terminal session is shown in the following sections. The remainder of this topic describes the components of the session in detail.
After the user connects to Model 204 using the Teletype device (as described in Getting online), Model 204 displays the following message to indicate it is ready for the user to initiate a session:
MODEL 204
Logging in
The user logs in to Model 204:
?LOGIN CCA D0101500 *** M204.0347: PASSWORD ?######## *** M204.0353: CCA D0101500 LOGIN 85 JUL 18 15:18 *** M204.0131: CHECKPOINT COMPLETED ON 85.199 15:09:29.75
Opening a file
The user opens the CLIENTS file:
?OPENC CLIENTS *** M204.0620: FILE CLIENTS OPENED
Displaying a procedure
The user displays the procedures in the file:
?DISPLAY LIST CONTRIB POLICY PROC50 SACRAMENTO TRIAL
Viewing parameter settings
The user views settings of parameters:
?VIEW OUTLPP, PGSEP OUTLPP 60 OUTPUT LINES PER PAGE PGSEP 2 LINES BETWEEN PAGES
Resetting parameters
The user resets the values of the parameters:
?RESET OUTLPP=50, PGSEP=3 OUTLPP 50 OUTPUT LINES PER PAGE PGSEP 3 LINES BETWEEN PAGES
Entering an ad hoc request
The user enters an ad hoc request:
?BEGIN ?FD.POL: FIND ALL RECORDS FOR WHICH ? POLICY NO = 100035 ? SEX = M ? STATE = OHIO OR NEW YORK ? END FIND ?FR.POL: FOR EACH RECORD IN GET.POL ? PRINT ALL INFORMATION ? SKIP 1 LINE END FOR ?END
Model 204 displays output from the request.
FULLNAME = ADAMS, CESAR O POLICY NO = 100035 DRIVER ID = 100085 MARITAL STATUS = MARRIED SEX = M STATE = NEW YORK INCIDENT = T2 INCIDENT DATE = 770513 INCIDENT = T1 INCIDENT DATE = 780614 INCIDENT = T2 INCIDENT DATE = 790715 DATE OF BIRTH = 640619
Displaying a stored procedure
The user displays a stored procedure:
?DISPLAY SACRAMENTO BEGIN CATEGORY.A: FIND ALL RECORDS FOR WHICH TOTAL PREMIUM IS GREATER THAN 300 AGENT = GOODRICH OR BATEMAN CITY = SACRAMENTO END FIND COUNTER: COUNT RECORDS IN CATEGORY.A PRINT COUNT IN COUNTER FOR EACH RECORD IN CATEGORY.A PRINT FULLNAME AND AGENT AT 30 END FOR END
Executing a procedure and viewing output
The user executes the procedure and Model 204 displays output:
?INCLUDE SACRAMENTO 5 ADAMS, KEN U GOODRICH ELLIOTT, CHRISTINE Q BATEMAN GOLDSMITH, CLAYTON C BATEMAN GRIFFIN, EUGENE O BATEMAN WRIGHT, FRANK I GOODRICH
Defining a new procedure
The user defines a new procedure:
?PROCEDURE TEST *** M204.1144: DEFINE PROCEDURE ?BEGIN ?POL.100990: FIND ALL RECORDS FOR WHICH ? POLICY NO = 100990 ? END FIND ? FOR EACH RECORD IN POL.100990 ? PRINT SEX AND DATE OF BIRTH END FOR ?END ?END PROCEDURE *** M204.1146: PROCEDURE ENDED
Printing the procedure
The user displays the procedure on the printer:
?USE OUTPRINT ?DISPLAY TEST *** M204.1327: NUMBER OF U DD LINES OUTPUT=8 *** M204.0131: CHECKPOINT COMPLETED ON 85.199 15:35:29.75
Deleting a procedure
The user deletes a procedure:
? DELETE SACRAMENTO
Logging out
The user logs out of Model 204:
? LOGOUT *** M204.0608: FILE CLOSED: CLIENTS *** M204.0353: CCA D0101500 LOGOUT 85 JUL 18 15:36
Disconnecting from Model 204
The user disconnects:
? DISCONNECT
Getting online
To connect to Model 204 using the Teletype device, the user must do the following:
- Turn the power on.
- Set the terminal mode switch to LINE and the duplex switch to HALF.
- Dial the telephone number provided by the system manager and wait for the carrier tone.
- Place the receiver in the acoustical coupler and wait for the terminal to type an acknowledgment. The particular acknowledgment depends on the system interface and type of connection. Model 204 indicates that it is ready by displaying the following:
MODEL 204
Logging in
LOGIN process
Having established a connection to Model 204, the user must log in if the LOGIN process is required at an installation. The following command is used to log in:
{LOGIN | LOGON} userid [account]
where:
| userid | Is a 1- to 10-character name assigned by the system manager to identify the user. |
| account | Is an optional 1- to 10-character name assigned by the system manager to identify the user's group or department. |
The user ID and password determine the types of operations that the user is allowed to perform.
The following dialog shows the procedure for logging in.
Sample LOGIN dialog
The user logs in under the user ID CCA and account D0101500:
?LOGIN CCA D0101500
Model 204 prompts for a valid password:
*** M204.0347: PASSWORD
Model 204 masks the password to protect it from unauthorized access. The user enters the password (1-8 characters). The # symbols represent the masked password:
?########
The login was successful, so Model 204 displays the user ID, account, date, and time:
*** M204.0353: CCA D0101500 LOGIN 85 JUL 18 15:18 *** M204.0131: CHECKPOINT COMPLETED ON 85.19915:09:29.75
Model 204 prompts for a command:
?
If the LOGIN had failed, Model 204 would have displayed the message:
*** M204.0349: LOGIN FAILED
Note: Once the user has successfully logged in to Model 204, the user can issue any commands or enter SOUL requests. Certain restricted commands can be issued only if the user has the proper privileges, as discussed in the Overview of Model 204 commands.
Opening a file
Before the user can update or retrieve data, a file or group must be opened by means of either the OPEN or OPENC command. The user enters:
{OPEN | OPENC} filename
where:
filename identifies the file or group to be opened.
See the OPEN FILE and OPENC wiki topics for more information about files, groups, and the different characteristics of OPEN and OPENC.
Using OPEN with different file types
Using OPEN with different types of Model 204 files results in different actions:
- If a user attempts to OPEN a public file, Model 204 opens it.
- If a user attempts to OPEN a semipublic file, Model 204 prompts for a file password.
- If the user enters a valid password, the file is opened with all the file privileges that are associated with that password.
- If the user does not know the password and enters either an invalid password or a carriage return, the file is opened, and the user is granted the default privileges for the file.
- If a user attempts to OPEN a private file, Model 204 prompts for a file password and opens the file only if the user enters a valid password.
Opening a public file
The following example illustrates the opening of a public file:
?OPENC CLIENTS
CLIENTS is a public file and is opened without requiring a password. The following message is displayed:
*** M204.0620: FILE CLIENTS OPENED
Opening a semipublic file
The following example illustrates the opening of a semipublic file.
The user attempts to open CENSUS, which is a semipublic file:
?OPENC CENSUS *** M204.0347: PASSWORD ?########
The user presses a carriage return. The file is opened, and the user is granted default privileges that do not allow the user to update the file. The following message is displayed:
*** M204.0620: FILE CENSUS OPENED -- NO UPDATES ALLOWED
Viewing and changing parameter settings
Before a user runs a file retrieval that results in a printed report, the user might want to check the values of the parameters that control the spacing of printed output. Parameters are variables that define terminal characteristics, the length of user input and output lines, file characteristics, table sizes, and other information at particular installations. The basic types of parameters are:
- System
- File
- User
Some parameters can be set or reset only by the system manager or by a file manager. Others can be reset by the user. All the parameters have default values provided by Model 204. The parameters that affect terminal operations are summarized in the List of Model 204 parameters.
Using the VIEW command
The user can display the current values of all the parameters or a subset of parameters by means of the VIEW command, which can be abbreviated to V. The format of the VIEW command is as follows:
VIEW parameter [,parameter] ...
Special sets of parameters also can be displayed. For example:
| This command... | Displays all... |
|---|---|
| VIEW ALL | Parameters |
| VIEW SYSTEM | System parameters |
| VIEW USER | User parameters |
| VIEW FILE | File parameters |
The RESET command, which can be abbreviated to R, allows the user to change the settings of user parameters. VIEW and RESET are illustrated in the following terminal session.
Example of the VIEW command
The user requests the selected parameters to be displayed:
?VIEW OUTLPP, PGSEP OUTLPP 60 OUTPUT LINES PER PAGE PGSEP 2 LINES BETWEEN PAGES
The user specifies new values for OUTLPP and PGSEP:
?RESET OUTLPP=50, PGSEP=3 OUTLPP 50 OUTPUT LINES PER PAGE PGSEP 3 LINES BETWEEN PAGES
Running Model 204 requests and procedures
You can run a Model 204 SOUL request in one of the following ways:
- Enter SOUL statements at the terminal and invoke an immediate response.
- Enter SOUL statements and system control commands in the form of a procedure, save the procedure on disk, and then invoke the procedure at a later time.
Procedures
Statements and commands are entered in the form of a procedure when the user enters:
PROCEDURE name . . . statements and/or commands . . . END PROCEDURE
where:
name identifies the procedure being defined.
For example:
PROCEDURE CITY
This procedure can be executed at a later time by entering:
INCLUDE CITY
If the procedure is a temporary procedure, the user specifies a negative number (that is, -n) instead of a name.
A procedure need not always combine executable statements and commands. A procedure can contain only a portion of a SOUL request. It also can contain nonexecutable text such as program documentation.
Example
In the following example, the user enters and runs a request, checks the output, and decides to execute a previously stored procedure. The user then creates and saves a procedure for subsequent editing and execution.
The user enters retrieval statements:
?BEGIN ?FD.POL: FIND ALL RECORDS FOR WHICH ? POLICY NO = 100035 ? SEX = M ? STATE = OHIO OR NEW YORK ? END FIND ?FR.POL: FOR EACH RECORD IN FD.POL ? PRINT ALL INFORMATION ? SKIP 1 LINE END FOR ?END
Model 204 displays retrieved data:
FULLNAME = ADAMS, CESAR O POLICY NO = 100035 DRIVER ID = 100085 MARITAL STATUS = MARRIED SEX = M STATE = NEW YORK INCIDENT = T2 INCIDENT DATE = 770513 INCIDENT = T1 INCIDENT DATE = 780614 INCIDENT = T2 INCIDENT DATE = 790715 DATE OF BIRTH = 640619
The user executes a previously entered procedure:
?INCLUDE SACRAMENTO 5 ADAMS, KEN U GOODRICH ELLIOTT, CHRISTINE Q BATEMAN GOLDSMITH, CLAYTON C BATEMAN GRIFFIN, EUGENE O BATEMAN WRIGHT, FRANK I GOODRICH
The user defines a procedure named TEST. The system prompts for statements and the user enters them:
?PROCEDURE TEST *** M204.1144: DEFINE PROCEDURE ?BEGIN ?POL.100990: FIND ALL RECORDS FOR WHICH ? POLICY NO = 100990 ? END FIND ?POL.FR: FOR EACH RECORD IN POL.100990 ? PRINT SEX AND DATE OF BIRTH END FOR ?END
The user signals the end of procedure:
?END PROCEDURE
The system responds and then prompts for another command:
*** M204.1146: PROCEDURE ENDED ?
Displaying a procedure
Using the DISPLAY and USE commands
A procedure can be displayed by means of the DISPLAY command, which can be abbreviated to D. The user requests that a procedure be displayed on the terminal by entering either:
DISPLAY procname
or:
DISPLAY -n
All permanent procedures are displayed if the user enters:
DISPLAY ALL
To display a list of the procedures currently available in the file, the user enters:
DISPLAY LIST
A procedure also can be displayed on a device such as a line printer if the user includes an appropriate USE command. For example, if the following command is specified, the device associated with ddname in the system initialization deck is used instead of the user's normal output device (usually the terminal):
USE ddname
The Rocket Model 204 documentation wiki command pages provide a detailed description of the DISPLAY and USE commands:
DISPLAY PROCEDURE command: Procedure names
DISPLAY PROCEDURE command: Procedure text
The user displays the available procedures:
?DISPLAY LIST CONTRIB POLICY PROC50 SACRAMENTO TRIAL
The user displays the procedure named SACRAMENTO:
?DISPLAY SACRAMENTO
BEGIN CATEGORY.A: FIND ALL RECORDS FOR WHICH TOTAL PREMIUM IS GREATER THAN 300 AGENT = GOODRICH OR BATEMAN CITY = SACRAMENTO END FIND COUNTER: COUNT RECORDS IN CATEGORY.A PRINT COUNT IN COUNTER FOR EACH RECORD IN CATEGORY.A PRINT FULLNAME AND AGENT AT 30 END FOR END
Sample DISPLAY dialog
Several of the DISPLAY options are illustrated in the following dialog.
The user displays the procedure named TEST:
?DISPLAY TEST BEGIN POL.100990: FIND ALL RECORDS FOR WHICH POLICY NO = 100990 END FIND FR.POL: FOR EACH RECORD IN POL.100990 PRINT SEX AND DATE OF BIRTH END FOR END
The user specifies a printer data set:
?USE OUTPRINT
The user writes the procedure named TEST to the printer:
?DISPLAY TEST *** M204.1327: NUMBER OF U DD LINES OUTPUT = 8
Deleting a procedure
Using the DELETE command
A saved procedure can be deleted when it is no longer needed by using the DELETE command. This conserves space on the disk. The user identifies the procedure by name:
DELETE procname
Temporary procedures, specified by number (n) in the form -n, need not be explicitly deleted. They are deleted automatically when the user logs out. In the terminal session, the user does not need procedure SACRAMENTO again and enters:
DELETE SACRAMENTO
Recovering from an error
When an error condition occurs, Model 204 displays a message, determines the severity of the error, and, depending on the type of error that occurred, can stop the run, restart the user, or save the contents of memory for subsequent debugging.
The basic types of error conditions, prompting messages, and informational messages in Model 204 are summarized in this section. For a detailed explanation about Model 204 messages, refer to the Rocket Model 204 messages documentation.
Prompting and informational messages
Model 204 displays a variety of prompting and informational messages during initialization, evaluation of SOUL requests, and execution of procedures. For example:
DO YOU REALLY WANT TO action? PASSWORD? FILE OPENED FILE CLOSED GROUP OPENED GROUP CLOSED FILE MAY BE LOGICALLY INCONSISTENT
Counting errors
Counting errors are the least severe types of errors. If a counting error occurs while Model 204 is compiling a SOUL request, the request cannot be executed. If the error occurs while Model 204 is evaluating a request, evaluation continues after the error message is displayed. If the error occurs while Model 204 is attempting to execute a system control command, execution of the command is halted.
These errors are called counting errors, because they cause a counter to be incremented. Counting error messages have the form:
*** n M204.1030: INVALID MODEL 204 COMMAND
where n indicates the current value of the counter. The system parameter ERMX specifies the maximum value that the counter can have. If this maximum is reached, the counter is reset and the user is restarted as described in Soft restart. The counter also is reset whenever a new BEGIN command is encountered.
Counting errors are not severe enough to cause a user restart. If the error occurs in a SOUL request, the user can correct the error using an editor and can then compile the request again. If the error occurs in a system control command, the user can simply reenter the command. If the error occurs in a procedure, the user must wait for Model 204 to process the entire procedure before correcting the error.
Severe errors
Severe errors occur when certain internal tables are filled up or when unreadable data structures are encountered. Model 204 cannot recover from these errors while the user is running it. In response to errors of this kind, Model 204 does the following:
- Immediately stops the current request
- Logs the user out
- Closes all open files
- Displays the message:
*** M204.1024: USER RESTARTED
The Model 204 connection is maintained and the user can log in again. Sometimes the user can resume the same operation that was being performed when the error occurred. However, if a file was being updated at that time, the physically inconsistent indicator is set (file status parameter FISTAT = X'02') and Model 204 displays the message:
*** M204.1221: FILE IS PHYSICALLY INCONSISTENT
The file structure might be damaged and the file manager must correct the damage before the user can proceed.
Unless a file is marked physically inconsistent as the result of an error condition, a user restart affects only the user who encountered the error.
Soft restart
Certain errors result in a user restart condition but do not physically damage the file. Errors in this category usually occur when the terminal line is dropped or when another terminal I/O problem occurs. Model 204 stops the request, logs the user out, and displays the message:
*** M204.1024: USER RESTARTED SOFTLY
The physically inconsistent indicator is not set in this case. However, if the user was executing an updating request, the logically inconsistent indicator (FISTAT = X'40') can be set. If this happens, the following message is displayed when the file is opened again:
*** M204.0623: filename MAY BE LOGICALLY INCONSISTENT
The user can proceed to use the file, but the file manager should be notified so that the consistency of the data can be verified and the FISTAT parameter can be reset.
Displaying messages
When a prompting, informational, or error message is displayed by Model 204, a prefix associated with the message specifies the type of message (that is, Model 204 or user) and the number of the message. The system manager can use this prefix information when changing the processing that is performed for particular error conditions.
The MSGCTL parameter can be used to suppress the display of the prefix or to suppress the display of error or informational messages. (Prompting messages cannot be suppressed.) MSGCTL can be set by the system manager for an installation during initialization.
Closing a file
Using the CLOSE command
Having completed all file operations, the user can close the file using the CLOSE command:
CLOSE CENSUS
Files are closed automatically when the user logs out of Model 204 or if a system failure occurs.
Logging out and disconnecting
Using the LOGOUT command
When the user finishes submitting SOUL requests and issuing system control commands, the LOGOUT or LOGOFF command is used to log out of Model 204. At some installations, the user also must hang up the phone in addition to issuing the DISCONNECT command, as in the following example.
The user logs out of Model 204:
?LOGOUT
Model 204 closes any open files:
*** M204.0608: FILE CLOSED:CENSUS
Model 204 displays the user ID, account, date, and time:
*** M204.0352: CCA D0101500 LOGOUT 85 JUL 18 15:28
The user disconnects and can now hang up the telephone:
?DISCONNECT