$SirJGet: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (minor cleanup)
 
(32 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Place audit trail data on $list</span>
<span class="pageSubtitle">Place audit trail data on $list</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $SirJGet function is the [[AppendJournalData (Stringlist function)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $SirJGet function is the <var>[[AppendJournalData (Stringlist function)|AppendJournalData]]</var> function.</p>


The $SirJGet function is used to retrieve audit trail data from the current <var class="product">Model 204</var> 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.  
The <var>$SirJGet</var> function is used to retrieve audit trail data from the current <var class="product">Model 204</var> journal stream and place it on a [[$lists|$list]]. <var>$SirJGet</var> is only available if a site has purchased [[SirScan]]. To invoke <var>$SirJGet</var>, you must have either system manager or system administrator privileges.  


$SirJGet accepts five arguments and returns a numeric code.
<var>$SirJGet</var> accepts five arguments and returns a numeric code.


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RESULT = $SirJGet(list_id, start_time, end_time,
<p class="syntax"><span class="term">%result</span> = <span class="literal">$SirJGet</span>(<span class="term">list_id</span>, [<span class="term">start_time</span>], [<span class="term">end_time</span>], <span class="term">user_list</span>, <span class="term">parms</span>)
user_list, parms)
<section end="syntax" /></p>
<p class="caption">$SirJGet Function
</p>
</p>
<p class="caption">%RESULT is set to indicate the success of the function.</p>


<table class="syntaxTable">
<table>
<tr><th>%result</th>
<td> A [[#Return codes|return code]] set to indicate the success of the function.</td></tr>
 
<tr><th>list_id</th>
<tr><th>list_id</th>
<td>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.</td></tr>
<td>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.</td></tr>
<tr><th>start_time</th>
<tr><th>start_time</th>
<td>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 <var class="product">Model 204</var> region was brought up.</td></tr>
<td>The start time for the journal data to be formatted in <code>YYDDDHHMISSXX</code> format (<code>YY</code> = year, <code>DDD</code> = Julian day number, <code>HH</code> = hour, <code>MI</code> = minutes, <code>SS</code> = seconds, <code>XX</code> = 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.  
<p>
If <var class="term">start_time</var> is not specified, the start time is considered to be the time that the <var class="product">Model 204</var> region was brought up.</p></td></tr>
 
<tr><th>end_time</th>
<tr><th>end_time</th>
<td>The end 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 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.</td></tr>
<td>The end time for the journal data to be formatted in <code>YYDDDHHMISSXX</code> 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.  
<p>
If <var class="term">end_time</var> is not specified, the end time is considered to be the current time.</p></td></tr>
 
<tr><th>user_list</th>
<tr><th>user_list</th>
<td>Selection criteria for users for which audit trail data is to be formatted. .im scansel</td></tr>
<td>[[#User selection criteria|Selection criteria]] for users for which audit trail data is to be formatted. </td></tr>
 
<tr><th>parms</th>
<tr><th>parms</th>
<td>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 the following list : .sr list = $list .im scanfmt
<td>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 [[#Formatting options for audit trail data|this option list]].</td></tr>
</td></tr></table>
</table>


<p class="code">  
===Return codes===
0 - No errors
<p class="code"> 0 - No errors
  1 - MAXREC exceeded ($list might contain new records)
  1 - MAXREC exceeded ($list might contain new records)
  2 - MAXIO exceeded ($list might contain new records)
  2 - MAXIO exceeded ($list might contain new records)
  3 - CCATEMP full (if LISTFC $SirParm parameter not set)
  3 - CCATEMP full (if LISTFC <var>$SirParm</var> parameter not set)
  4 - Out of virtual storage
  4 - Out of virtual storage
  6 - $List identifier missing
  6 - $List identifier missing
Line 39: Line 46:
  8 - Invalid parameter (argument 5)
  8 - Invalid parameter (argument 5)
  9 - Invalid start or end time (argument 2 or 3)
  9 - Invalid start or end time (argument 2 or 3)
10 - No audit trail types selected (ST, AA, AD, etc..)
10 - No audit trail types selected (ST, AA, AD, etc..)
</p>
</p>
<p class="caption">$SirJGet return codes
 
===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 <code>&amp;</code> symbol.
Each clause can contain one of the following criteria:
 
<table>
<tr><th><var>IODEV</var>n</th>
<td>A number <i><b>n</b></i> indicating a specific IODEV type, as in IODEV15, IODEV7, or IODEV11.</td></tr>
 
<tr><th><var>PST</var></th>
<td>Entries for all <var class="product">Model 204</var> Psuedo-SubTasks.</td></tr>
 
<tr><th>n1.n2.n3.n4</th>
<td>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 <code>198.242.244.0/255.255.255.0</code> or <code>198.242.244.0-24</code>. These two subnetted IP addresses encompass the same set of IP addresses.</td></tr>
 
<tr><th><var>JAN:</var>sss</th>
<td>The name of a Janus port, possibly containing wildcards, as in <code>JAN:WEBPORT</code>, <code>JAN:WEB*</code>, or <code>JAN:???PORT</code>.</td></tr>
 
<tr><th>xxx</th>
<td>A specific user number, as in 0, 233, or 1024.</td></tr>
 
<tr><th>xxx-yyy</th>
<td>A range of user numbers, as in 0-20 or 111-1000.</td></tr>
 
<tr><th>ssss</th>
<td>A string, possibly containing wildcards, that indicates a specific userid, as in <code>RASPUTIN</code>, <code>RAS*</code>, <code>???PUTIN</code>. 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.</td></tr>
</table>
Criteria can be mixed and matched using the <code>&amp;</code> separator, which
indicates an "AND" operation, or using blanks or commas, which indicate
an "OR" operation.
For example
<p class="code">IODEV15&amp;LENIN 11-20
</p>
</p>
requests information for all IODEV 15 threads logged on as
userid <code>LENIN</code>, and requests all the information for user numbers 11
through 20.
<p class="code">TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST
</p>
requests information for all of the following:
<ul>
<li>All connections from IP address
198.242.244.33 that log on a userid that begins with <code>TROT</code>
<li>All connections to Janus port <code>SOCIALIST</code> that log
on to userid <code>MARX</code>
<li>All PSTs
</ul>
Portnames and userids can contain special wildcard characters.
These characters and their meanings are:
<table>
<tr><th><var>*</var></th>
<td>Matches any number of characters. For example, <code>BRE*</code> matches <code>BREAD</code>, <code>BREEZY</code>, and <code>BREZHNEV</code>.</td></tr>


<tr><th><var>?</var></th>
<td>Matches a single character. For example, <code>?RUSHCHEV</code> matches <code>TRUSHCHEV</code>, <code>BRUSHCHEV</code>, and <code>KRUSHCHEV</code>.</td></tr>
<tr><th><var>"</var></th>
<td>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, <code>E"*BARTER</code> matches <code>E*BARTER</code>.</td></tr>
</table>
===Formatting options for audit trail data===
<table>
<tr><th><var>AA</var></th>
<td>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 [[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#Audit trail format|Audit trail format]]. If <code>AA</code> is specified, it is redundant to also specify any of these other types.</td></tr>
<tr><th><var>AD</var></th>
<td>AD type entries are to be formatted.</td></tr>
<tr><th><var>CI</var></th>
<td>CI type entries are to be formatted.</td></tr>
<tr><th><var>CP</var></th>
<td>CP type entries are to be formatted.</td></tr>
<tr><th><var>CS</var></th>
<td>CS type entries are to be formatted.</td></tr>
<tr><th><var>DATE</var></th>
<td>The date associated with each audit trail entry should be included in the formatted output. The date is output in <code>YYMMDD</code> format, where <code>YY</code> is year, <code>MM</code> is month, and <code>DD</code> is day.</td></tr>
<tr><th><var>ER</var></th>
<td>ER type entries are to be formatted.</td></tr>
<tr><th><var>LI</var></th>
<td>LI type entries are to be formatted.</td></tr>
<tr><th><var>LP</var></th>
<td>LP type entries are to be formatted.</td></tr>
<tr><th><var>LR</var></th>
<td>LR type entries are to be formatted.</td></tr>
<tr><th><var>LS</var></th>
<td>LS type entries are to be formatted.</td></tr>
<tr><th><var>MAXIO=</var>num</th>
<td>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 <var>MAXIO</var> must be between 1 (<code>MAXIO=1</code>) and 10,000,000 (<code>MAXIO=10000000</code>).Its default value is <code>100</code>.</td></tr>
<tr><th><var>MAXREC=</var>num</th>
<td>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 <var>MAXREC</var> must be between 1 (<code>MAXREC=1</code>) and 10,000,000 (<code>MAXREC=10000000</code>). Its default value is <code>1000</code>.</td></tr>
<tr><th><var>MS</var></th>
<td>MS type entries are to be formatted.</td></tr>
<tr><th><var>NOSC</var></th>
<td>The <var class="product">SirScan</var> RK lines produced for the <var class="product">SirScan</var> SCANTIME feature (to facilitate identification of journal entries by userid or other criteria) are to be suppressed from the output $list.</td></tr>
<tr><th><var>OI</var></th>
<td>OI type entries are to be formatted.</td></tr>
<tr><th><var>OO</var></th>
<td>OO type entries are to be formatted.</td></tr>
<tr><th><var>RK</var></th>
<td>RK type entries are to be formatted.</td></tr>
<tr><th><var>SEQ</var></th>
<td>Each output $list item is to contain an eight-byte sequence number at the start. The <var>SEQ</var> parameter is followed by the starting sequence number and an an increment separated by a comma, as in <code>SEQ=100,5</code>, 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 <code>SEQ=,1</code> 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.
</td></tr>
<tr><th><var>SERV</var></th>
<td>The server number of each audit trail entry is to be included in the formatted output.</td></tr>
<tr><th><var>ST</var></th>
<td>Statistics entries are to be formatted.</td></tr>
<tr><th><var>TIME</var></th>
<td>The time associated with each audit trail entry is included in the formatted output. Time is output in <code>HHMMSSTH</code> format, where <code>HH</code> is hour, <code>MM</code> is minute,<code>SS</code> is second, <code>T</code> is tenths of a second, and <code>H</code> is hundredths of a second.</td></tr>
<tr><th><var>TYPE</var></th>
<td>The type of each audit trail entry is to be included in the formatted output. Type will be <var>AD</var>, <var>CI</var>, <var>CP</var>, <var>CS</var>, <var>ER</var>, <var>LI</var>, <var>LP</var>, <var>LR</var>, <var>LS</var>, <var>MS</var>, <var>OI</var>, <var>OO</var>, <var>RK</var>, or <var>US</var> for audit entries, and it will be <var>ST</var> for statistics entries.</td></tr>
<tr><th><var>US</var></th>
<td>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.</td></tr>
<tr><th><var>USER</var></th>
<td>The user number of each audit trail entry is to be included in the formatted output.</td></tr>
<tr><th><var>USESC</var></th>
<td>Use the RK lines produced for the <var class="product">SirScan</var> 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.</td></tr>
<tr><th><var>WIDTH=</var>num</th>
<td>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 (<code>WIDTH=50</code>) through 255 (<code>WIDTH=255</code>).</td></tr></table>
==Example==
The following statement formats all non-stat audit trail entries for IODEV3's between 10 AM and 2 PM on March 12, 1993:
The following statement formats all non-stat audit trail entries for IODEV3's between 10 AM and 2 PM on March 12, 1993:


<p class="code"> %RC = $SirJGet(%LIST, '9306310000000', '9306314000000', -
<p class="code">%RC = $SirJGet(%LIST, '9306310000000', '9306314000000', 'IODEV3', 'AA')
'IODEV3', 'AA')
</p>
</p>


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[SirScan]]
<li>[[SirScan]]
</ul>
</ul>
<p class="caption">Products authorizing $SirJGet
</p>


[[Category:$Functions|$SirJGet]]
[[Category:$Functions|$SirJGet]]

Latest revision as of 22:50, 6 October 2015

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