Tokenized Encryption: Documentation Error Handling


These products generate software and hardware error messages in varying formats and naming conventions. The cryptographic interface established a standard error message format and re-packaged message text, return codes, error codes, etc. into this new format. The User’s Guide explains each product message format, provides links to Messages and Codes manuals, and gives error identification, determination and resolution guidance.

The error handling logic had several objectives, described in the CPCICI User’s Guide, along with instructions on how to implement them:

  1. Use the top line of all online screens for messages, the design standard for this client. All online device screens could display 80 characters per line, although some could display more. So a message was limited to 80 characters. Color and blinking could also be used; blue or green for informational messages, yellow for warning messages and red for errors.
  2. Recover from the error wherever possible. For example, if a file went offline, automated operations software was invoked to bring it back online and notify operations to look into the problem. Optionally, checkpoint information was saved so the transaction could be resumed from the point of error, rather than start over.
  3. Intercept errors and determine the best way to handle them. Many products’ default error action is task termination, even though the error may be recoverable. The error routines provided options when invoking cryptographic functions, including retries and re-entry.
  4. Gather as much diagnostic information as possible, and present it to the operator in everyday terminology. For example, when a record isn’t found, the operator is told what field is incorrect, prompted to verify it and then allowed to re-enter it, rather than task termination that forced a user to start over.
  5. Suggest actions. For example, call a supervisor or suggest a transaction to check item availability. Message content was determined by the programmer and department manager or supervisor.
  6. Keep an error log. Optionally, a programmer can specify a message also be logged for error debugging, tracking transaction flow and/or actions taken.

    The error handling copy book–a.k.a. storage definition–was stored in a program library. The CPCICI User’s Guide describes how the COBOL fields should be used in a program, one data item at a time, as regards usage and content:

    The CPCICI User’s Guide describes how to populate storage layouts–including all information in this article. It also explains how to display the messages and includes links to all vendor websites and specific manuals.

    Handling Errors Eases the Pain

    For most programmers, constructing both a consistent and comprehensive error handling methodology and detailed, descriptive error handling documentation isn't exactly the plum in the pudding. And most managers simply view these tasks as additional obstacles to meeting challenging deadlines. Yet once a system, application or process is in production, these components rank among the most important pieces of IT deliverables.

      • Error indicator, the first 1-byte field, signified if an error occurred. Y signified yes, N for no.
      • Error information, the second field, was the 80-character string displayed on the screen. The REDEFINES function was used to subdivide the 80 bytes into 10 different storage layouts for each product listed above. Not only did message formats differ for each product (and user-defined), but the number of fields also varied.
      • Regardless of the error, the first portion consisted of 22 characters: U=xxxx,T=nnnnnnnnnnnn, where xxxx is userid and nnnnnnnnnnnn is token number.
      • The remainder of message layouts varied greatly, determined by product text, codes and indicators. User messages consist of up to 58 text characters, defined as a single field. Product messages usually contained a number of fields. For CICS, error data consisted of 14 bytes for file operation (read, write, delete, etc.), a 20-character error description (record not found, invalid key, etc.) and 4 bytes of RESP text, RESP value, RESP2 text and RESP2 value. In the case of ICSF, 32 bytes contain error description, then a 4-byte error value, a 5-byte error text and a 5-byte error modifier. Similarly differing record layouts were used for other products.

Jim Schesvold is a technical editor for IBM Systems Magazine. Jim can be reached at

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.

comments powered by Disqus



2018 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters