MIKES_CREATE_REC_HANDLER
MCRRH
This procedure provides facilities to create, edit and browse files by defining the record structure in a simple format, then generating SCL to perform the requisite action. There are three modes in which the generated SCL will run, dependent on the combination of input and output files specified. In Create mode (output file alone), data may be input into the defined fields. Browse mode (input file alone) allows files to be browsed with the contents displayed by field. Edit mode (both input and output files specified) provides the facility to edit the contents of files interactively.
Note that (currently) only one record type can be created per file, so a file having several record types would have to be built up using APPEND_RECORDS or the generated SCL edited manually to cater for separate record types.
| @ literal | @RECNAME | = @ mandatory @, |
| @ ref int | @USEDEFNFILE | = @@, |
| @ literal | @SAVEDEFNFILE | = @@, |
| @ ref int | @SOURCELIBRARY | = *SRC, |
| @ ref int | @OMFLIBRARY | = *OMF, |
| @ ref int | @SYNONYM | = *OMF, |
| @ response | @RESPONSE | = RESULT ) |
Parameter details
| Keyword | Meaning | Default |
|---|---|---|
| RECNAME | Governs the name of the procedure to be generated. Any hyphens
in the name will be replaced by underscores = name |
None. The parameter is mandatory |
| USEDEFNFILE | The name of the file containing the definition of the file
for which the editor procedure is to be generated = file_name |
The file definition is created interactively |
| SAVEDEFNFILE | The name of the file to which an interactively generated file
definition is to be written = file_name |
If the file definition has been interactively generated, then RECNAME suffixed by "DEFN", otherwise no file is created |
| SOURCELIBRARY | The name of the library to contain the generated source file = library_name |
*SRC |
| OMFLIBRARY | The name of the library to contain the compiled OMF from the
generated source file = library_name |
*OMF |
| SYNONYM | The name of a synonym to be created for the generated OMF = synonym |
No synonym will be created |
| RESPONSE | Response code variable | RESULT |
Interactive layout builder
When a definition file is not supplied as input, the interactive record layout builder is invoked. This allows the record definition to be built up interactively.
A screen is displayed, allowing field name, field type, field length, and field validation to be input. These are not validated, and will be written to the SAVE_DEFN file as long as all of the first three fields contain values. If a mistake is made when defining the record layout, the only way to change the definition is to manually edit the definition file.
Field name may consist of any characters - it is not used for anything other than the display screen in the generated procedure.
Field type may take the following values:
| X | The field is stored exactly as input, in character format |
| H | The field is input and displayed as hex characters. The length specified is the length of the display field, ie. twice the length of the field on the record in bytes |
| D | The field is stored in character (display) format, right justified and with leading zeroes. Note that this is an unsigned field |
| S | The field is stored in binary format, as a signed value. The length includes the sign (hence an S9(8) field would be given a length of 9) |
| U | The field is stored in binary format as an unsigned value |
| P | The field is stored in packed format (COMP-3) |
Field length is the length of the field as shown on the screen, which will be the same as the number of bytes occupied in the record for display fields, but not for binary and packed fields.
Field validation allows additional validation (other than whether the field is numeric or not) to be performed. The rules take the syntax of SCL conditions, including the rules on bracketing of secondary condition. The field itself is symbolised by %F in the validation rules, and will automatically be generated as a numeric or character field depending on the field type. The rule specifies what values are valid.
Examples:
%F NE "ABC"
((%F > 0) AND (%F < 32))
The generated procedure
| @ literal | @INFILE | = @@, |
| @ literal | @OUTFILE | = @@, |
| @ literal | @VALIDATE | = "Y", |
| @ response | @RESPONSE | = RESULT ) |
Parameter details
| Keyword | Meaning | Default |
|---|---|---|
| INFILE | The name of the file to be input to the record handler
procedure, for Browse or Edit modes
= file_name |
No input file is used (Create mode) |
| OUTFILE | The name of the file to be created by the record
handler procedure, for Create and Edit modes
= file_name |
No output file is created (Browse mode) |
| VALIDATE | Specifies whether input fields are to be
validated when the record handler procedure is
run in Create or Edit mode
= Y, YES = N, NO Input fields are not to be validated |
Y Input fields are to be validated |
| RESPONSE | Response code variable | RESULT |
The generated procedure is named rec_name_HANDLER. The appearance of the screen when run depends on the mode being used:
Create mode
The fields to be input are shown on the screen. Data up to the cursor will be transmitted. When VALIDATE = Y is specified (the default), numeric fields are validated, as are any fields with special validation rules, and the screen redisplayed with fields in error flashing and highlighted with asterisks if any fields fail validation. To end input, a screen with "Q" as the first and only character should be sent.
Edit mode
The records in the input file are displayed by field, with an Action field at the top of the screen. This field may be given the following values:
| Q | end edit, skipping the current record and all others in the input file |
| E | end edit, copying all remaining records to the output file |
| S | skip - read next input record without writing anything to the output file |
| C | copy current record unchanged into output file and read next input record |
| I | insert - write a record consisting of the field values on the screen to the output file and redisplay the current input record |
| None | write a record consisting of the field values on the screen to the output file and read the next record on the input file |
Data up to the cursor will be transmitted, all fields following that will retain the values displayed on the screen. When VALIDATE = Y is specified (the default), numeric fields are validated, as are any fields with special validation rules, and the screen redisplayed with fields in error flashing and highlighted with asterisks if any fields fail validation.
When the end of the input file is reached, the edit screen will be displayed with the fields blank, allowing records to be appended to the file.
Browse mode
The records in the input file are displayed by field. The records are displayed serially, from first to last. An Action field is present at the top of the screen. This may take the following values:
| E, Q | end browsing |
| None | Read and display next record |
Errors with displaying field contents
Where a Display field contains a non-numeric character, the character will be replaced with "?" to display it, and the start protect at the end of the field (ie. immediately preceding the name of the next field) will be followed by "!".
Where a Signed or Unsigned field is too long for the display length of the field, the value is truncated on the right (eg. "12345" in a four character field would be shown as "1234") and the start protect at the end of the field will be followed by "!".
The definition file
A definition file will be created if the record definition is built up interactively, and may be used in subsequent SCL generation. The file may be manually edited, for example when a file definition changes or one file definition is similar to another. It may also be created manually, omitting the interactive record building stage.
The definition file consists of a series of records, each one taking the form
field_name field_type field_length field_validation
where field_name is 30 bytes long, field_type is 1 byte long, field_length is up to 3 bytes long, and field_validation (where present) may be up to 34 bytes long. All should be left-justified.