$SirJGet

Place audit trail data on $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $SirJGet function is the AppendJournalData function.

The $SirJGet function is used to retrieve audit trail data from the current Model 204 journal stream and place it on a $list. $SirJGet is only available if a site has purchased SirScan. To invoke $SirJGet, you must have either system manager or system administrator privileges.

$SirJGet accepts five arguments and returns a numeric code.

Syntax

%result = $SirJGet(list_id, [start_time], [end_time], user_list, parms)

%result	A return code set to indicate the success of the function.
list_id	The identifier of the $list that is to receive the formatted audit trail data. The audit trail data is appended to the current contents of the indicated $list. This is a required argument.
start_time	The start time for the journal data to be formatted 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. If start_time is not specified, the start time is considered to be the time that the Model 204 region was brought up.
end_time	The end time for the journal data to be formatted in YYDDDHHMISSXX format. 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. If end_time is not specified, the end time is considered to be the current time.
user_list	Selection criteria for users for which audit trail data is to be formatted.
parms	A list of parameters indicating how the audit trail data is to be formatted. This argument is a list of blank delimited keywords that come from this option list.

Return codes

0 - No errors 1 - MAXREC exceeded ($list might contain new records) 2 - MAXIO exceeded ($list might contain new records) 3 - CCATEMP full (if LISTFC $SirParm parameter not set) 4 - Out of virtual storage 6 - $List identifier missing 7 - Invalid $list identifier 8 - Invalid parameter (argument 5) 9 - Invalid start or end time (argument 2 or 3) 10 - No audit trail types selected (ST, AA, AD, etc..)

User selection criteria

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	A number n indicating a specific IODEV type, as in IODEV15, IODEV7, or IODEV11.
PST	Entries for all Model 204 Psuedo-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*, ???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 & separator, which indicates an "AND" operation, or using blanks or commas, which indicate an "OR" operation. For example

IODEV15&LENIN 11-20

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

TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST

requests 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.

Formatting options for audit trail data

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 &list. items to be allowed into the output $list. 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.
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 $list.
OI	OI type entries are to be formatted.
OO	OO type entries are to be formatted.
RK	RK type entries are to be formatted.
SEQ	Each output $list 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 $list item causes it to be incremented. In the previous example, the first added $list 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	Statistics 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. Initial blanks are not removed, and long 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 $list items. If an audit trail entry will not fit in a single $list item of this width, it is continued in the next $list item. The allowable range for width is 50 (WIDTH=50) through 255 (WIDTH=255).

Example

The following statement formats all non-stat audit trail entries for IODEV3's between 10 AM and 2 PM on March 12, 1993:

%RC = $SirJGet(%LIST, '9306310000000', '9306314000000', 'IODEV3', 'AA')

Products authorizing $SirJGet

• SirScan