Skip to content
Thoroughbred Software InternationalThoroughbred Software InternationalThoroughbred DocumentationDocs

CHANGE

FUNCTION

This command is used to change existing data records and edit text fields. It cannot be used to add new data records to a file.

SYNTAX

CHANGE link-name [USING key-file-access | index-file-access]
      [MISSING KEY PROCESS IS procedure]
      [BUSY PROCESS IS procedure]
      [END PROCESS IS procedure]
      [ERROR PROCESS IS procedure]
      [SELECT WHEN condition]
      [PROCESSING IS procedure]
      [TEXT "text-id" [WINDOW window-options]]
      [RETRY IS retry-code-string]


      key-file-access:


         KEY [SORT numeric-value] IS record-access |
         record-range


      index-file-access:


         RECORD NUMBER [SORT numeric-value] IS record-access |
         record-range


      record-range:


         RANGE IS [REVERSE]
               ALL |
            FROM record-access TO record-access


      record-access:


         value | NEXT | FIRST | LAST | PREVIOUS


      window-options:


         [LINE IS numeric-value]
         [COLUMN IS numeric-value
         [NUMBER LINES ARE numeric-value]
         [CHARACTERS PER-LINE ARE numeric-value]
         [BORDER TYPE IS border-code-string]
         [HEADING IS string-value]
         [FUNCTION IS function-code-string]


      border-code-string:


         R Reverse Video
         C Character
         N None
         G Graphics
      function-code-string:


         C Display, Change, Exit/Clear
         c Display, Change, Exit
         D Display, Scroll, Exit
         d Display, Exit
         E Erase Window


      retry-code-string


         C Continue with next command
         I Ignore. Invalid for CHANGE command.
         N Do END PROCESS, continue with next command
         S Skip busy record
         Y Use standard busy processing
link-name
the link where the data file is specified.
procedure
the name of a procedure to perform.
condition
an expression or statement, which is tested to determine whether a record will be selected.
string-value
a data-name, variable, constant, or expression that results in a string value.
numeric-value
a data name, variable, constant, or expression that results in an integer.
text-id
a string data name, variable, constant, or expression that specifies a one-character text field ID defined in the format.
retry-code-string
specifies the action to take if the command needs to be retried.

NOTES

  • This command enables you to change the data record and key. You can also edit text field data in a file.

  • The CHANGE command reads and locks the record and makes it accessible to the script by loading the data into the local format area. The data can be changed in a processing procedure before the record is written back to the file.

  • If the record is to be changed, the CHANGE command requires a PROCESSING procedure.

  • If the PROCESSING procedure changes the data, any secondary key changes in the sort file are automatically made as required.

  • If the PROCESSING procedure changes the primary key, the old record is deleted after the new record is written and the text fields and secondary keys are updated. If the primary key is changed to the value of an existing key, the ERROR procedure is performed if specified, and the record is not written.

  • File access options enable you to specify a random individual record, a record relative to the current record position, or a range of records. Other options enable you to specify record selection criteria, a standard record processing procedure, and text field access and record processing.

  • The USING KEY clause is the default.

  • Key-access files must use key-file-access. Indexed files must use index-file-access.

    Indexed files can be accessed by record number or by an existing sort defined in the link. The USING RECORD NUMBER clause is only used to access specific record numbers. Using a defined sort to access a record in an indexed file is the same as using a sort to access a record in a keyed file.

  • The SORT option specifies a sort definition that can be used to access the records in the file by a secondary key.

    When a SORT option is used, a string value must be specified. The MISSING KEY procedure is not valid. File access using a secondary key will access the record closest to the specified key, so a record will always be accessed unless an end of file is reached.

  • The record-access can specify a record by using a string key value for key-file-access, or a numeric record number for index-file-access. If the SORT option is used, you must specify a string key value. NEXT or PREVIOUS options can specify a record in the file relative to the current record position, and the FIRST or LAST options specify the first or last record in the file.

  • The record-range can specify the entire file, for example, ALL, FIRST TO LAST, or LAST TO FIRST. The record-range can also specify a smaller range of records. The REVERSE clause is required to make explicit the direction of the range from high to low key values when the direction of the range is not apparent from the statement. Ranges such as “G-500” TO CUS-CODE, or TEMP-CODE TO CUS-CODE are assumed to be forward unless the REVERSE clause is used.

  • If a record-range is specified, it must make sense, such as NEXT TO LAST, FIRST TO “R-250”, or “A-100” TO “C-200”. A REVERSE range FIRST TO LAST is invalid.

  • A missing key condition occurs if the CHANGE command specifies a primary key that does not exist in the file. If a missing key condition occurs, the MISSING KEY procedure is performed. If the MISSING KEY procedure is not specified, script execution continues with the next command, or with the next record in the range, if a range is specified. MISSING KEY is not applicable when a record-range is specified.

  • A busy record condition occurs if the record being accessed is in use and locked by another user. The CHANGE and DELETE commands lock a record.

    By default, if the CHANGE command specifies a record that is busy, the BUSY procedure is performed and, after five seconds, the command is retried. You can change this behavior by specifying a value for the WAIT-TIME Script-IV variable or by specifying a value for the PRM WAITLOCK statement. For more information on the PRM WAITLOCK statement see the Thoroughbred Basic Customization and Tuning Guide.

    Even if the BUSY procedure is not specified, script execution continues to wait until the record is available. The operator can press the Escape key to force script execution to continue, depending on the escape processing set for the script.

  • The BUSY PROCESS IS procedure is executed before the RETRY option is evaluated.

  • An end-of-file condition occurs when the file-access options attempt to change a record that is beyond the last record in the file or beyond the last record in the range. If the CHANGE command encounters an end of file, the END procedure is performed. If the END procedure is not specified, script execution continues with the next command.

  • If an error occurs, other than the missing key, busy record, or end-of-file condition, during the processing of this command, the ERROR procedure is performed. If ERROR is not specified, script execution continues with the next command or with the next record in the range if a range is specified.

  • The SELECT WHEN option can be used with an individual record or a range of records to select a record for processing based on a logical condition. The logical condition is two or more values, consisting of constants, data names, variables, functions, or expressions, which interact with relational or logical operators to form a true or false result. The record is accessed and the test performed. If the specified condition is true, the record is selected for processing. If no SELECT WHEN is specified, all records accessed are selected.

  • To determine how to form a condition for the SELECT WHEN option, please refer to the information in the Logical Conditionals section of this manual.

  • The TEXT option is used to edit the text in text fields.

  • Reading and processing text fields is separate from reading and processing data records. To add, change, or display text fields with the CHANGE command, the format must have the text field defined and the CHANGE command must specify the correct text field.

  • A window is used for text field processing. If window-options are not specified, the window defaults to the size, location, and type defined in the Dictionary-IV format definition for this text field. The window-options can override these defaults. If you override the CHARACTERS PER-LINE and text is changed, the results will be unpredictable and you could corrupt your text field data. Therefore, you should maintain consistency when multiple scripts are used to update or display text fields.

  • The FUNCTION options enable you to specify function-codes that control the text window processing. These options range from simple display to full-function editing of text.

EXAMPLES

CHANGE 4SCUST USING KEY CUST-CODE
      MISSING KEY PROCESS IS 8-ADD-CUST
      BUSY PROCESS IS 9-LOCKED-CUST
      PROCESSING IS 10-CHG-CUST


CHANGE 4SCUST USING 4SCUST.CUST-CODE
      TEXT "A"
      WINDOW FUNCTION TEXT-FLAG
            HEADING "Additional Customer Information"
            LINE 15
            NUMBER LINES 3
            CHARACTERS 40
            COLUMN 20
            BORDER TYPE "R"

The following pages contain flowcharts for examples of the CHANGE command in single-access mode and in multiple-access mode.

SEE ALSO

ADD, DELETE, KEY-NAME, RETRY, WAIT-TIME, and the TEXT option of the READ command in the Script-IV Language Reference. The ERR system variable and ERR system function in the Thoroughbred Basic Language Reference. The PRM WAITLOCK statement in the Thoroughbred Basic Customization and Tuning Guide.

CHANGE (Single-Access) Example

Screenshot from Script-IV Language Reference

CHANGE (Multiple-Access) Example

Screenshot from Script-IV Language Reference

From the Script-IV Language Reference, version 8.9.1. Open this page in the PDF