AppendJournalData (Stringlist function)

Add lines from journal to Stringlist (Stringlist class)

[Requires SirScan]

This callable method adds lines to the end of a Stringlist from the current, or a specified, Model 204 journal. The AppendJournalData method is only available to customers licensed for SirScan.

The AppendJournalData function has five NameAllowed parameters, and it returns a numeric result.

Syntax

[%rc =] sl:AppendJournalData[( [[StartTime=] string], [[EndTime=] string], - [[Threads=] string], [[Options=] string], - [[Journal=] journal])]

Syntax terms

%rc	An optional numeric variable to contain the returned indicator of the success of the function. It will be one of the following return values: 0 No problems. 1 MAXREC exceeded (sl might contain new items). 2 MAXIO exceeded (sl might contain new items). All other errors result in request cancellation. For definitions of MAXREC and MAXIO, see "Options parameter", below.
sl	A Stringlist object.
StartTime	The first positional parameter, optionally named StartTime, is a string containing the time of the first journal entry to be processed. The time in the string should be in YYDDDHHMISSXX format (YY = year, DDD = Julian day number, HH = hour, MI = minutes, SS = seconds, XX = hundredths of seconds). This start time is inclusive, so any audit trail entry matching the specified start time is considered to be in the range. Specifying this parameter is optional; if it is not specified, the start time is considered to be the time that the Model 204 region was brought up. All of the examples below employ the StartTime parameter; one of them demonstrates using a time relative to the current time.
EndTime	The second positional parameter, optionally named EndTime, is a string containing the end time of the first journal entry to be processed. The time in the string should be in YYDDDHHMISSXX format (YY = year, DDD = Julian day number, HH = hour, MI = minutes, SS = seconds, XX = hundredths of seconds). This end time is exclusive, so any audit trail entry matching the specified end time is considered to be out of the range and is not formatted. Specifying this parameter is optional; if it is not specified, the end time is considered to be the current time.
Threads	The third positional parameter, optionally named Threads, is a string that contains selection criteria for users for which audit trail data is to be formatted. The selection criteria can be a set of blank or comma delimited "phrases", each made up of one or more "clauses" separated by the & symbol. These clauses and phrases are described below in "Threads parameter".
Options	The fourth positional parameter, optionally named Options, is an optional, case-sensitive string that contains a list of blank-delimited keywords which are described below in "Options parameter". Your specification must include one or more audit trail types (ST, AA, AD, etc.).
Journal	The fifth positional parameter, optionally named Journal, is a Journal class object variable, which lets you access a Model 204 journal other than the current journal. If Journal is a Null object or is not specified, AppendJournalData uses the current Model 204 journal. This parameter is available as of Version 7.7 of the Sirius Mods.

Threads parameter

As mentioned, the third positional parameter, optionally named Threads, is a string that contains selection criteria for users for which audit trail data is to be formatted. The selection criteria can be a set of blank or comma delimited "phrases" each made up of one or more "clauses" separated by the & symbol. Each clause can contain one of the following criteria:

IODEVn	The number n indicates a specific IODEV type, as in IODEV15, IODEV7, or IODEV11.
PST	Entries for all Model 204 Pseudo-SubTasks.
n1.n2.n3.n4	An IP address for a Janus thread, as in 198.242.244.97 or 150.209.8.51. The IP address can also be followed by a slash (/) and a subnet mask, or by a hyphen (-) and a number of bits in a subnet mask, as in 198.242.244.0/255.255.255.0 or 198.242.244.0-24. These two subnetted IP addresses encompass the same set of IP addresses.
JAN:sss	The name of a Janus port, possibly containing wildcards, as in JAN:WEBPORT, JAN:WEB*, or JAN:???PORT.
xxx	A specific user number, as in 0, 233, or 1024.
xxx-yyy	A range of user numbers, as in 0-20 or 111-1000.
ssss	A string, possibly containing wildcards, that indicates a specific userid, as in RASPUTIN, RAS*, or ???PUTIN. For users in the ADMIN_xxx SCLASSes, a userid of just an asterisk (*) is special-cased to mean not only all logged on users, but all threads, whether logged on or not.

Criteria can be mixed and matched using the & (ampersand) separator, which indicates an "AND" operation, or using blanks or commas, which indicate an "OR" operation. For example:

IODEV15&LENIN 11-20

This requests information for all IODEV 15 threads logged on as userid LENIN, and requests all the information for user numbers 11 through 20.

With the following criteria:

TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST

You request information for all of the following:

• All connections from IP address 198.242.244.33 that log on a userid that begins with TROT
• All connections to Janus port SOCIALIST that log on to userid MARX
• All PSTs

Portnames and userids can contain special wildcard characters. These characters and their meanings are:

• * Matches any number of characters. For example, BRE* matches BREAD, BREEZY, and BREZHNEV.
• ? Matches a single character. For example, ?RUSHCHEV matches TRUSHCHEV, BRUSHCHEV, and KRUSHCHEV.
• " Means the next character is to be treated literally, even if it is wildcard character. Using the double-quotation character is necessary if a wildcard character appears in the name to be matched. For example, E"*BARTER matches E*BARTER.

Options parameter

As mentioned, the fourth positional parameter, optionally named Options, is an optional, case-sensitive string that contains a list of blank-delimited keywords that come from the following list. Your specification must include one or more audit trail types (ST, AA, AD, etc.).

AA	Non-stat audit entries are to be formatted. This includes AD, CI, CP, CS, ER, LI, LP, LR, LS, MS, OI, OO, RK, and US entries. For an explanation of the meaning of these entries, see Audit trail format. If AA is specified, it is redundant to also specify any of these other types.
AD	AD type entries are to be formatted.
CI	CI type entries are to be formatted.
CP	CP type entries are to be formatted.
CS	CS type entries are to be formatted.
DATE	The date associated with each audit trail entry should be included in the formatted output. The date is output in YYMMDD format, where YY is year, MM is month, and DD is day.
ER	ER type entries are to be formatted.
LI	LI type entries are to be formatted.
LP	LP type entries are to be formatted.
LR	LR type entries are to be formatted.
LS	LS type entries are to be formatted.
MAXIO=num	The maximum number of sequential full track I/O's to be performed against the journal in this call. This parameter can be used to prevent accidentally doing a large number of I/O's on the journal. The value for MAXIO must be between 1 (MAXIO=1) and 10,000,000 (MAXIO=10000000). Its default value is 100.
MAXREC=num	The maximum number of items to be allowed into the output Stringlist. This parameter can be used to prevent accidentally using a large amount of CCATEMP to hold the formatted output. The value for MAXREC must be between 1 (MAXREC=1) and 10,000,000 (MAXREC=10000000). Its default value is 1000. Prior to version 8.1 of the Sirius Mods, the largest value allowed for MAXREC was 1,000,000 (MAXREC=1000000).
MS	MS type entries are to be formatted.
NOSC	The SirScan RK lines produced for the SirScan SCANTIME feature (to facilitate identification of journal entries by userid or other criteria) are to be suppressed from the output Stringlist.
OI	OI type entries are to be formatted.
OO	OO type entries are to be formatted.
QT	QT type entries are to be formatted. QT is available as of version 7.5 of Model 204.
RK	RK type entries are to be formatted.
SEQ	Each output Stringlist item is to contain an eight-byte sequence number at the start. The SEQ parameter is followed by the starting sequence number and an an increment separated by a comma, as in SEQ=100,5, which means that the starting sequence number is 100, and the sequence numbers increment by 5. Note that the starting sequence number never actually appears, because the first Stringlist item causes it to be incremented. In the previous example, the first added Stringlist item would actually be 105. The starting sequence number can be omitted, in which case it is assumed to be 0, so SEQ=,1 causes sequence numbers to start at one and go up by one. The sequence numbers are always eight bytes long and padded on the left with zeros. If the sequence number exceeds 99999999, the leading decimal digits are simply discarded.
SERV	The server number of each audit trail entry is to be included in the formatted output.
ST	ST type entries are to be formatted.
TIME	The time associated with each audit trail entry is included in the formatted output. Time is output in HHMMSSTH format, where HH is hour, MM is minute, SS is second, T is tenths of a second, and H is hundredths of a second.
TYPE	The type of each audit trail entry is to be included in the formatted output. Type will be AD, CI, CP, CS, ER, LI, LP, LR, LS, MS, OI, OO, RK, or US for audit entries, and it will be ST for statistics entries.
US	US type entries are to be formatted. Blanks at the start of a line are not removed, and long user entries are a single US line with continuation lines that have no prefix and no label.
USER	The user number of each audit trail entry is to be included in the formatted output.
USESC	Use the RK lines produced for the SirScan SCANTIME feature (to facilitate identification of journal entries by userid or other criteria). This ensures that all journal records can be definitely identified with a userid, IP address, or Janus port. The cost of this completeness is that an extra SCANTIME seconds of the journal need to be scanned before the start time. Unless SCANTIME is set to an inadvisedly high value, the cost of this should be minor.
WIDTH=num	The maximum width for the output Stringlist items. If an audit trail entry will not fit in a single Stringlist item of this width, it is continued in the next item. The allowable range for width is 50 (WIDTH=50) through 255 (WIDTH=255).

Usage notes

• If the caller of AppendJournalData is not a System Administrator, an implicit selection filter is applied so that the caller will only see entries that were produced by a thread with the same userid as the caller. This condition is ANDed with any other filtering conditions.
  In the case of a historical journal (that is, a journal produced by a run other than the current run), the user must instantiate a Journal class object that references a stream. When that stream is opened, Model 204 ensures that the current user has Read access to the dataset(s) comprising the stream. A user whose security (ACF2, RACF etc) profile does not allow Read access is not allowed to issue the AppendJournalData method for that journal.
• If you want to use a journal other than the current one, its dataset(s) have to be allocated to your Online. You may need to use the Model 204 ALLOCATE or DEFINE STREAM commands.
• Under Sirius Mods Version 7.7, if you specify a journal other than the current one, it must be a journal created with the same Model 204 release as your current Online. If the releases are different, any AppendJournalData method call will silently fail to add any data to its output Stringlist. In Sirius Mods Version 7.8, an attempt to instantiate a Journal object variable that references a journal from a different version than the Online produces a BadJournal exception.

Examples

1. The following method invocation formats all non-stat audit trail entries for IODEV3 types between 10 a.m. and 2 p.m. on August 10, 2009 from the OLDJRNL historical journal:

   %list is object stringList ... %list = new %list:appendJournalData(startTime = '0922210000000', - endTime = '0922214000000', - threads = 'IODEV3', - options = 'AA', - journal = 'OLDJRNL')

2. The same result can be achieved without named parameters:

   %list is object stringList ... %list = new %list:appendJournalData('0922210000000', '0922214000000', - 'IODEV3', 'AA', 'OLDJRNL')
3. The following fragment shows how to extract journal records from the last 15 seconds:

   %list is object stringList %start is float ... %list = new %start = %(system):currentTimeMilliseconds - 15*1000 %list:appendJournalData(startTime = %start:millisecondsToString('YYDDDHHMISSXX'), - threads = 'IODEV3', - options = 'AA')

See also

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods