|
|
|
Requests that the next log message be made available to LOGPROC.
&LOGREAD { VARS= prefix* [ RANGE=( start,end ) ]|
VARS={ name | ( name,name, ..., name ) } |
STRING=( name, name, ..., name) } |
ARGS [ RANGE=( start,end ) ] |
MDO=mdoname | SET }
The system-level LOGPROC procedure can intercept and process messages directed to the activity log.
The &LOGREAD statement is reserved for use by the LOGPROC NCL procedure and requests that processing of the LOGPROC procedure be suspended until the next log message is available.
After the &LOGREAD statement, the LOGPROC procedure can analyze the log message and initiate any special processing required.
Optionally, the LOGPROC procedure can delete messages from the log using the &LOGDEL statement. The &LOGREAD statement is designed to tokenize the incoming log messages into variables in a variety of forms to simplify analysis and interpretation of the messages by the LOGPROC logic.
On completion of &LOGREAD the system variable &ZVARCNT is set to the number of variables created or modified by the operation.
The profile of the message received by &LOGREAD is set in a suite of reserved system variables. The message profile (which includes attributes such as color, highlighting, and source information) provides a complete description of all log message attributes, in addition to the message text. The message attributes can also be accessed using the $LOG MDO, which is always available after a successful &LOGREAD. The $LOG MDO is mapped by the $MSG map.
Note: For more information about the &LOGREAD message profile, see the Network Control Language Programming Guide.
Operands:
Specifies that no tokenization of the log message is to be performed, but that the &LOGREAD statement is to return only the message profile for the next log message.
If SET is not specified, operands must be coded on the &LOGREAD statement specifying the tokenization requirements for the message text using other &LOGREAD operands.
Specifies that the message is to be tokenized into the nominated variables before control returns to the procedure. Each word of the log record line is tokenized into the nominated variables from left to right. If insufficient variables are provided, some data will be lost. Excess variables are set to null. The formats of the operands that is coded with VARS= are described below:
Denotes that variables are generated automatically during the tokenization process, and that variable names will be prefix1 … prefix2 and so on. (The RANGE= operand is specified to indicate a starting and ending suffix number). prefix* cannot be used with other variable names.
The name of a variable, excluding the ampersand (&).
As name, but n denotes the length of the data to be placed in the variable.
Denotes a skip operation, where n represents the number of units to be skipped during the tokenization process. On VARS= statements, n denotes 'skip this number of words'. An asterisk (*) by itself is the same as *(1).
Specifies that no tokenization is to be performed. The entire text of the command line is treated as a single string and returned to the procedure in the nominated variables. The formats of the operands associated with STRING are:
User-specified variables, excluding the leading &, into which the string text is put. Text is placed into each variable up to the maximum length of that variable.
User-specified variables, excluding the leading ampersand (&), into which the string text is put. Text is placed into each variable for the length n.
Denotes a skip operation, where n represents the number of units to be skipped during the tokenization process. On STRING statements, n denotes 'skip n characters'. An asterisk (*) by itself is the same as *(1).
Denotes that the line of text retrieved is tokenized and placed word-by-word into automatically generated variables of the form &1 through &n, depending on how many are required to hold the text.
The RANGE= operand is coded to designate start and end values to delimit the number of variables generated.
Specifies the object name to which an MDO is to be assigned if an MDO is present in the log message.
MDOs are user data structures, which is passed to NCL processes with &EVENT or &WRITE statements. They will be propagated to the system log if they are present in an eligible log message.
Examples: &LOGREAD
&LOGREAD ARGS RANGE=(20,80)
The next log message to arrive is tokenized into variables from &20 up to &80 maximum. &ZVARCNT is set to indicate how many variables were created.
&LOGREAD VARS=(*(3),A(2),B(3),C,D,E,F)
The next log message is tokenized into individual words. *(3) indicates that the first 3 words are ignored, 2 characters of the next word are placed in the variable &A, three characters of the next word are placed in the variable &B and the next 4 words are placed into variables &C, &D, &E, and &F respectively.
&LOGREAD VARS=ABC* RANGE=(1,50)
The next log message is tokenized and placed word-by-word into a series of automatically generated variables with the form ABC1, ABC2, ..., ABC50, and so on. Variables are generated, up to the limit specified by the RANGE operand.
&LOGREAD STRING=(A,B(2),*(5),C(3))
Reads the next log message as a single text string. The first 256 bytes are placed in &A, the next 2 characters are placed in &B, the next 5 characters are ignored, and the next 3 characters are placed in &C.
Notes:
Log records always include the time the record was generated (in format HH.MM.SS.TH), with the user ID for the user who generated the record, and the TERMINAL where that user is logged on.
If STRING is not specified, these fields are tokenized as follows:
These three fields are always present.
If no USERID or TERMINAL is associated with a particular message (such as for commands executed during system initialization), either or both of these fields are set to a single minus (-) character. Therefore, the NCL procedure can assume that the fourth variable will contain the first word of the actual text of the log message.
For commands executed from an NCL process's dependent processing environment (via &INTCMD), the terminal field appears as *nclid*, where nclid is the NCL process identifier.
After a successful &LOGREAD, a $LOG MDO will always be available to LOGPROC. $LOG is mapped by $MSG and contains all attributes associated with a message. In addition, if the message was an envelope for a user MDO, the user MDO is referenced directly from $LOG.USERMDO or automatically assigned from the MDO= operand on the &LOGREAD. The mapname for the user MDO is available in $LOG.MAPNAME or the &ZMAPNAME profile variable.
&ZMDORC and &ZMDOFDBK are set.
In the activity log certain characters are used to highlight specific classes of messages. For example, the plus sign (+) prefixes commands, and an equal sign (=) prefixes VTAM PPO messages. These special indicators appear in the physical printed log only, and are not returned in the tokens that result from an &LOGREAD statement.
An example of using LOGPROC to intercept particular messages arises with File Transmission Services (FTS). A LOGPROC procedure is written to monitor when transmissions finish. On detecting the completion of certain transmissions (determined by their request name or data set name), LOGPROC can dynamically generate job control language (JCL) to process a newly-arrived data set and automatically submit it to the internal reader.
An example of a utility to perform this is supplied with the system as UTIL0005.
&LOGREAD can also be used to split the activity log into different categories and write records to data sets where they are available for on-line browsing. An example of a LOGPROC to perform this, and a supplementary procedure to perform on-line log browsing is supplied with the system.
Any attempt to use &LOGREAD in other than the designated LOGPROC procedure results in an error.
Note: For more information about the LOGPROC procedure, see the Reference Guide. See also LOGPROC message profile variables.
| Copyright © 2009 CA. All rights reserved. |
|