User Logging Programmer's Guide 900 Series HP 3000 Computer Systems ABCDE HP Part No. 32650-90027 Printed in U.S.A.
The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability or tness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material.
Printing History The following table lists the printings of this document, together with the respective release dates for each edition. The software version indicates the version of the software product at the time this document was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions. Edition Date Software Version First Edition Update #1 November 1987 July 1988 A.01.00 A.10.
Documentation Map iv
Preface The User Logging Programmer's Guide describes the MPE/iX User Logging Facility. It explains the di erences between user logging in MPE/iX and MPE VE Operating Systems. Serial Logging, disc logging, and application design are discussed.
Conventions UPPERCASE In a syntax statement, commands and keywords are shown in uppercase characters. The characters must be entered in the order shown; however, you can enter the characters in either uppercase or lowercase. For example: COMMAND can be entered as any of the following: command Command COMMAND It cannot, however, be entered as: comm italics comamnd In a syntax statement or an example, a word in italics represents a parameter or argument that you must replace with the actual value.
Conventions (continued) [ ... ] In a syntax statement, horizontal ellipses enclosed in brackets indicate that you can repeatedly select the element(s) that appear within the immediately preceding pair of brackets or braces. In the example below, you can select parameter zero or more times. Each instance of parameter must be preceded by a comma: [,parameter][...
Contents 1. Introduction User Logging Applications . . . . . . . . . . . . . . . . . . . . . . . 1-1 2. User Logging Intrinsics 3. User Logging Commands 4. The User Logging Process Which Media to Use . . . . . . . . . . . . Creating the LOGID . . . . . . . . . . . . Identifying LOGIDs on the System . . . . . Changing Attributes Associated with LOGIDs Building a DISC Log le . . . . . . . . . . . Controlling the Logging Process . . . . . . . Logging to DISC . . . . . . . . . . . . . Logging to TAPE . . . .
Tables B-1. Code De nition . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2. Data Fields of Log Records . . . . . . . . . . . . . . . . . . . . . . C-1. User Logging Error Codes . . . . . . . . . . . . . . . . . . . . . .
1 Introduction The MPE/iX User Logging facility provides a method for recording events (for example, to record additions and modi cations to user databases and les). MPE/iX commands and intrinsics are used to setup log les and record to them. Power failure recovery, bu ering, and log le over ow handling can be done for the user automatically. Multiple user processes may share the same log le and share the system process that manages it.
2 User Logging Intrinsics User Logging is performed programmatically by using the intrinsics listed below. The user that starts an application which calls the User Logging intrinsics, must have User Logging (LG) or System Supervisor (OP) capabilities. Refer to the Intrinsics Reference Manual (32650-90028) for the syntax of the following intrinsics: Note BEGINLOG CLOSELOG ENDLOG FLUSHLOG There are no major di erences between Native Mode and Compatibility Mode for User Logging.
LOGINFO LOGSTATUS OPENLOG WRITELOG 2-2 LOGINFO provides information about an open log le and the previous log le (if one exists) in the log le set, or it may be used to obtain information about the whole log le set (for example, the total number of records written). LOGSTATUS provides information about a current, open log le (for example, to determine the amount of space available in a DISC log le).
3 User Logging Commands User Logging can be performed at the system level by using the commands listed below. Refer to the MPE/iX Commands Reference Manual (32650-90003) for the syntax and a more detailed description of the following commands: :ALTLOG :ALTLOG alters the attributes of an existing User Logging identi er. :CHANGELOG :CHANGELOG changes the log le without stopping or interrupting the logging process.
4 The User Logging Process There are two levels of User Logging; the user's level and the system level. At the user's level there are application and recovery programs that access the log le. At the system level, there must be a User Logging process running. The User Logging system process allows up to 256 users to access a single log le at the same time (con gurable at system startup); it handles bu ering and power failure recovery, and provides data about the status of the log le.
Identifying LOGIDs on the System To nd the logid s currently known to the system and the attributes of each, use the :LISTLOG command: :LISTLOG LOGID CREATOR CHANGE AUTO BON KATHY TEST1 MARK.MPEM YES KATHY.MPEM YES KATHY.MPEM NO NO YES NO CURRENT LOG FILE BON003.DOVI.MPEM KAT001.SNIDER.MPEM LOGF.TEST.MPEM A password will be displayed to the logid 's creator only if the creator has speci ed the ;PASS option: :LISTLOG logid;PASS LOGID CREATOR CHANGE AUTO TEST1/SECRET KATHY.
Controlling the Logging Process When logid has been created and the log le built, the Operator will control the logging process using the :LOG command. The :LOG command allows the operator to start a logging process to a new log le, stop a logging process (for example, to change attributes using :ALTLOG, or to shut the system down), or restart a logging process to a log le which has already been accessed.
Note Using :CHANGELOG is recommended over stopping the process, switching log les (by renaming les or using :ALTLOG to point to a new log le), and starting the process. Using :CHANGELOG is easier and it creates these links for use in recovery. It is not required that all log les in a set be on the same media. The rst le could be on disc, the second on tape, the third on disc, etc. This can be controlled with the ;DEV= option of the :CHANGELOG command.
5 User Logging in an Application When the logging process is running, an application can begin writing log records, to the log le, through the use of intrinsics. Using the OPENLOG Intrinsic The OPENLOG intrinsic provides access to the User Logging facility.
Using the WRITELOG Intrinsic After the log le is opened, the data can be written to the log le with the WRITELOG intrinsic. Data will be passed in the WRITELOG intrinsic call and User Logging will add 9 words of information to the beginning of each record. The 9 words of information describe which process recorded the data, when it was recorded, which User Logging intrinsic was used to record it, and a checksum for validity checking.
Using the CLOSELOG Intrinsic When the application has completed accessing the log le, the CLOSELOG intrinsic is called. The CLOSELOG intrinsic will post a record to indicate all transactions for the process have been completed. OPENLOG and CLOSELOG may be called multiple times by the same user. Using the MODE Parameter Each User Logging intrinsic includes a mode parameter used to indicate whether the I/O is to be performed with WAIT or NOWAIT.
6 Recovery Each application which accesses User Logging should have a recovery program written by the user. The recovery program should read the formatted data in the log le and apply it to a backup copy of the data structures belonging to the application. The recovery program can then be run in case of a system failure or program abort to recover the transactions that had fully completed before the problem occurred.
Backup copies of the application data structures will be needed for the recovery process. The recovery program should look for BEGINLOG and ENDLOG records. When an ENDLOG record is found, the transaction has been completed, and all actions represented by the WRITELOG records within that transaction should be applied to the backup data structures. If a BEGINLOG is found without a matching ENDLOG, the transaction was not complete, its actions should not be reapplied.
Power Failure User logging automatically recovers from power failures occurring on the I/O device where the log le resides. If User Logging detects that a power failure has occurred, it will automatically read the log le until the last good record is read. It will then rewrite the data, from its bu er, starting at that block. The Operator may be prompted to reset the tape drive and place it back online.
A Suggested User Logging Procedure The suggested User Logging procedure includes the following: 1. Use the :GETLOG command to create a logid for the application. If data security is required, use the ;PASS option of the :GETLOG command. Specify the con gured device class name (DISC or TAPE). If the logid speci ed in the :GETLOG command is associated with a disc le, build the le with the ;CODE=LOG option of the :BUILD command and enough disc space to contain one day's output. 2.
B Record Formats Record formats are required for direct access to the logging les by the user. The following logging record formats indicate where information resides during the logging process.
0 2 3 4 6 7 11 127 ---------------------------------------------------------------------------| | | | | | | | | rec# | cksum | code | time | date | logid | | |------|-------|------|------|------|-------|------------------------------| Header Record (Start/Restart) 0 2 3 4 6 7 11 127 ---------------------------------------------------------------------------| | | | | | | | | rec# | cksum | code | time | date | logid | | |------|-------|------|------|------|-------|------------------------------| Trailer R
0 2 3 4 6 7 11 12 14 --------------------------------------------------------------------| | | | | | | seq | | | | rec# | cksum | code | time | date | logid | num | c-time | c-date | |------|-------|------|------|------|-------|-----|--------|--------| 15 33 34 52 53 71 72 127 ---------------------------------------------------------------------------| | | | | | | | | f-file-name | f-type | p-file-name | p-type | c-file-name | c-type | | |-------------|--------|-------------|--------|-------------|--------|
Table B-2.
C User Logging Error Codes Table C-1 lists the User Logging error codes and their meanings. These error codes are returned in the logstatus parameter of each of the User Logging intrinsics. Table C-1. User Logging Error Codes Code Meaning Corrective Action 0 No error for this intrinsic call. None. 1 User requested NOWAIT mode and the logging process is busy. Retry the intrinsic call. 2 Check all parameters to be sure they are Parameter out of bounds in logging intrinsic.
Table C-1. User Logging Error Codes (Cont.) Code Meaning Corrective Action The creator of the logid can obtain the password by using the ;PASS option of the :LISTLOG command. 8 Incorrect password was passed to a User Logging intrinsic. 9 An error occurred while writing to the log Obtain the File System error from the le. The File System error message will be $STDLIST and take the appropriate action. printed on $STDLIST. 12 The system is out of disc space, the logging process cannot proceed.
Index A C Accessing complete, log le, 5-3 Active identi ers, list LISTLOG, 3-1 Alter attribute of UL identi er ALTLOG, 3-1, 4-2, 4-3 ALTLOG Alter attribute of UL identi er, 4-2, 4-3 ALTLOG Alter attribute of UL identi er, 3-1 ALTLOG Command, 3-1 Application Multiple le, 1-1 Program, 4-1 Application, design, A-1 Application, link OPENLOG, 2-2, 5-1 Application, using intrinsics, 5-1 Application, writing log records, 5-1 ASCII code, logid, 5-1 Attribute, alter logging identi er ALTLOG, 4-2 Attributes, le BUI
Create logid, 4-1 Current log le information LOGSTATUS, 2-2, 5-3 D De nition, code Record, B-3 DISC, 4-1, 4-2, 4-3 Logging to, 4-3 Disc le speci cation, 4-3 Display space available SHOWLOGSTATUS, 4-4 Display status information SHOWLOGSTATUS, 4-4 E ENDLOG Intrinsic, 2-1, 5-2 Mark end, 5-2 Nested pairs, 5-2 Record, 6-1 Write special record, 5-2 End transaction marker Record, B-2 Error code Meanings, C-1 Error codes Intrinsic, C-1 F Failure, power, 6-3 Field, LEN, 6-2 Fields, data Records, B-3 FLUSHLOG Intr
Logging identi er, attribute GETLOG, 3-1, 4-2 Logging identi er, establish GETLOG, 3-1, 4-1, 4-3 Logging identi er, remove RELLOG, 3-1 Logging process Logid, 4-1 Logging record format, B-1 Logging speed, 4-1 Logid identify, 4-2 Logging process, 4-1 Logid, ASCII code, 5-1 Logid, create, 4-1 LOGINFO Intrinsic, 2-1, 2-2, 5-3 Log le set information, 2-2, 5-3 Open log le information, 2-2, 5-3 Previous log le information, 2-2, 5-3 LOGSTATUS Current, open log le information, 2-2, 5-3 Intrinsic, 2-1, 2-2, 5-3 M ma
Read formatted data, 6-1 RECOVERY program, 6-2 Recreate action from log record, 5-2 RELLOG Remove logging identi er, 3-1 RELLOG Command, 3-1 Remove link CLOSELOG, 2-1, 5-3 Remove logging identi er RELLOG, 3-1 Restart/start, header Record, B-2 Restart UL process LOG, 3-1, 4-3 S Setup log le, 1-1 SHOWLOGSTATUS Command, 5-3 Display space available, 3-1, 4-4 Display status information, 3-1, 4-4 SHOWLOGSTATUS Command, 3-1 Single transaction, 1-1 Space available, display SHOWLOGSTATUS, 3-1, 4-4 Start/restart, he
